Tutorials Python Python Working with JSON
Ch 39 / 58
Python Intermediate 13 min read Chapter 39 of 58

Python Working with JSON

JSON (JavaScript Object Notation) is the universal language of the web — every REST API, config file, and web service communicates in JSON. Python's built-in json module makes encoding and decoding JSON effortless. This chapter is a complete deep-dive: converting Python objects to JSON strings and back, reading and writing JSON files, working with nested structures, pretty-printing, handling edge cases, custom serialisation for objects that JSON can't handle natively, and real-world API patterns.

What you'll learn in this chapter
What JSON is and Python ↔ JSON type mapping
json.dumps() and json.loads() — encode/decode strings
json.dump() and json.load() — read/write files
Pretty printing, sorting keys, indentation
Custom serialisation — dates, classes, Decimal
Real-world REST API and config file patterns
Advertisement

What is JSON and Why Does it Matter?

JSON (JavaScript Object Notation) is a lightweight, text-based data format that is language-independent and human-readable. It's the standard for web APIs, configuration files, NoSQL databases, and inter-service communication. Every Python developer works with JSON daily.

Python ↔ JSON encode/decode flow
Python object: {"name": "Alice", "age": 25, "active": True}
▼
json.dumps() — ENCODE (serialise)
JSON string: '{"name": "Alice", "age": 25, "active": true}'
▼
json.loads() — DECODE (deserialise)
Python object: {"name": "Alice", "age": 25, "active": True}
Python Type JSON Equivalent
dict object  {}
list, tuple array  []
str string  ""
int, float number
True / False true / false
None null
datetime, set, bytes… ❌ Not natively supported
JSON key rules JSON only supports string keys. Python dict keys can be any hashable type, but when serialised to JSON, all keys are converted to strings. JSON keys are always double-quoted (not single-quoted like Python strings often are).

Encoding — json.dumps() Python → JSON String

json.dumps(obj) serialises a Python object to a JSON-formatted string. The "s" stands for "string". Use this when you need to send JSON over a network, store it in a variable, or embed it in code.

Python — json_dumps.py
import json

# ── Basic types ───────────────────────────────────────
print(json.dumps({"name": "Alice", "age": 25}))
# '{"name": "Alice", "age": 25}'

print(json.dumps([1, 2, "three", True, None]))
# '[1, 2, "three", true, null]'

print(json.dumps(True))    # 'true'  ← lowercase in JSON
print(json.dumps(None))    # 'null'
print(json.dumps(3.14))    # '3.14'

# ── Pretty-print with indent ──────────────────────────
data = {
    "user":   "alice",
    "scores": [95, 87, 92],
    "active": True,
    "address": {"city": "Vadodara", "pin": "390001"}
}

print(json.dumps(data, indent=2))
# {
#   "user": "alice",
#   "scores": [95, 87, 92],
#   "active": true,
#   "address": {"city": "Vadodara", "pin": "390001"}
# }

# ── Sorting keys alphabetically ──────────────────────
print(json.dumps(data, sort_keys=True, indent=2))

# ── Compact output (no spaces) ───────────────────────
print(json.dumps(data, separators=(",", ":")))
# {"user":"alice","scores":[95,87,92],"active":true,...}

# ── Non-ASCII characters ─────────────────────────────
msg = {"greeting": "नमस्ते", "emoji": "🐍"}
print(json.dumps(msg))                          # escaped unicode
print(json.dumps(msg, ensure_ascii=False))     # actual unicode chars

Decoding — json.loads() JSON String → Python

json.loads(string) deserialises a JSON string into a Python object. JSON objects become dicts, arrays become lists, true/false become True/False, and null becomes None.

Python — json_loads.py
import json

# ── Parse a JSON string ───────────────────────────────
json_str = '{"name": "Alice", "age": 25, "active": true, "score": null}'
data     = json.loads(json_str)

print(type(data))           # <class 'dict'>
print(data["name"])        # Alice
print(data["active"])     # True  ← Python bool
print(data["score"])      # None  ← Python None
print(type(data["age"]))  # <class 'int'>

# ── Parse a JSON array ────────────────────────────────
arr_str = '[1, "two", 3.14, true, null]'
arr     = json.loads(arr_str)
print(type(arr))            # <class 'list'>
print(arr[0])               # 1

# ── Nested JSON ───────────────────────────────────────
nested = """
{
    "id": 1,
    "user": {"name": "Bob", "email": "bob@example.com"},
    "tags": ["python", "developer"],
    "metadata": null
}
"""
obj = json.loads(nested)
print(obj["user"]["email"])        # bob@example.com
print(obj["tags"][0])              # python

# ── Handle JSONDecodeError ────────────────────────────
try:
    json.loads("not valid json")
except json.JSONDecodeError as e:
    print(f"Error: {e}")

# ── Parse with object_hook — custom decoding ─────────
def as_complex(dct):
    if "real" in dct and "imag" in dct:
        return complex(dct["real"], dct["imag"])
    return dct

z = json.loads('{"real": 3, "imag": 4}', object_hook=as_complex)
print(z)           # (3+4j)  ← Python complex number!
Advertisement
K2infocom Python Masterclass & Backend Development
Master Python, Django & Backend APIs with AI
Go from absolute beginner to building production-ready REST APIs, web applications, and ML pipelines. Real projects, live mentoring in Vadodara, and placement support included.
2,400+
Students Enrolled
4.9 ⭐
Google Rating
6 Months
Full Program
100%
Placement Support
Python 3 Django & DRF FastAPI PostgreSQL Machine Learning Docker & AWS Real Projects AI Tools

File I/O — json.dump() and json.load()

json.dump(obj, file) writes JSON directly to an open file object. json.load(file) reads and parses JSON from an open file object. No "s" in the name = working with files (not strings).

Python — json_file_io.py
import json

data = {
    "project":  "K2infocom Portal",
    "version":  "2.1.0",
    "features": ["auth", "dashboard", "reports"],
    "config": {
        "debug":     False,
        "max_users": 1000,
        "timeout":   30
    }
}

# ── Write JSON to file ────────────────────────────────
with open("config.json", "w", encoding="utf-8") as f:
    json.dump(data, f, indent=2, ensure_ascii=False)
# config.json now contains formatted JSON

# ── Read JSON from file ───────────────────────────────
with open("config.json", encoding="utf-8") as f:
    loaded = json.load(f)

print(loaded["project"])             # K2infocom Portal
print(loaded["config"]["debug"])   # False
print(loaded["features"][0])       # auth

# ── Utility functions ─────────────────────────────────
def read_json(path):
    """Read a JSON file and return the parsed object."""
    with open(path, encoding="utf-8") as f:
        return json.load(f)

def write_json(path, obj, **kwargs):
    """Write a Python object to a JSON file."""
    with open(path, "w", encoding="utf-8") as f:
        json.dump(obj, f, ensure_ascii=False, **kwargs)

# Usage
write_json("settings.json", data, indent=4)
cfg = read_json("settings.json")
print(cfg["version"])                # 2.1.0

Pretty Printing & Formatting Options

The json module's formatting options let you control indentation, key ordering, separators, and non-ASCII encoding. Knowing these makes your JSON output professional and interoperable.

Python — json_formatting.py
import json

data = {"b": 2, "a": 1, "c": [3, 1, 2]}

# indent — number of spaces (or "\t" for tabs)
print(json.dumps(data, indent=4))
print(json.dumps(data, indent="\t"))  # tab indentation

# sort_keys — alphabetical key ordering
print(json.dumps(data, sort_keys=True))
# {"a": 1, "b": 2, "c": [3, 1, 2]}

# separators — customise between items and key:value
# default: (", ", ": ") with spaces
compact = json.dumps(data, separators=(",", ":"))    # no spaces
print(compact)     # {"b":2,"a":1,"c":[3,1,2]}

# ensure_ascii — True (default): escape non-ASCII; False: output as-is
non_ascii = {"city": "Vadodara 🏙️", "lang": "हिन्दी"}
print(json.dumps(non_ascii))
# {"city": "Vadodara \\ud83c\\udfd9\\ufe0f", "lang": "..."}

print(json.dumps(non_ascii, ensure_ascii=False))
# {"city": "Vadodara 🏙️", "lang": "हिन्दी"}

# allow_nan — control float special values
import math
# json.dumps(math.nan)           → 'NaN'  (non-standard JSON!)
# json.dumps(math.nan, allow_nan=False) → ValueError!

# Combining options
print(json.dumps(
    data,
    indent=2,
    sort_keys=True,
    ensure_ascii=False
))

Custom Serialisation — Dates, Classes & Decimal

Not all Python objects can be converted to JSON natively — datetime, custom classes, Decimal, set, and bytes all require custom handling. Python provides two ways: a custom encoder class (subclass json.JSONEncoder) or a default function passed to the default parameter.

Python — custom_json_serialisation.py
import json
from datetime import datetime, date
from decimal import Decimal

# ── Method 1: default function ────────────────────────
def json_serialiser(obj):
    """Handle types not natively supported by JSON."""
    if isinstance(obj, (datetime, date)):
        return obj.isoformat()           # "2025-05-16T14:30:00"
    if isinstance(obj, Decimal):
        return float(obj)
    if isinstance(obj, set):
        return list(obj)
    if isinstance(obj, bytes):
        return obj.decode("utf-8")
    raise TypeError(f"Type {type(obj)} not serialisable")

payload = {
    "created":  datetime.now(),
    "price":    Decimal("99.99"),
    "tags":     {"python", "web", "api"},
    "raw":      b"hello",
}
print(json.dumps(payload, default=json_serialiser, indent=2))

# ── Method 2: Custom JSONEncoder class ───────────────
class AppEncoder(json.JSONEncoder):
    def default(self, obj):
        if isinstance(obj, datetime):
            return obj.strftime("%Y-%m-%d %H:%M:%S")
        if isinstance(obj, Decimal):
            return str(obj)           # keep precision as string
        if hasattr(obj, "__dict__"):  # any class instance
            return obj.__dict__
        return super().default(obj)

print(json.dumps(payload, cls=AppEncoder, indent=2))

# ── Serialise custom class instances ─────────────────
class Product:
    def __init__(self, name, price):
        self.name  = name
        self.price = price

p = Product("Laptop", Decimal("49999.00"))
print(json.dumps(p, cls=AppEncoder))
# {"name": "Laptop", "price": "49999.00"}

# ── parse_float — decode JSON numbers as Decimal ─────
precise = json.loads(
    '{"price": 99.99}',
    parse_float=Decimal   # avoids float precision errors
)
print(type(precise["price"]))  # <class 'decimal.Decimal'>
print(precise["price"])        # 99.99 (exact)

Real-World JSON Patterns

JSON is the backbone of REST APIs, config files, and data pipelines. Here are the patterns you'll use in every professional Python project:

Python — json_real_world.py
import json
from pathlib import Path

# ── Pattern 1: Config file management ─────────────────
DEFAULT_CONFIG = {
    "database_url":  "sqlite:///app.db",
    "debug":         False,
    "allowed_hosts": ["localhost", "127.0.0.1"],
    "max_connections": 10,
}

def load_config(path="config.json"):
    p = Path(path)
    if not p.exists():
        write_json(path, DEFAULT_CONFIG)
        return DEFAULT_CONFIG.copy()
    with p.open(encoding="utf-8") as f:
        return {**DEFAULT_CONFIG, **json.load(f)}  # merge defaults

# ── Pattern 2: Deep get from nested JSON ──────────────
def deep_get(obj, *keys, default=None):
    """Safely get nested JSON value: deep_get(d, "user", "email")"""
    for key in keys:
        if isinstance(obj, dict):
            obj = obj.get(key, default)
        elif isinstance(obj, list) and isinstance(key, int):
            obj = obj[key] if key < len(obj) else default
        else:
            return default
    return obj

api_resp = {"data": {"user": {"email": "alice@k2.com"}}}
print(deep_get(api_resp, "data", "user", "email"))  # alice@k2.com
print(deep_get(api_resp, "data", "user", "phone", default="N/A"))

# ── Pattern 3: JSON Lines (JSONL) ─────────────────────
# One JSON object per line — common for streaming data / logs
records = [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"},
    {"id": 3, "name": "Carol"},
]

# Write JSONL
with open("data.jsonl", "w", encoding="utf-8") as f:
    for rec in records:
        f.write(json.dumps(rec) + "\n")

# Read JSONL
with open("data.jsonl", encoding="utf-8") as f:
    for line in f:
        rec = json.loads(line)
        print(rec["name"])

# ── Pattern 4: Validate JSON schema manually ─────────
def validate_user(data):
    required = {"name", "email", "age"}
    missing  = required - set(data.keys())
    if missing:
        raise ValueError(f"Missing fields: {missing}")
    if not isinstance(data["age"], int):
        raise TypeError("age must be int")
    return True

Practice Python Online — Free Compilers

Don't want to install anything yet? Practice all JSON examples from this chapter directly in your browser — Python's json module is available in every online environment.

▶
Online Python 3 Compiler
Write, run and debug Python code in your browser. No installation required. Test every JSON example instantly.
Open Compiler
Replit
Full IDE online
Google Colab
Free GPU notebooks
JupyterLite
Notebooks in browser
Programiz
Beginner-friendly
Chapter Summary
  • JSON is text-based, language-independent, and the universal format for web APIs and config files. Python's built-in json module handles all JSON operations.
  • Type mapping: Python dict→JSON object, list/tuple→array, str→string, int/float→number, True/False→true/false, None→null.
  • json.dumps(obj) encodes Python → JSON string. json.loads(string) decodes JSON string → Python. The "s" = string.
  • json.dump(obj, file) writes to file. json.load(file) reads from file. No "s" = file I/O. Always use encoding="utf-8".
  • Key formatting options: indent=2 for readable output, sort_keys=True for deterministic ordering, ensure_ascii=False for Unicode output, separators=(",", ":") for compact output.
  • Types not natively serialisable: datetime, Decimal, set, bytes, custom classes. Handle via default= function or cls=JSONEncoder subclass.
  • Use parse_float=Decimal in json.loads() to avoid floating-point precision errors when parsing monetary values.
  • JSONL (JSON Lines) — one JSON object per line — is the standard for streaming data, logs, and large datasets.
  • Handle json.JSONDecodeError for malformed input; always validate required fields before processing API responses.
Free Resource
Download our Python JSON Cheat Sheet
dumps/loads/dump/load, formatting options, custom serialisation, type mapping & real-world patterns — one printable page.
Get Sheet
Advertisement
Quick Check — Test Your Understanding
Question & Answer
✓ Answer

Both serialise a Python object to JSON, but differ in destination:

  • json.dumps(obj) — the "s" stands for string. Returns the JSON as a Python string. Use when you need the JSON in memory (e.g. sending over a network, embedding in code).
  • json.dump(obj, file) — writes directly to an open file object. More memory-efficient for large objects since it streams directly to disk.

The same "s" rule applies to reading: json.loads(string) parses from a string; json.load(file) reads from a file.

✓ Answer

The following types raise TypeError with default JSON serialisation:

  • datetime / date — convert with .isoformat()
  • Decimal — convert to float or str
  • set — convert to list
  • bytes — convert with .decode()
  • Custom class instances — convert to dict via .__dict__

Handle them with a default= function or by subclassing json.JSONEncoder.

✓ Answer
import json
data = {"z": 3, "a": 1, "m": [1, 2]}

print(json.dumps(data, indent=2, sort_keys=True))
# {
#   "a": 1,
#   "m": [1, 2],
#   "z": 3
# }

Use ensure_ascii=False as well if your data contains non-ASCII characters like Unicode, emojis, or Indian script.

✓ Answer

JSONL (JSON Lines) is a format where each line of a text file is a separate, valid JSON object. There is no wrapping array — each line is independent.

Used for: streaming data processing (you can process line-by-line without loading the whole file), log files, large datasets, and machine learning training data. It's memory-efficient because you never need to parse the entire file at once.

# data.jsonl — one JSON object per line:
# {"id": 1, "name": "Alice"}
# {"id": 2, "name": "Bob"}
with open("data.jsonl") as f:
    for line in f:
        rec = json.loads(line)   # one at a time
✓ Answer

By default, JSON floating-point numbers are decoded as Python float, which uses IEEE 754 double precision. This can introduce tiny precision errors that are catastrophic for financial or monetary values:

print(json.loads('{"price": 99.99}')["price"])
# 99.99000000000001  ← float precision issue!

from decimal import Decimal
print(json.loads('{"price": 99.99}', parse_float=Decimal)["price"])
# Decimal('99.99')  ← exact!

Use parse_float=Decimal whenever you're parsing monetary amounts or other values where precision is critical.

MCQ 1 of 3
Which function decodes a JSON-formatted string into a Python object?
MCQ 2 of 3
What does Python's True become when serialised to JSON?
MCQ 3 of 3
Which parameter of json.dumps() produces nicely indented, human-readable output?

Rate Us on Google

4.8 / 5
Enjoying this tutorial?
Your 5-star review helps other learners discover our free tutorials and encourages us to keep creating quality content.
80+ reviews
Write a Google Review
Join WhatsApp Channel