JSON Files — dump & load

By the end of this lesson you can:

• Save a Python dict or list to a .json file with json.dump.
• Load it back with json.load.
• Read and write JSON strings with json.dumps / json.loads.
• Use the indent=2 argument to write pretty-printed (human-readable) JSON.
• Recognise the Python ↔ JSON type mapping.

Watch a Python dict survive a write/read cycle:

import json

# 1 — save
data = {
    "name": "Aisyah",
    "age": 12,
    "subjects": ["maths", "art"],
    "address": {"city": "KL", "postcode": "50480"},
}

with open("profile.json", "w", encoding="utf-8") as f:
    json.dump(data, f, indent=2)

# 2 — read back
with open("profile.json", encoding="utf-8") as f:
    loaded = json.load(f)

print(loaded == data)         # → True
print(loaded["address"]["city"])    # → KL

Two function calls. The data goes out as text, comes back as the same dict. Nested structure survives intact.

The four functions

json.dump(data, file)         Write data to an OPEN file
json.load(file)                Read data from an OPEN file

json.dumps(data)               Convert data to a STRING
json.loads(s)                  Parse a JSON STRING into data

Notice the s. dump/load work with file objects; dumps/loads work with strings. The data direction is the same.

The Python ↔ JSON type map

Python              JSON
dict                object {...}
list / tuple        array [...]
str                 string "..."
int                 number
float               number
True / False        true / false
None                null

Notice tuples become arrays — and come back as lists. Sets and custom objects don't survive at all (you'll get TypeError: Object of type set is not JSON serializable). Convert sets to lists before saving.

Pretty-print with indent

json.dump(data, f, indent=2)
# In the file:
# {
#   "name": "Aisyah",
#   "age": 12,
#   "subjects": [
#     "maths",
#     "art"
#   ]
# }

json.dump(data, f)
# All on one line:
# {"name": "Aisyah", "age": 12, "subjects": ["maths", "art"]}

Use indent=2 when humans will read the file. Skip it for machine-only data (faster, smaller).

Unicode safety

By default, json.dump escapes non-ASCII characters. For Malay or other languages with accents, pass ensure_ascii=False:

data = {"name": "Saïd", "city": "Kuala Lumpur 🇲🇾"}

# Default (ASCII-only, ugly)
json.dump(data, f)
# {"name": "Sa\u00efd", "city": "Kuala Lumpur \ud83c\udde6..."}

# Better
json.dump(data, f, ensure_ascii=False)
# {"name": "Saïd", "city": "Kuala Lumpur 🇲🇾"}

The string flavour · for APIs

# Serialise to a string — useful when sending to an HTTP API
s = json.dumps({"event": "login", "user": "aisyah"})
print(s)   # → {"event": "login", "user": "aisyah"}

# Deserialise from a string — useful when receiving from an API
incoming = '{"status": "ok", "items": [1, 2, 3]}'
data = json.loads(incoming)
print(data["items"])    # → [1, 2, 3]

Error handling

Bad JSON → json.JSONDecodeError. Wrap it.

try:
    with open("config.json", encoding="utf-8") as f:
        config = json.load(f)
except FileNotFoundError:
    config = {}                    # first run
except json.JSONDecodeError as e:
    print(f"Corrupt config: {e}")
    config = {}

Re-do PY-L2-22's high-score keeper with JSON instead of CSV-ish lines. Way cleaner.

# hi_score_json.py — high scores stored as JSON

import json

FILE = "scores.json"

def load_scores():
    try:
        with open(FILE, encoding="utf-8") as f:
            return json.load(f)
    except FileNotFoundError:
        return []
    except json.JSONDecodeError:
        print("Score file corrupt — starting fresh.")
        return []

def save_scores(scores):
    with open(FILE, "w", encoding="utf-8") as f:
        json.dump(scores, f, indent=2)

def add_score(scores, name, score, top_n=5):
    scores.append({"name": name, "score": score})
    scores.sort(key=lambda s: s["score"], reverse=True)
    del scores[top_n:]
    save_scores(scores)
    return scores

# Demo
scores = load_scores()
print("Loaded:", scores)

scores = add_score(scores, "Aisyah", 92)
scores = add_score(scores, "Wei Jie", 88)
scores = add_score(scores, "Priya", 95)

print("After:", scores)

scores.json after running

[
  {
    "name": "Priya",
    "score": 95
  },
  {
    "name": "Aisyah",
    "score": 92
  },
  {
    "name": "Wei Jie",
    "score": 88
  }
]

Read the diff

Compare to PY-L2-22's version. The whole "parse a line into a dict" logic is gone — json.load hands you the list of dicts directly. The save is even cleaner — json.dump(scores, f, indent=2) writes the whole list at once, pretty-printed. Whole data structures move as a unit — that's JSON's superpower.

JSON saves whole Python data structures with one function call. json.dump writes to a file; json.load reads. json.dumps/json.loads use strings (for APIs). Use indent=2 for human-readable files. Sets and custom objects don't survive — convert to lists/dicts before saving. The load → mutate → save pattern is the basis of every persistent app you'll write from now on.