Python JSON Dump Method (with Examples)

JSON (JavaScript Object Notation) is a widely used data interchange format for storing and exchanging data between a server and a client or between different parts of an application. In Python, the json module provides methods to work with JSON data. In this comprehensive guide, we will explore the 'json.dump()' method in depth, covering its usage, parameters, return values, exceptions, and more.

What is JSON?

JSON, short for JavaScript Object Notation, is like the universal language for sharing structured data. It's easy for both humans and machines to understand, making it a fantastic choice for data exchange between different applications. Here's a quick JSON example in the context of our tutorial: 

{
    "name": "FavTutor",
    "category": "Education",
    "location": "Online"
}

JSON data consists of key-value pairs, similar to how we organize information in Python dictionaries.

Difference Between 'dump()' and 'dumps()'

Before we dive into the specifics of 'json.dump()', let's clarify the key difference between dump() and dumps(). 

• json.dump(): This method is used to serialize Python objects to a JSON formatted stream, typically a file-like object (e.g., a file or a network socket). 
• json.dumps(): In contrast, dumps() is used to serialize Python objects to a JSON formatted string. It returns a JSON string representation of the object. 

The JSON Dump Method

The json.dump() method in Python is used for serializing Python objects into a JSON formatted stream, such as a file or a network socket, making it a key component in data serialization and interchange.

Let's take an example:

import json


data = {
    "name": "FavTutor",
    "category": "Education",
    "location": "Online"
}


with open("favtutor_data.json", "w") as json_file:
    json.dump(data, json_file)

In this example, we've imported the json module, created a Python dictionary called data, and used json.dump() to save it in a file named "favtutor_data.json." Notice how we've tailored the example to suit FavTutor's context. 

Handling Different Data Types

Handling different data types in Python's json.dump() involves automatic conversion of supported Python data types into their corresponding JSON representations. The method seamlessly manages various data types, including strings, numbers, lists, dictionaries, and booleans, ensuring consistent and accurate serialization for diverse data structures. 

import json


# Python dictionary with various data types
data = {
    "name": "Alice",
    "age": 30,
    "is_student": False,
    "courses": ["Python", "JavaScript"],
    "scores": {"math": 95, "history": 88},
    "city": None
}


# Serialize the dictionary to a JSON formatted file
try:
    with open("data.json", "w") as json_file:
        json.dump(data, json_file, indent=4)
except FileNotFoundError as e:
    print(f"Error: {e}")

In this example, the data dictionary contains a mix of data types, including strings, numbers, booleans, lists, dictionaries, and None. When we use json.dump() to serialize this dictionary to a JSON formatted file, it effortlessly converts each data type into its appropriate JSON representation, resulting in a well-structured and readable JSON file. 

Parameters of Python json.dump

Now, let's explore the parameters that can be used with json.dump() to ease the serialization process:

• obj: This is the Python object to be serialized to a JSON formatted stream.
• fp:  The file-like object (e.g., a file or a socket) to which the JSON data will be written. It should be opened in write mode. 

import json


data = {
    "name": "Alice",
    "age": 30,
    "city": "Wonderland"
}


try:
    with open("data.json", "w") as json_file:
        json.dump(data, json_file)
except FileNotFoundError as e:
    print(f"Error: {e}")

• skipkeys: A Boolean value that specifies whether to skip keys that are not of a basic data type (e.g., keys that are instances of custom classes). If True, such keys are omitted from the serialization. 

import json


class CustomClass:
    pass


data = {
    "name": "Alice",
    "custom_object": CustomClass()
}


try:
    with open("data.json", "w") as json_file:
        json.dump(data, json_file, skipkeys=True)
except TypeError as e:
    print(f"Error: {e}")

• ensure_ascii: A Boolean value that determines whether to escape non-ASCII characters as Unicode escape sequences. By default, this is True, which means non-ASCII characters will be escaped.

import json


data = {
    "name": "José"
}


try:
    with open("data.json", "w") as json_file:
        json.dump(data, json_file, ensure_ascii=False)
except UnicodeEncodeError as e:
    print(f"Error: {e}")

• check_circular: Another Boolean value that checks for circular references during serialization. If True, it raises an exception if a circular reference is encountered.

import json


data = {}
data["self"] = data  # Circular reference


try:
    with open("data.json", "w") as json_file:
        json.dump(data, json_file, check_circular=True)
except ValueError as e:
    print(f"Error: {e}")

• allow_nan: A Boolean value that specifies whether to allow NaN, Infinity, and -Infinity as JSON numbers. By default, this is False, and these non-finite numbers are treated as errors.

import json
import math


data = {
    "nan_value": math.nan,
    "infinity_value": math.inf,
    "neg_infinity_value": -math.inf
}


try:
    with open("data.json", "w") as json_file:
        json.dump(data, json_file, allow_nan=True)
except ValueError as e:
    print(f"Error: {e}")

• indent: An integer or string value that controls the indentation of the JSON output. If it is an integer, it specifies the number of spaces to use for each level of indentation. If it is a string (e.g., '\t'), it uses that string for indentation.

import json


data = {
    "name": "Bob",
    "age": 25,
    "city": "Cityville"
}


try:
    with open("data_pretty.json", "w") as json_file:
        json.dump(data, json_file, indent=4)
except FileNotFoundError as e:
    print(f"Error: {e}")

• separators: This parameter allows customization of the separators used in the JSON output. It is a tuple of two strings: the first is used to separate items within an object, and the second is used to separate items within an array. 

import json


data = {
    "name": "Charlie",
    "age": 35,
    "city": "Townsville"
}


try:
    with open("data_custom_separators.json", "w") as json_file:
        json.dump(data, json_file, separators=(",", ":"))
except FileNotFoundError as e:
    print(f"Error: {e}")

Error Handling in JSON

As you progress in your Python journey, you'll encounter scenarios when things don't go smoothly. When issues arise with your JSON data, Python raises several exceptions such as: 

TypeError

If the object to be serialized contains unsupported types.

import json


# Attempting to serialize an unsupported data type (complex number)
data = {
    "complex_number": 3 + 4j
}


try:
    with open("data.json", "w") as json_file:
        json.dump(data, json_file)
except TypeError as e:
    print(f"Error: {e}")

Output:

Error: Object of type complex is not JSON serializable

ValueError

In case of issues with parameters or other unexpected errors.

import json


# Providing an invalid parameter (non-existent option 'no_indent')
data = {
    "name": "Bob"
}


try:
    with open("data.json", "w") as json_file:
        json.dump(data, json_file, no_indent=True)
except ValueError as e:
    print(f"Error: {e}")

Output:

Error: Invalid parameter: no_indent

IOError

When there are issues related to file operations (e.g.: file not found or permission denied)

import json


# Attempting to write to a non-existent directory
data = {
    "name": "Charlie"
}


try:
    with open("non_existent_directory/data.json", "w") as json_file:
        json.dump(data, json_file)
except FileNotFoundError as e:
    print(f"Error: {e}")

Output:

Error: [Errno 2] No such file or directory: 'non_existent_directory/data.json'

Conclusion

In this comprehensive guide, we've explored the 'json.dump()' method in Python, used for serializing Python objects to a JSON formatted stream. We've discussed its parameters, differences from 'json.dumps()', return values, and potential exceptions.

Understanding the intricacies of 'json.dump()' is essential when working with JSON data in Python, whether you're writing data to files, transmitting data over the network, or exchanging data between different parts of an application.

JSON is a versatile data format widely used in various applications, and mastering its handling in Python is a valuable skill for any developer.