JSON Files: Saving Your Data

JSON is a text format for data that json.dump and json.load turn Python's dictionaries and lists into and back from, through a file, while json.dumps and json.loads do the same with a string, which is how web APIs send their answers.

Apprentice · Python · Updated

By

After this lesson you can

  • Save Python data to a JSON file with json.dump and load it back with json.load
  • Turn data into JSON text and back with json.dumps and json.loads, and say which Python values JSON can hold

Key takeaways

  • JSON is a text format for data, with objects in curly braces, lists in square brackets, text in double quotes, numbers, true, false and null.
  • json.dump(data, file) writes Python data to an open file as JSON, and json.load(file) reads it back as the same dictionaries and lists.
  • json.dumps() turns data into a JSON string and json.loads() turns a JSON string into data, which is how a web API's answer is read.
  • indent=2 spreads the JSON over several lines, two spaces deeper for each level, so a person can read it.
  • A tuple comes back from JSON as a list and a number key as text, and a set can't be saved at all.

A program's data is rarely a few lines of text. It's a dictionary of settings, a list of contacts, a game's saved state: data with a shape. To keep it between runs, or send it to another program, you need a way to write that shape down and read it back exactly. JSON is that way, and it's everywhere: settings files, saved data, and almost every answer a web API sends.

The example is the Riverbend Running Club's goals: how many miles each member plans to run in a week.

Saving a dictionary as text

The goals are a dictionary. Writing it to a text file with str() looks like it works:

goals = {"Priya": 15, "Marcus": 20}

with open("goals.txt", "w", encoding="utf-8") as file:
    file.write(str(goals))

with open("goals.txt", encoding="utf-8") as file:
    loaded = file.read()

print(loaded)
print(type(loaded))
{'Priya': 15, 'Marcus': 20}
<class 'str'>

open() with "w" writes the file and with no mode reads it, and the with block closes the file when its lines are done. What comes back looks like the dictionary, but type() says it's a string: loaded["Priya"] stops with a TypeError, because a string's characters are found by number. Turning the text back into a dictionary would mean taking it apart character by character.

What JSON looks like

JSON (read "jay-son", short for JavaScript Object Notation) is a way of writing data as text that programs in every language can read back. The club's goals, with each member's races, look like this in JSON:

{
  "Priya": {"weekly_miles": 15, "races": ["Riverbend 5K"]},
  "Marcus": {"weekly_miles": 20, "races": []}
}

It looks a lot like Python, with a few differences in spelling:

Python JSON
dict, {"Priya": 15} object, {"Priya": 15}
list, ["Riverbend 5K"] array, ["Riverbend 5K"]
str, "Priya" or 'Priya' string, "Priya" (double quotes only)
int and float, 15, 4.5 number, 15, 4.5
True, False true, false
None null

Saving and loading with json.dump and json.load

Python's built-in json module writes and reads JSON for you. import json brings it in:

import json

goals = {
    "Priya": {"weekly_miles": 15, "races": ["Riverbend 5K"]},
    "Marcus": {"weekly_miles": 20, "races": []},
}

with open("goals.json", "w", encoding="utf-8") as file:
    json.dump(goals, file, indent=2)

with open("goals.json", encoding="utf-8") as file:
    loaded = json.load(file)

print(loaded["Priya"]["races"][0])
print(loaded == goals)
Riverbend 5K
True

json.dump(goals, file) writes the dictionary into the open file as JSON, and json.load(file) reads it back as a real dictionary, lists inside it and all, equal to the one that was saved. indent=2 lays the file out over several lines, each level two spaces deeper than the one around it, so goals.json reads like this:

{
  "Priya": {
    "weekly_miles": 15,
    "races": [
      "Riverbend 5K"
    ]
  },
  "Marcus": {
    "weekly_miles": 20,
    "races": []
  }
}

Without indent, the whole file is one long line: fine for a program, hard for a person.

JSON as a string: dumps and loads

Sometimes the JSON isn't in a file: a web API sends its answer as JSON text, and a program may want JSON text to print or send. json.dumps() and json.loads() do the same jobs with a string (the s is for string):

import json

goals = {"Priya": 15, "Marcus": 20}
print(json.dumps(goals))

answer = '{"runner": "Luis", "miles": 2.6, "finished": true, "medal": null}'
run = json.loads(answer)
print(run["miles"] + 1)
print(run["finished"], run["medal"])
{"Priya": 15, "Marcus": 20}
3.6
True None

json.loads() turned the text into a dictionary, so run["miles"] is a number you can add to, and JSON's true and null came back as Python's True and None.

JSON holds only what the table shows, so some values change shape on the way through. A tuple is saved as an array and comes back as a list. A dictionary's keys are always strings in JSON, so a key of 1 comes back as "1". A set has no JSON spelling at all: json.dumps({"Riverbend 5K"}) stops with TypeError: Object of type set is not JSON serializable. Turn it into a list first, with list().

Do it: update one member's goal

The club keeps every member's weekly goal in a JSON file: an object with each member's name and their goal in miles, such as {"Priya": 15, "Marcus": 20}. A member changes their goal, and the file has to be changed to match.

  • path: the JSON file's name. The file is already there.
  • runner: the member's name.
  • miles: their new weekly goal.

Your job: write the function set_goal(path, runner, miles) so it loads the goals from the file at path, sets runner's goal to miles, saves all the goals back to the same file, and returns the updated dictionary.

  • Load with json.load and save with json.dump, opening the file with encoding="utf-8" each time.
  • A member who's already in the file gets their new goal; everyone else keeps theirs.
  • A member who isn't in the file yet is added.

Worked through: the file holds {"Priya": 15, "Marcus": 20}. set_goal("goals.json", "Marcus", 25) loads that dictionary, changes Marcus's goal to 25, saves it, and returns {"Priya": 15, "Marcus": 25}, which is now what the file holds too.

Practiced live on the lesson page: write the Python right there and check it.

Check yourself

2 questions to try on the lesson page.

So what

JSON is how programs save their data and how they talk to each other, so json.dump, json.load, dumps and loads are the four lines that connect your program to files, settings and web APIs alike.

Key terms

Related