JSON Files

Instruction

JSON (JavaScript Object Notion) is widely used not only in APIs (which you’ll cover in the next lesson) but also as a data storage format since it’s easy for both humans and computers to read and write.

Although JSON is based on JavaScript’s syntax, its arrays and objects are so similar to Python’s lists and dictionaries that converting between them is pretty simple.

Reading JSON Files

Just as there’s a csv module in the Python Standard Library for working with CSV data, there’s also a json module for doing the same with JSON data.

To read a JSON file, you create a file object, just as you would when opening a text or CSV file. Once created, you pass the file object as an argument to the json.load() method.

import json

with open("some-file.json", "r") as file:
  data = json.load(file)

print(data)

JSON’s data structures translate almost directly into Python data structures:

JSON objects are unordered collections of key-value pairs. When read from a file, they’re converted into their Python equivalent: dictionaries. JSON arrays are ordered collections of values, and when read from a file, they’re converted into their Python equivalent: lists.

Nested JSON structures are also translated into their Python equivalents.

For example, if you had created the JSON file, some-file.csv, as a Python data structure that contained the following:

[
  {
    "name": "Python",
    "creator": "Guido van Rossum",
    "year_appeared": 1991
  },
  {
    "name": "Swift",
    "creator": "Chris Lattner",
    "year_appeared": 2014
  },
  {
    "name": "Kotlin",
    "creator": "Jetbrains",
    "year_appeared": 2011
  }
]

The code’s output would look like this:

[{'name': 'Python', 'creator': 'Guido van Rossum', 'year_appeared': 1991},
 {'name': 'Swift', 'creator': 'Chris Lattner', 'year_appeared': 2014},
 {'name': 'Kotlin', 'creator': 'Jetbrains', 'year_appeared': 2011}]

The JSON file and its equivalent Python data structure are so similar that they’re hard to tell apart. The one obvious giveaway is that JSON spells boolean values in all-lowercase letters,true and false, while Python spells them as capitalized words, True and False. Fortunately, Python’s json module methods convert boolean values to the correct form.

Handling Decoding Errors

There’s always a chance that the JSON file might not be formatted appropriately. In practice, you’ll want to wrap your file-reading code inside a try block to catch a JSON decoding error, along with other errors that are likely to happen while reading files, as shown below:

import json

try:
  with open('some-file.json', 'r') as file:
    data = json.load(file)
    print(data)
except json.JSONDecodeError as e:
  print(f"JSON decoding error: {e}")
except FileNotFoundError:
  print("File not found.")

If the JSON file is malformed, the code above will output JSON decoding error:, followed by the specific error, which will often include the line and column in the file where it became unable to decode the JSON.

Writing JSON Files

To write data to a JSON file, you need to:

1. First, put it into a data structure — a list or a dictionary — because JSON doesn’t support individual values. You can ignore this step if the data is already in a data structure.
2. Open a file using the open() function, preferably in combination with the with keyword.
3. Using the file object created by the open() function, use the json.dump() method to write the data to the file, automatically converting it into JSON in the process.

Here’s a quick example. This code:

import json

data = {
  "name": "C",
  "creator": "Dennis Ritchie",
  "year_appeared": 1972
}

with open("another-file.json", "w") as file:
  json.dump(data, file)

Produces a file named another-file.json with the following contents:

{"name": "C", "creator": "Dennis Ritchie", "year_appeared": 1972}

json.dump() has several optional parameters. The indent parameter lets you specify that the JSON should be pretty-printed and the depth of the indentation. For example, if you change the call to json.dump() in the code above to the following:

  json.dump(data, file, indent=4)

The resulting JSON file’s contents will look like this, with four spaces for each level of indentation:

data = {
  "name": "C",
  "creator": "Dennis Ritchie",
  "year_appeared": 1972
}

You may also find these optional parameters useful:

• ensure_ascii: When left at its default value, True, it escapes any non-ASCII characters. If you want to preserve characters outside the ASCII set, which includes emoji, use this parameter and set its value to False.
• sort_keys: When left at its default value, False, it writes the JSON output keys in the same order as the keys in the Python data structure. If you want to write the JSON file with its keys sorted in ascending alphabetical order, use this parameter and set its value to True.

Working With JSON Strings

In addition to providing ways to read and write to JSON files, the json module also provides methods for reading and writing data from and to JSON strings.

The json.loads() method can take a string and parse it into a Python data structure. Note that it’s loads(), not load(); the trailing “s” stands for “string”. Here’s an example:

import json

json_string = '''
{
  "name": "Ruby",
  "creator": "Yukihiro Matsumoto",
  "year_appeared": 1995
}
'''
data = json.loads(json_string)
print(data)

The json.dumps() method, again, note the trailing “s”, can take a Python data structure and encode it into a JSON string. Here’s an example:

import json

data = {
  "name": "Perl",
  "creator": "Larry Wall",
  "year_appeared": 1987
}
json_string = json.dumps(data, indent=4)
print(json_string)

Here’s the output of the above code:

{
  "name": "Perl",
  "creator": "Larry Wall",
  "year_appeared": 1987
}