`json` — JSON-Kodierer und -Dekodierer¶

Quellcode: Lib/json/__init__.py

JSON (JavaScript Object Notation) ist in RFC 7159 (der RFC 4627 ersetzt) und in ECMA-404 festgelegt. Es ist ein leichtgewichtiges Format zum Datenaustausch, angelehnt an die Syntax für Objektliterale von JavaScript – auch wenn es keine echte Teilmenge von JavaScript ist [1] .

Bemerkung

Der Begriff „Objekt“ kann bei der JSON-Verarbeitung in Python mehrdeutig sein. In Python sind alle Werte Objekte. In JSON meint ein Objekt alle Daten in geschweiften Klammern, ähnlich einem Dictionary in Python.

Warnung

Sei vorsichtig beim Einlesen von JSON-Daten aus unsicheren Quellen. Eine bösartige JSON-Zeichenkette kann den Dekodierer dazu bringen, erhebliche CPU- und Speicherressourcen zu verbrauchen. Es empfiehlt sich, die Größe der eingelesenen Daten zu begrenzen.

Dieses Modul bietet eine API, die denen der Standardbibliotheksmodule marshal und pickle ähnelt.

Einfache Hierarchien von Python-Objekten kodieren:

>>> import json
>>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
'["foo", {"bar": ["baz", null, 1.0, 2]}]'
>>> print(json.dumps("\"foo\bar"))
"\"foo\bar"
>>> print(json.dumps('\u1234'))
"\u1234"
>>> print(json.dumps('\\'))
"\\"
>>> print(json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True))
{"a": 0, "b": 0, "c": 0}
>>> from io import StringIO
>>> io = StringIO()
>>> json.dump(['streaming API'], io)
>>> io.getvalue()
'["streaming API"]'

Kompakt kodieren:

>>> import json
>>> json.dumps([1, 2, 3, {'4': 5, '6': 7}], separators=(',', ':'))
'[1,2,3,{"4":5,"6":7}]'

Ansprechend ausgeben:

>>> import json
>>> print(json.dumps({'6': 7, '4': 5}, sort_keys=True, indent=4))
{
    "4": 5,
    "6": 7
}

Das Kodieren von JSON-Objekten anpassen:

>>> import json
>>> def custom_json(obj):
...     if isinstance(obj, complex):
...         return {'__complex__': True, 'real': obj.real, 'imag': obj.imag}
...     raise TypeError(f'Cannot serialize object of {type(obj)}')
...
>>> json.dumps(1 + 2j, default=custom_json)
'{"__complex__": true, "real": 1.0, "imag": 2.0}'

JSON dekodieren:

>>> import json
>>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]')
['foo', {'bar': ['baz', None, 1.0, 2]}]
>>> json.loads('"\\"foo\\bar"')
'"foo\x08ar'
>>> from io import StringIO
>>> io = StringIO('["streaming API"]')
>>> json.load(io)
['streaming API']

Das Dekodieren von JSON-Objekten anpassen:

>>> import json
>>> def as_complex(dct):
...     if '__complex__' in dct:
...         return complex(dct['real'], dct['imag'])
...     return dct
...
>>> json.loads('{"__complex__": true, "real": 1, "imag": 2}',
...     object_hook=as_complex)
(1+2j)
>>> import decimal
>>> json.loads('1.1', parse_float=decimal.Decimal)
Decimal('1.1')
>>> json.loads('{"name": "point", "coords": [[1, 2], [3, 4]]}',
...     array_hook=tuple)
{'name': 'point', 'coords': ((1, 2), (3, 4))}
>>> json.loads('{"name": "point", "coords": [1, 2]}',
...     object_pairs_hook=frozendict, array_hook=tuple)
frozendict({'name': 'point', 'coords': (1, 2)})

JSONEncoder erweitern:

>>> import json
>>> class ComplexEncoder(json.JSONEncoder):
...     def default(self, obj):
...         if isinstance(obj, complex):
...             return [obj.real, obj.imag]
...         # Let the base class default method raise the TypeError
...         return super().default(obj)
...
>>> json.dumps(2 + 1j, cls=ComplexEncoder)
'[2.0, 1.0]'
>>> ComplexEncoder().encode(2 + 1j)
'[2.0, 1.0]'
>>> list(ComplexEncoder().iterencode(2 + 1j))
['[2.0', ', 1.0', ']']

json von der Shell aus zum Prüfen und ansprechenden Ausgeben verwenden:

$ echo '{"json":"obj"}' | python -m json
{
    "json": "obj"
}
$ echo '{1.2:3.4}' | python -m json
Expecting property name enclosed in double quotes: line 1 column 2 (char 1)

Eine ausführliche Dokumentation steht unter Befehlszeilenschnittstelle.

Bemerkung

JSON ist eine Teilmenge von YAML 1.2. Das JSON, das dieses Modul mit seinen Voreinstellungen erzeugt (insbesondere mit dem voreingestellten Wert für separators), ist außerdem eine Teilmenge von YAML 1.0 und 1.1. Dieses Modul lässt sich daher auch als YAML-Serialisierer verwenden.

Bemerkung

Die Kodierer und Dekodierer dieses Moduls erhalten die Reihenfolge von Ein- und Ausgabe voreingestellt. Die Reihenfolge geht nur verloren, wenn die zugrunde liegenden Behälter unsortiert sind.

Grundlegende Verwendung¶

json.dump(obj, fp, *, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, sort_keys=False, **kw)¶

Serialisiert obj als JSON-formatierten Strom nach fp (ein dateiähnliches Objekt, das .write() unterstützt), gemäß dieser Umwandlungstabelle von Python nach JSON.

Bemerkung

Anders als pickle und marshal ist JSON kein Protokoll mit Rahmen. Mehrere Objekte durch wiederholte Aufrufe von dump() mit demselben fp zu serialisieren, ergibt daher eine ungültige JSON-Datei.

Parameter:

obj (object) – Das zu serialisierende Python-Objekt.
fp (file-like object) – Das dateiähnliche Objekt, nach dem obj serialisiert wird. Das Modul json erzeugt immer str-Objekte, keine bytes-Objekte; fp.write() muss daher str als Eingabe unterstützen.
skipkeys (bool) – Bei True werden Schlüssel, die keinen einfachen Typ haben (str, int, float, bool, None), übersprungen, statt einen TypeError auszulösen. Voreingestellt False.
ensure_ascii (bool) – Bei True (der Voreinstellung) sind in der Ausgabe garantiert alle eingehenden Zeichen außerhalb von ASCII und alle nicht druckbaren Zeichen maskiert. Bei False werden alle Zeichen unverändert ausgegeben, außer den Zeichen, die maskiert werden müssen: Anführungszeichen, umgekehrter Schrägstrich und die Steuerzeichen U+0000 bis U+001F.
check_circular (bool) – Bei False wird die Prüfung auf Zirkelbezüge bei Behältertypen übersprungen. Ein Zirkelbezug führt dann zu einem RecursionError (oder Schlimmerem). Voreingestellt True.
allow_nan (bool) – Bei False führt das Serialisieren von float-Werten außerhalb des Bereichs (nan, inf, -inf) zu einem ValueError, in strenger Übereinstimmung mit der JSON-Spezifikation. Bei True (der Voreinstellung) werden ihre JavaScript-Gegenstücke (NaN, Infinity, -Infinity) verwendet.
cls (a JSONEncoder subclass) – Wenn gesetzt, ein eigener JSON-Kodierer mit überschriebener Methode default(), um in eigene Datentypen zu serialisieren. Bei None (der Voreinstellung) wird JSONEncoder verwendet.
indent (int | str | None) – Bei einer positiven ganzen Zahl oder einer Zeichenkette werden die Elemente von JSON-Arrays und die Mitglieder von Objekten mit diesem Einzug ansprechend ausgegeben. Eine positive ganze Zahl rückt je Ebene um so viele Leerzeichen ein. Eine Zeichenkette (etwa "\t") wird für den Einzug jeder Ebene verwendet. Bei null, einem negativen Wert oder "" (der leeren Zeichenkette) werden nur Zeilenumbrüche eingefügt. Bei None (der Voreinstellung) werden keine Zeilenumbrüche eingefügt.
separators (tuple | None) – Ein Zweiertupel: (item_separator, key_separator). Bei None (der Voreinstellung) ist separators gleich (', ', ': '), wenn indent None ist, und sonst (',', ': '). Für das kompakteste JSON gib (',', ':') an, um Leerraum zu vermeiden.
default (callable | None) – Eine Funktion, die für Objekte aufgerufen wird, die sich sonst nicht serialisieren lassen. Sie sollte eine JSON-kodierbare Fassung des Objekts zurückgeben oder einen TypeError auslösen. Bei None (der Voreinstellung) wird TypeError ausgelöst.
sort_keys (bool) – Bei True werden Dictionarys nach Schlüssel sortiert ausgegeben. Voreingestellt False.

Bemerkung

Schlüssel in Schlüssel-Wert-Paaren von JSON haben immer den Typ str. Wird ein Dictionary nach JSON umgewandelt, werden alle seine Schlüssel in Zeichenketten umgewandelt. Wandelt man ein Dictionary daher nach JSON und wieder zurück, muss das Ergebnis dem Ausgangswert nicht gleichen: loads(dumps(x)) != x, wenn x Schlüssel hat, die keine Zeichenketten sind. sort_keys sortiert die Schlüssel, bevor sie in Zeichenketten umgewandelt werden. Numerische Schlüssel werden also nach ihrem Wert sortiert und nicht nach ihrer Zeichenkettendarstellung.

Geändert in Version 3.2: Für indent sind nun neben ganzen Zahlen auch Zeichenketten erlaubt.

Geändert in Version 3.4: Voreingestellt wird (',', ': ') verwendet, wenn indent nicht None ist.

Geändert in Version 3.6: Alle optionalen Parameter sind jetzt nur als Schlüsselwort übergebbar.

json.dumps(obj, *, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, sort_keys=False, **kw)¶: Serialisiert obj zu einem JSON-formatierten str gemäß dieser Umwandlungstabelle. Die Argumente haben dieselbe Bedeutung wie bei dump().

json.load(fp, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, array_hook=None, **kw)¶

Deserialisiert fp zu einem Python-Objekt gemäß der Umwandlungstabelle von JSON nach Python.

Parameter:

fp (file-like object) – Eine Textdatei oder Binärdatei, die .read() unterstützt und das zu deserialisierende JSON-Dokument enthält.
cls (a JSONDecoder subclass) – Wenn gesetzt, ein eigener JSON-Dekodierer. Weitere Schlüsselwortargumente an load() werden an den Konstruktor von cls übergeben. Bei None (der Voreinstellung) wird JSONDecoder verwendet.
object_hook (callable | None) – Wenn gesetzt, eine Funktion, die mit dem Ergebnis jedes dekodierten JSON-Objektliterals (einem dict) aufgerufen wird. Der Rückgabewert dieser Funktion wird anstelle des dict verwendet. Damit lassen sich eigene Dekodierer umsetzen, etwa die Klassenhinweise von JSON-RPC. Voreingestellt None.
object_pairs_hook (callable | None) – Wenn gesetzt, eine Funktion, die mit dem Ergebnis jedes dekodierten JSON-Objektliterals als geordnete Liste von Paaren aufgerufen wird. Der Rückgabewert dieser Funktion wird anstelle des dict verwendet. Damit lassen sich eigene Dekodierer umsetzen. Ist auch object_hook gesetzt, hat object_pairs_hook Vorrang. Voreingestellt None.
array_hook (callable | None) – Wenn gesetzt, eine Funktion, die mit dem Ergebnis jedes dekodierten JSON-Arrayliterals als Python-Liste aufgerufen wird. Der Rückgabewert dieser Funktion wird anstelle der list verwendet. Damit lassen sich eigene Dekodierer umsetzen. Voreingestellt None.
parse_float (callable | None) – Wenn gesetzt, eine Funktion, die mit der Zeichenkette jeder zu dekodierenden JSON-Gleitkommazahl aufgerufen wird. Bei None (der Voreinstellung) entspricht das float(num_str). Damit lassen sich JSON-Gleitkommazahlen in eigene Datentypen einlesen, etwa in decimal.Decimal.
parse_int (callable | None) – Wenn gesetzt, eine Funktion, die mit der Zeichenkette jeder zu dekodierenden ganzen JSON-Zahl aufgerufen wird. Bei None (der Voreinstellung) entspricht das int(num_str). Damit lassen sich ganze JSON-Zahlen in eigene Datentypen einlesen, etwa in float.
parse_constant (callable | None) – Wenn gesetzt, eine Funktion, die mit einer der folgenden Zeichenketten aufgerufen wird: '-Infinity', 'Infinity' oder 'NaN'. Damit lässt sich eine Ausnahme auslösen, wenn ungültige JSON-Zahlen auftreten. Voreingestellt None.

Verursacht:

JSONDecodeError – Wenn die zu deserialisierenden Daten kein gültiges JSON-Dokument sind.
UnicodeDecodeError – Wenn die zu deserialisierenden Daten keine in UTF-8, UTF-16 oder UTF-32 kodierten Daten enthalten.

Geändert in Version 3.1:

Der optionale Parameter object_pairs_hook kam hinzu.
parse_constant wird für ‚null‘, ‚true‘ und ‚false‘ nicht mehr aufgerufen.

Geändert in Version 3.6:

Alle optionalen Parameter sind jetzt nur als Schlüsselwort übergebbar.
fp kann jetzt eine Binärdatei sein. Die Eingabekodierung sollte UTF-8, UTF-16 oder UTF-32 sein.

Geändert in Version 3.11: Das voreingestellte parse_int von int() begrenzt jetzt die größte Länge der Zahlenzeichenkette über die Längenbeschränkung bei der Umwandlung von Zahlen in Zeichenketten des Interpreters, um Angriffen zur Dienstverweigerung vorzubeugen.

Geändert in Version 3.15: Der optionale Parameter array_hook kam hinzu.

json.loads(s, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, array_hook=None, **kw)¶: Gleichbedeutend mit load(), deserialisiert aber statt eines dateiähnlichen Objekts s (eine Instanz von str, bytes oder bytearray, die ein JSON-Dokument enthält) zu einem Python-Objekt gemäß dieser Umwandlungstabelle.

Geändert in Version 3.6: s kann jetzt den Typ bytes oder bytearray haben. Die Eingabekodierung sollte UTF-8, UTF-16 oder UTF-32 sein.

Geändert in Version 3.9: Das Schlüsselwortargument encoding wurde entfernt.

Kodierer und Dekodierer¶

class json.JSONDecoder(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None, array_hook=None)¶

Einfacher JSON-Dekodierer.

Nimmt beim Dekodieren voreingestellt die folgenden Übertragungen vor:

JSON	Python
Objekt	dict
Array	Liste
Zeichenkette	str
Zahl (int)	int
Zahl (real)	float
true	True
false	False
null	None

Es versteht außerdem NaN, Infinity und -Infinity als die entsprechenden float-Werte, was über die JSON-Spezifikation hinausgeht.

object_hook ist eine optionale Funktion, die mit dem Ergebnis jedes dekodierten JSON-Objekts aufgerufen wird. Ihr Rückgabewert wird anstelle des übergebenen dict verwendet. Damit lassen sich eigene Deserialisierungen bereitstellen, etwa die Unterstützung der Klassenhinweise von JSON-RPC.

object_pairs_hook ist eine optionale Funktion, die mit dem Ergebnis jedes dekodierten JSON-Objekts als geordnete Liste von Paaren aufgerufen wird. Der Rückgabewert von object_pairs_hook wird anstelle des dict verwendet. Damit lassen sich eigene Dekodierer umsetzen. Ist auch object_hook festgelegt, hat object_pairs_hook Vorrang.

Geändert in Version 3.1: Unterstützung für object_pairs_hook hinzugefügt.

array_hook ist eine optionale Funktion, die mit dem Ergebnis jedes als Liste dekodierten JSON-Arrays aufgerufen wird. Der Rückgabewert von array_hook wird anstelle der list verwendet. Damit lassen sich eigene Dekodierer umsetzen.

Geändert in Version 3.15: Unterstützung für array_hook hinzugefügt.

parse_float ist eine optionale Funktion, die mit der Zeichenkette jeder zu dekodierenden JSON-Gleitkommazahl aufgerufen wird. Voreingestellt entspricht das float(num_str). Damit lässt sich ein anderer Datentyp oder Parser für JSON-Gleitkommazahlen verwenden, etwa decimal.Decimal.

parse_int ist eine optionale Funktion, die mit der Zeichenkette jeder zu dekodierenden ganzen JSON-Zahl aufgerufen wird. Voreingestellt entspricht das int(num_str). Damit lässt sich ein anderer Datentyp oder Parser für ganze JSON-Zahlen verwenden, etwa float.

parse_constant ist eine optionale Funktion, die mit einer der folgenden Zeichenketten aufgerufen wird: '-Infinity', 'Infinity', 'NaN'. Damit lässt sich eine Ausnahme auslösen, wenn ungültige JSON-Zahlen auftreten.

Ist strict falsch (voreingestellt ist True), sind Steuerzeichen innerhalb von Zeichenketten erlaubt. Steuerzeichen sind in diesem Zusammenhang jene mit Zeichencodes im Bereich 0–31, darunter '\t' (Tabulator), '\n', '\r' und '\0'.

Sind die zu deserialisierenden Daten kein gültiges JSON-Dokument, wird ein JSONDecodeError ausgelöst.

Geändert in Version 3.6: Alle Parameter sind jetzt nur als Schlüsselwort übergebbar.

decode(s)¶

Gibt die Python-Darstellung von s zurück (eine Instanz von str, die ein JSON-Dokument enthält).

JSONDecodeError wird ausgelöst, wenn das übergebene JSON-Dokument nicht gültig ist.

raw_decode(s)¶

Dekodiert ein JSON-Dokument aus s (ein str, der mit einem JSON-Dokument beginnt) und gibt ein Zweiertupel aus der Python-Darstellung und dem Index in s zurück, an dem das Dokument endete.

Damit lässt sich ein JSON-Dokument aus einer Zeichenkette dekodieren, an deren Ende noch weitere Daten stehen können.

class json.JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)¶

Erweiterbarer JSON-Kodierer für Python-Datenstrukturen.

Unterstützt voreingestellt die folgenden Objekte und Typen:

Python	JSON
dict, frozendict	Objekt
list, tuple	Array
str	Zeichenkette
int, float, von int und float abgeleitete Enums	Zahl
True	true
False	false
None	null

Geändert in Version 3.4: Unterstützung für von int und float abgeleitete Enum-Klassen hinzugefügt.

Geändert in Version 3.15: Unterstützung für frozendict hinzugefügt.

Um das auf weitere Objekte auszuweiten, bilde eine Unterklasse und setze eine Methode default() um, die für o möglichst ein serialisierbares Objekt zurückgibt und andernfalls die Umsetzung der Oberklasse aufruft (um TypeError auszulösen).

Ist skipkeys falsch (die Voreinstellung), wird ein TypeError ausgelöst, wenn versucht wird, Schlüssel zu kodieren, die nicht str, int, float, bool oder None sind. Ist skipkeys wahr, werden solche Einträge einfach übersprungen.

Ist ensure_ascii wahr (die Voreinstellung), sind in der Ausgabe garantiert alle eingehenden Zeichen außerhalb von ASCII und alle nicht druckbaren Zeichen maskiert. Ist ensure_ascii falsch, werden alle Zeichen unverändert ausgegeben, außer den Zeichen, die maskiert werden müssen: Anführungszeichen, umgekehrter Schrägstrich und die Steuerzeichen U+0000 bis U+001F.

Ist check_circular wahr (die Voreinstellung), werden Listen, Dicts und eigens kodierte Objekte beim Kodieren auf Zirkelbezüge geprüft, um eine endlose Rekursion zu verhindern (die einen RecursionError auslösen würde). Andernfalls findet keine solche Prüfung statt.

Ist allow_nan wahr (die Voreinstellung), werden NaN, Infinity und -Infinity als solche kodiert. Dieses Verhalten entspricht nicht der JSON-Spezifikation, passt aber zu den meisten Kodierern und Dekodierern auf JavaScript-Basis. Andernfalls löst das Kodieren solcher Gleitkommazahlen einen ValueError aus.

Ist sort_keys wahr (voreingestellt False), wird die Ausgabe von Dictionarys nach Schlüssel sortiert. Das ist für Regressionstests nützlich, damit JSON-Serialisierungen von Tag zu Tag vergleichbar bleiben.

Ist indent eine nicht negative ganze Zahl oder eine Zeichenkette, werden die Elemente von JSON-Arrays und die Mitglieder von Objekten mit diesem Einzug ansprechend ausgegeben. Ein Einzug von 0, ein negativer Wert oder "" fügt nur Zeilenumbrüche ein. None (die Voreinstellung) wählt die kompakteste Darstellung. Eine positive ganze Zahl rückt je Ebene um so viele Leerzeichen ein. Ist indent eine Zeichenkette (etwa "\t"), wird diese Zeichenkette für den Einzug jeder Ebene verwendet.

Geändert in Version 3.2: Für indent sind nun neben ganzen Zahlen auch Zeichenketten erlaubt.

Wird separators angegeben, sollte es ein Tupel (item_separator, key_separator) sein. Voreingestellt ist (', ', ': '), wenn indent None ist, und sonst (',', ': '). Für die kompakteste JSON-Darstellung gib (',', ':') an, um Leerraum zu vermeiden.

Geändert in Version 3.4: Voreingestellt wird (',', ': ') verwendet, wenn indent nicht None ist.

Wird default angegeben, sollte es eine Funktion sein, die für Objekte aufgerufen wird, die sich sonst nicht serialisieren lassen. Sie sollte eine JSON-kodierbare Fassung des Objekts zurückgeben oder einen TypeError auslösen. Ohne Angabe wird TypeError ausgelöst.

Geändert in Version 3.6: Alle Parameter sind jetzt nur als Schlüsselwort übergebbar.

default(o)¶

Setze diese Methode in einer Unterklasse so um, dass sie für o ein serialisierbares Objekt zurückgibt oder die Umsetzung der Basisklasse aufruft (um einen TypeError auszulösen).

Um zum Beispiel beliebige Iteratoren zu unterstützen, ließe sich default() so umsetzen:

def default(self, o):
   try:
       iterable = iter(o)
   except TypeError:
       pass
   else:
       return list(iterable)
   # Let the base class default method raise the TypeError
   return super().default(o)

encode(o)¶

Gibt eine JSON-Zeichenkettendarstellung einer Python-Datenstruktur o zurück. Zum Beispiel:

>>> json.JSONEncoder().encode({"foo": ["bar", "baz"]})
'{"foo": ["bar", "baz"]}'

iterencode(o)¶

Kodiert das übergebene Objekt o und liefert jede Zeichenkettendarstellung, sobald sie verfügbar ist. Zum Beispiel:

for chunk in json.JSONEncoder().iterencode(bigobject):
    mysocket.write(chunk)

Ausnahmen¶

exception json.JSONDecodeError(msg, doc, pos)¶

Unterklasse von ValueError mit den folgenden zusätzlichen Attributen:

msg¶: Die unformatierte Fehlermeldung.

doc¶: Das JSON-Dokument, das eingelesen wird.

pos¶: Der Index in doc, an dem das Einlesen fehlschlug.

lineno¶: Die Zeile, die zu pos gehört.

colno¶: Die Spalte, die zu pos gehört.

Added in version 3.5.

Einhaltung des Standards und Zusammenspiel¶

Das JSON-Format ist in RFC 7159 und in ECMA-404 festgelegt. Dieser Abschnitt beschreibt, wie weit dieses Modul die RFC einhält. Der Einfachheit halber bleiben Unterklassen von JSONEncoder und JSONDecoder sowie alle nicht ausdrücklich genannten Parameter unberücksichtigt.

Dieses Modul hält die RFC nicht streng ein, sondern setzt einige Erweiterungen um, die gültiges JavaScript, aber kein gültiges JSON sind. Im Einzelnen:

Unendliche und NaN-Zahlenwerte werden angenommen und ausgegeben;
Mehrfach vorkommende Namen innerhalb eines Objekts werden angenommen, und nur der Wert des letzten Name-Wert-Paares wird verwendet.

Da die RFC es Parsern, die sie einhalten, erlaubt, Eingabetexte anzunehmen, die die RFC nicht einhalten, hält der Deserialisierer dieses Moduls die RFC mit den Voreinstellungen streng genommen ein.

Zeichenkodierungen¶

Die RFC verlangt, dass JSON in UTF-8, UTF-16 oder UTF-32 dargestellt wird, wobei UTF-8 für das bestmögliche Zusammenspiel empfohlen wird.

Wie es die RFC erlaubt, aber nicht verlangt, setzt der Serialisierer dieses Moduls voreingestellt ensure_ascii=True und maskiert die Ausgabe damit so, dass die entstehenden Zeichenketten nur druckbare ASCII-Zeichen enthalten.

Abgesehen vom Parameter ensure_ascii ist dieses Modul streng als Umwandlung zwischen Python-Objekten und Unicode-Zeichenketten definiert und befasst sich darüber hinaus nicht unmittelbar mit Zeichenkodierungen.

Die RFC verbietet es, am Anfang eines JSON-Textes eine Bytereihenfolgemarke (BOM) einzufügen, und der Serialisierer dieses Moduls fügt seiner Ausgabe keine BOM hinzu. Die RFC erlaubt es JSON-Deserialisierern, eine BOM am Anfang ihrer Eingabe zu übergehen, verlangt es aber nicht. Der Deserialisierer dieses Moduls löst einen ValueError aus, wenn eine BOM am Anfang steht.

Die RFC verbietet JSON-Zeichenketten mit Bytefolgen, die keinen gültigen Unicode-Zeichen entsprechen (etwa ungepaarte UTF-16-Surrogate), nicht ausdrücklich, weist aber darauf hin, dass sie Probleme beim Zusammenspiel verursachen können. Voreingestellt nimmt dieses Modul Codepunkte für solche Folgen an und gibt sie aus, sofern sie im ursprünglichen str vorkommen.

Unendliche und NaN-Zahlenwerte¶

Die RFC erlaubt es nicht, unendliche oder NaN-Zahlenwerte darzustellen. Dennoch nimmt dieses Modul voreingestellt Infinity, -Infinity und NaN an und gibt sie aus, als wären sie gültige JSON-Zahlenliterale:

>>> # Neither of these calls raises an exception, but the results are not valid JSON
>>> json.dumps(float('-inf'))
'-Infinity'
>>> json.dumps(float('nan'))
'NaN'
>>> # Same when deserializing
>>> json.loads('-Infinity')
-inf
>>> json.loads('NaN')
nan

Im Serialisierer lässt sich dieses Verhalten über den Parameter allow_nan ändern, im Deserialisierer über den Parameter parse_constant.

Mehrfach vorkommende Namen innerhalb eines Objekts¶

Die RFC legt fest, dass die Namen innerhalb eines JSON-Objekts eindeutig sein sollen, schreibt aber nicht vor, wie mit mehrfach vorkommenden Namen in JSON-Objekten umzugehen ist. Voreingestellt löst dieses Modul keine Ausnahme aus, sondern übergeht zu einem Namen alle Name-Wert-Paare bis auf das letzte:

>>> weird_json = '{"x": 1, "x": 2, "x": 3}'
>>> json.loads(weird_json)
{'x': 3}

Über den Parameter object_pairs_hook lässt sich dieses Verhalten ändern.

Werte auf oberster Ebene, die kein Objekt und kein Array sind¶

Die alte, in der überholten RFC 4627 festgelegte Fassung von JSON verlangte, dass der Wert auf der obersten Ebene eines JSON-Textes entweder ein JSON-Objekt oder ein JSON-Array ist (dict oder list in Python), und nicht null, ein Wahrheitswert, eine Zahl oder eine Zeichenkette. RFC 7159 hat diese Einschränkung aufgehoben. Dieses Modul setzt sie weder im Serialisierer noch im Deserialisierer um und hat das nie getan.

Dennoch möchtest du für das bestmögliche Zusammenspiel diese Einschränkung vielleicht freiwillig selbst einhalten.

Grenzen der Umsetzung¶

Manche Umsetzungen von JSON-Deserialisierern setzen Grenzen für:

die Größe der angenommenen JSON-Texte
die größte Verschachtelungstiefe von JSON-Objekten und -Arrays
den Bereich und die Genauigkeit von JSON-Zahlen
den Inhalt und die größte Länge von JSON-Zeichenketten

Dieses Modul setzt keine solchen Grenzen über die der betreffenden Python-Datentypen und des Python-Interpreters selbst hinaus.

Achte beim Serialisieren nach JSON auf solche Grenzen in Anwendungen, die dein JSON verarbeiten. Häufig werden JSON-Zahlen zu IEEE-754-Zahlen doppelter Genauigkeit deserialisiert und unterliegen damit den Grenzen dieser Darstellung bei Bereich und Genauigkeit. Das ist besonders dann wichtig, wenn du int-Werte von Python mit extrem großem Betrag serialisierst oder Instanzen „exotischer“ Zahlentypen wie decimal.Decimal.

Befehlszeilenschnittstelle¶

Quellcode: Lib/json/tool.py

Das Modul json lässt sich mit python -m json als Skript aufrufen, um JSON-Objekte zu prüfen und ansprechend auszugeben. Das Untermodul json.tool setzt diese Schnittstelle um.

Sind die optionalen Argumente infile und outfile nicht angegeben, werden sys.stdin beziehungsweise sys.stdout verwendet:

$ echo '{"json": "obj"}' | python -m json
{
    "json": "obj"
}
$ echo '{1.2:3.4}' | python -m json
Expecting property name enclosed in double quotes: line 1 column 2 (char 1)

Geändert in Version 3.5: Die Ausgabe hat jetzt dieselbe Reihenfolge wie die Eingabe. Mit der Option --sort-keys wird die Ausgabe von Dictionarys alphabetisch nach Schlüssel sortiert.

Geändert in Version 3.14: Das Modul json lässt sich jetzt unmittelbar als python -m json ausführen. Aus Gründen der Rückwärtskompatibilität wird der Aufruf als python -m json.tool weiter unterstützt.

Befehlszeilenoptionen¶

infile¶

Die JSON-Datei, die geprüft oder ansprechend ausgegeben werden soll:

$ python -m json mp_films.json
[
    {
        "title": "And Now for Something Completely Different",
        "year": 1971
    },
    {
        "title": "Monty Python and the Holy Grail",
        "year": 1975
    }
]

Ist infile nicht angegeben, wird aus sys.stdin gelesen.

outfile¶: Schreibt die Ausgabe von infile in die angegebene Datei outfile. Andernfalls wird sie nach sys.stdout geschrieben.

--sort-keys¶: Sortiert die Ausgabe von Dictionarys alphabetisch nach Schlüssel.

Added in version 3.5.

--no-ensure-ascii¶: Schaltet das Maskieren von Zeichen außerhalb von ASCII ab, siehe json.dumps().

Added in version 3.9.

--json-lines¶: Liest jede Eingabezeile als eigenes JSON-Objekt ein.

Added in version 3.8.

--indent, --tab, --no-indent, --compact¶: Einander ausschließende Optionen zur Steuerung des Leerraums.

Added in version 3.9.

-h, --help¶: Zeigt die Hilfe an.

Fußnoten

`json` — JSON-Kodierer und -Dekodierer¶

Grundlegende Verwendung¶

Kodierer und Dekodierer¶

Ausnahmen¶

Einhaltung des Standards und Zusammenspiel¶

Zeichenkodierungen¶

Unendliche und NaN-Zahlenwerte¶

Mehrfach vorkommende Namen innerhalb eines Objekts¶

Werte auf oberster Ebene, die kein Objekt und kein Array sind¶

Grenzen der Umsetzung¶

Befehlszeilenschnittstelle¶

Befehlszeilenoptionen¶

Inhaltsverzeichnis

Vorheriges Thema

Nächstes Thema

Diese Seite

json — JSON-Kodierer und -Dekodierer¶

Grundlegende Verwendung¶

Kodierer und Dekodierer¶

Ausnahmen¶

Einhaltung des Standards und Zusammenspiel¶

Zeichenkodierungen¶

Unendliche und NaN-Zahlenwerte¶

Mehrfach vorkommende Namen innerhalb eines Objekts¶

Werte auf oberster Ebene, die kein Objekt und kein Array sind¶

Grenzen der Umsetzung¶

Befehlszeilenschnittstelle¶

Befehlszeilenoptionen¶

`json` — JSON-Kodierer und -Dekodierer¶