5. Python: advanced json
- Serialize types that
jsondoes not know (datetime,Decimal,set, dataclasses) withdefault=or aJSONEncoder. - Decode into rich types:
object_hookto recognize dates,parse_float=Decimalfor money,object_pairs_hookto catch duplicate keys. - Build a reliable round trip: object → JSON → identical object.
Theory
Section titled “Theory”Going out: default= and JSONEncoder
Section titled “Going out: default= and JSONEncoder”When dumps meets a type it cannot serialize, it calls the function passed in default= and serializes whatever it returns. It is the simplest mechanism:
def converti(o): if isinstance(o, datetime): return o.isoformat() if isinstance(o, Decimal): return str(o) # o float(o), scegli consapevolmente if isinstance(o, set): return sorted(o) if is_dataclass(o): return asdict(o) raise TypeError(f"Non so serializzare {type(o).__name__}")json.dumps(dato, default=converti)The alternative is a subclass of json.JSONEncoder with a default(self, o) method and cls=MioEncoder: same logic, handy when you want to reuse it in several places or encapsulate configuration.
Coming in: object_hook, object_pairs_hook, parse_float
Section titled “Coming in: object_hook, object_pairs_hook, parse_float”loads calls object_hook(dict) for every object it decodes, from the innermost to the outermost, and uses whatever it returns. It is the place to turn ISO strings into datetime:
def riconosci_date(d): for k, v in d.items(): if k.endswith("_at") and isinstance(v, str): d[k] = datetime.fromisoformat(v) return djson.loads(testo, object_hook=riconosci_date)object_pairs_hook, instead, receives the list of pairs (key, value) in document order: use it to reject duplicate keys or build special ordered structures. parse_float (and parse_int) replace the constructor used for numbers: parse_float=Decimal is the right way to read amounts.
Round trip
Section titled “Round trip”“Round trip” means: loads(dumps(x)) == x. With the basic types it always works (except tuples, which come back as lists). With datetime/Decimal you must pair a default going out with a hook coming in: the convention (e.g. “every key ending in _at is an ISO date”) is yours, JSON does not know it.
curl, explained: an order with dates and amounts
Section titled “curl, explained: an order with dates and amounts”curl -s https://corso-api-json.giuseppebosi.com/api/v1/orders/1 | jq '{created_at, total, n_righe: (.items | length)}'- /api/v1/orders/1
- order 1: it has an ISO date, a decimal amount and an array of line items
- jq '{…}'
- builds a new object by picking fields:
created_atandtotalas they are,n_righecomputed withlengthon theitemsarray
{ "created_at": "2025-01-10T21:00:00Z", "total": 12.04, "n_righe": 1}The full response:
{"id":1,"customer_id":39,"status":"delivered","shipping_address":{"street":"Via Sestri 73","city":"Bari","zip":"15399","country":"IT"},"total":12.04,"created_at":"2025-01-10T21:00:00Z","items":[{"id":1,"order_id":1,"book_id":11,"quantity":1,"unit_price":12.04}]}created_at is a string, total a float: exactly the two cases we want to handle better.
Response headers
Python: rich decoding and round trip
Section titled “Python: rich decoding and round trip”# pip install httpx# python3 json_avanzato.pyimport jsonfrom dataclasses import dataclass, asdict, is_dataclassfrom datetime import datetime, timezonefrom decimal import Decimalimport httpx
BASE = "https://corso-api-json.giuseppebosi.com/api/v1"
# --- 1. Decodifica ricca: date vere, Decimal per gli importi ---------------------------def riconosci_date(d: dict) -> dict: for k, v in d.items(): if k.endswith("_at") and isinstance(v, str): d[k] = datetime.fromisoformat(v) # accetta la 'Z' da Python 3.11 return d
testo = httpx.get(f"{BASE}/orders/1").textordine = json.loads(testo, object_hook=riconosci_date, parse_float=Decimal)print(type(ordine["created_at"]).__name__, ordine["created_at"].year) # datetime 2025print(type(ordine["total"]).__name__, ordine["total"] * 3) # Decimal 36.12
# --- 2. Codifica di tipi non nativi con default= --------------------------------------@dataclassclass Riga: book_id: int quantity: int unit_price: Decimal
def converti(o): if isinstance(o, datetime): return o.isoformat().replace("+00:00", "Z") if isinstance(o, Decimal): return str(o) if isinstance(o, set): return sorted(o) if is_dataclass(o): return asdict(o) raise TypeError(f"Non so serializzare {type(o).__name__}")
nuovo = { "created_at": datetime(2026, 9, 18, 9, 30, tzinfo=timezone.utc), "total": Decimal("18.71"), "tags": {"novità", "premio"}, "items": [Riga(7, 2, Decimal("9.355"))],}print(json.dumps(nuovo, default=converti, ensure_ascii=False))# {"created_at": "2026-09-18T09:30:00Z", "total": "18.71", "tags": ["novità", "premio"],# "items": [{"book_id": 7, "quantity": 2, "unit_price": "9.355"}]}
# --- 3. Lo stesso con una classe Encoder riusabile ------------------------------------class Encoder(json.JSONEncoder): def default(self, o): return converti(o)print(json.dumps({"q": datetime(2026, 1, 1, tzinfo=timezone.utc)}, cls=Encoder))
# --- 4. object_pairs_hook: rifiuta le chiavi duplicate --------------------------------def senza_duplicati(coppie): d = {} for k, v in coppie: if k in d: raise ValueError(f"chiave duplicata: {k!r}") d[k] = v return dtry: json.loads('{"dup": 1, "dup": 2}', object_pairs_hook=senza_duplicati)except ValueError as e: print(e) # chiave duplicata: 'dup'
# --- 5. Round-trip verificato ------------------------------------------------------------def dumps(x): return json.dumps(x, default=converti, sort_keys=True)def loads(s): return json.loads(s, object_hook=riconosci_date, parse_float=Decimal)
ritorno = loads(dumps(ordine))print(ritorno == ordine) # False!print(repr(ritorno["total"]), repr(ordine["total"])) # '12.04' Decimal('12.04')
# Il round-trip FALLISCE: converti ha scritto il Decimal tra apici, e in lettura è rimasto# una stringa. Le due metà devono essere simmetriche: se in uscita scrivi un numero...def converti_num(o): if isinstance(o, Decimal): return float(o) # numero JSON; la precisione torna grazie a parse_float=Decimal return converti(o)def dumps2(x): return json.dumps(x, default=converti_num, sort_keys=True)
andata = dumps2(ordine)assert loads(andata) == ordine, "il round-trip ha perso qualcosa"print("round-trip ok, byte:", len(andata))What you should see:
datetime 2025Decimal 36.12{"created_at": "2026-09-18T09:30:00Z", "total": "18.71", "tags": ["novità", "premio"], "items": [{"book_id": 7, "quantity": 2, "unit_price": "9.355"}…{"q": "2026-01-01T00:00:00Z"}chiave duplicata: 'dup'False'12.04' Decimal('12.04')round-trip ok, byte: 291Note step 5: the first version fails because going out the Decimal becomes a string and coming in it stays one. The final assert proves that converti_num and parse_float=Decimal are symmetric: if you change the convention on one side only, the assert tells you. (float(Decimal("12.04")) is written as 12.04 and comes back as Decimal("12.04"): no loss for the two decimal places of money; with more digits, keep the string in both directions.)
The JavaScript counterparts are replacer/toJSON (going out) and reviver (coming in): chapter 6. The mapping:
// default=converti -> JSON.stringify(x, replacer) oppure metodo toJSON() sull'oggetto// object_hook=riconosci_date -> JSON.parse(s, reviver)// parse_float=Decimal -> non esiste: i numeri sono sempre double. Usa stringhe + una libreria// (decimal.js, big.js) o interi in centesimi.Exercise
Section titled “Exercise”Try it online, nothing to install:
The GET request straight in your browser: https://corso-api-json.giuseppebosi.com/api/v1/orders/1
Python on Google Colab (a free Google account is needed to run the cells); TypeScript on StackBlitz (it opens and starts by itself in the browser). If the practice API is switched off, turn it on from /en/api-attiva/.
Download /api/v1/orders?limit=20. Decode with parse_float=Decimal and object_hook for the dates; then compute:
- the exact sum of the
totalvalues (it must be aDecimal); - the most recent order (comparing
datetimevalues, not strings); - serialize the list again with
default=and check thatloads(dumps(lista)) == lista.
Solution
import json, httpxfrom datetime import datetimefrom decimal import Decimal
def hook(d): for k, v in d.items(): if k.endswith("_at") and isinstance(v, str): d[k] = datetime.fromisoformat(v) return ddef conv(o): if isinstance(o, datetime): return o.isoformat().replace("+00:00", "Z") if isinstance(o, Decimal): return float(o) # numero, non stringa: vedi punto 5 raise TypeError
testo = httpx.get("https://corso-api-json.giuseppebosi.com/api/v1/orders", params={"limit": 20}).textordini = json.loads(testo, object_hook=hook, parse_float=Decimal)["items"]print(sum(o["total"] for o in ordini)) # 1334.45 (un Decimal)print(max(ordini, key=lambda o: o["created_at"])["id"]) # 2assert json.loads(json.dumps(ordini, default=conv), object_hook=hook, parse_float=Decimal) == ordiniWhat you should see:
1334.452If you had written str(o) in conv, total would have come back as the string "12.04" and the assert would have failed: the outgoing and incoming conventions must match.
Common mistakes
Section titled “Common mistakes”- A
default=that returns the object itself → infinite recursion /RecursionError. datetime.fromisoformatwith a trailingZ: it works from Python 3.11; before that you needed.replace("Z", "+00:00").- An
object_hookthat returnsNone(forgotreturn d): the whole object becomesNone. - Using
parse_float=Decimaland then adding withfloat: the imprecision comes back.
Summary
Section titled “Summary”default=/JSONEncoder going out, object_hook/object_pairs_hook/parse_float coming in, and a round-trip assert as a guarantee. In the next chapter we move to JavaScript: JSON.parse and JSON.stringify with reviver, replacer and toJSON.