`json` — JSON-Encoder und -Decoder¶

Quellcode: Lib/json/__init__.py

JSON (JavaScript Object Notation), spezifiziert durch RFC 7159 (der RFC 4627 ablöst) und durch ECMA-404, ist ein leichtgewichtiges Datenaustauschformat, das von der JavaScript-Objektliteralsyntax inspiriert ist (obwohl es kein strikter Teil der JavaScript-Syntax ist [1] ).

Hinweis

Der Begriff „Objekt“ im Kontext der JSON-Verarbeitung in Python kann mehrdeutig sein. Alle Werte in Python sind Objekte. In JSON bezieht sich ein Objekt auf beliebige Daten, die in geschweifte Klammern eingeschlossen sind, ähnlich einem Python-Dictionary.

Warnung

Seien Sie vorsichtig beim Parsen von JSON-Daten aus nicht vertrauenswürdigen Quellen. Eine bösartige JSON-Zeichenkette kann dazu führen, dass der Decoder erhebliche CPU- und Speicherressourcen verbraucht. Es wird empfohlen, die Größe der zu parsierenden Daten zu begrenzen.

Dieses Modul stellt eine API bereit, die Benutzern der Standardbibliotheksmodule marshal und pickle vertraut ist.

Kodierung einfacher Python-Objekthierarchien

>>> 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"]'

Kompakte Kodierung

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

Schöne Formatierung (Pretty Printing)

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

Anpassen der JSON-Objektkodierung

>>> 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}'

Dekodierung von JSON

>>> 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']

Anpassen der JSON-Objektdokodierung

>>> 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')

Erweitern von JSONEncoder

>>> 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', ']']

Verwendung von json von der Shell zur Validierung und schönen Formatierung

$ 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)

Siehe Kommandozeilenschnittstelle für detaillierte Dokumentation.

Hinweis

JSON ist eine Teilmenge von YAML 1.2. Das von den Standardeinstellungen dieses Moduls erzeugte JSON (insbesondere der Standardwert für separators) ist auch eine Teilmenge von YAML 1.0 und 1.1. Dieses Modul kann somit auch als YAML-Serialisierer verwendet werden.

Hinweis

Die Encoder und Decoder dieses Moduls behalten standardmäßig die Eingabe- und Ausgabereihenfolge bei. Die Reihenfolge geht nur verloren, wenn die zugrunde liegenden Container ungeordnet 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 Stream nach fp (ein .write()-unterstützendes Datei-ähnliches Objekt) unter Verwendung dieser Python-zu-JSON-Konvertierungstabelle.

Hinweis

Im Gegensatz zu pickle und marshal ist JSON kein Framing-Protokoll, daher führt der Versuch, mehrere Objekte mit wiederholten Aufrufen von dump() mit demselben fp zu serialisieren, zu einer ungültigen JSON-Datei.

Parameter:

obj (Objekt) – Das zu serialisierende Python-Objekt.
fp (Datei-ähnliches Objekt) – Das Datei-ähnliche Objekt, zu dem obj serialisiert wird. Das Modul json erzeugt immer str-Objekte, keine bytes-Objekte, daher muss fp.write() str-Eingaben unterstützen.
skipkeys (bool) – Wenn True, werden Schlüssel, die nicht vom Basistyp sind (str, int, float, bool, None), übersprungen, anstatt einen TypeError auszulösen. Standard ist False.
ensure_ascii (bool) – Wenn True (Standard), ist die Ausgabe garantiert, dass alle eingehenden Nicht-ASCII-Zeichen maskiert sind. Wenn False, werden diese Zeichen unverändert ausgegeben.
check_circular (bool) – Wenn False, wird die Prüfung auf zirkuläre Referenzen für Containertypen übersprungen und eine zirkuläre Referenz führt zu einem RecursionError (oder schlimmer). Standard ist True.
allow_nan (bool) – Wenn False, führt die Serialisierung von Gleitkommawerten außerhalb des Bereichs (nan, inf, -inf) zu einem ValueError, in strikter Übereinstimmung mit der JSON-Spezifikation. Wenn True (Standard), werden ihre JavaScript-Äquivalente (NaN, Infinity, -Infinity) verwendet.
cls (eine Unterklasse von JSONEncoder) – Wenn gesetzt, ein benutzerdefinierter JSON-Encoder mit überschriebener Methode default() , zur Serialisierung in benutzerdefinierte Datentypen. Wenn None (Standard), wird JSONEncoder verwendet.
indent (int | str | None) – Wenn eine positive Ganzzahl oder Zeichenkette, werden JSON-Array-Elemente und Objektmember mit diesem Einrückungsgrad schön formatiert. Eine positive Ganzzahl rückt mit so vielen Leerzeichen pro Ebene ein; eine Zeichenkette (wie "\t") wird verwendet, um jede Ebene einzurücken. Wenn null, negativ oder "" (leere Zeichenkette), werden nur Zeilenumbrüche eingefügt. Wenn None (Standard), wird die kompakteste Darstellung verwendet.
separators (Tupel | None) – Ein Tupel aus zwei Elementen: (item_separator, key_separator). Wenn None (Standard), ist separators standardmäßig (',', ' '), wenn indent None ist, und (',', ': ') andernfalls. Für das kompakteste JSON geben Sie (',', ':') an, um Leerzeichen zu eliminieren.
default (Aufrufbar | None) – Eine Funktion, die für Objekte aufgerufen wird, die nicht anders serialisiert werden können. Sie sollte eine JSON-kodierbare Version des Objekts zurückgeben oder einen TypeError auslösen. Wenn None (Standard), wird TypeError ausgelöst.
sort_keys (bool) – Wenn True, werden Dictionaries nach Schlüssel sortiert ausgegeben. Standard ist False.

Geändert in Version 3.2: Zeichenketten für indent zusätzlich zu Ganzzahlen erlaubt.

Geändert in Version 3.4: Verwendet (',', ': ') als Standard, wenn indent nicht None ist.

Geändert in Version 3.6: Alle optionalen Parameter sind nun keyword-only.

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 in eine JSON-formatierte str unter Verwendung dieser Konvertierungstabelle. Die Argumente haben die gleiche Bedeutung wie in dump().

Hinweis

Schlüssel in Schlüssel/Wert-Paaren von JSON sind immer vom Typ str. Wenn ein Dictionary in JSON konvertiert wird, werden alle Schlüssel des Dictionaries in Zeichenketten umgewandelt. Infolgedessen kann das Dictionary, wenn es in JSON und dann zurück in ein Dictionary konvertiert wird, nicht mit dem Original übereinstimmen. Das heißt, loads(dumps(x)) != x, wenn x Nicht-String-Schlüssel hat.

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

Dekodiert fp zu einem Python-Objekt unter Verwendung der JSON-zu-Python-Konvertierungstabelle.

Parameter:

fp (Datei-ähnliches Objekt) – Eine .read()-unterstützende Textdatei oder Binärdatei, die das zu dekodierende JSON-Dokument enthält.
cls (eine Unterklasse von JSONDecoder) – Wenn gesetzt, ein benutzerdefinierter JSON-Decoder. Zusätzliche Schlüsselwortargumente für load() werden an den Konstruktor von cls übergeben. Wenn None (Standard), wird JSONDecoder verwendet.
object_hook (Aufrufbar | None) – Wenn gesetzt, eine Funktion, die mit dem Ergebnis jedes dekodierten JSON-Objekts aufgerufen wird (ein dict). Der Rückgabewert dieser Funktion wird anstelle des dict verwendet. Diese Funktion kann verwendet werden, um benutzerdefinierte Dekoder zu implementieren, z. B. für die JSON-RPC-Klassenhinweise.
object_pairs_hook (Aufrufbar | None) – Wenn gesetzt, eine Funktion, die mit dem Ergebnis jedes JSON-Objekts aufgerufen wird, das mit einer geordneten Liste von Paaren dekodiert wurde. Der Rückgabewert dieser Funktion wird anstelle des dict verwendet. Diese Funktion kann zur Implementierung benutzerdefinierter Dekoder verwendet werden. Wenn object_hook ebenfalls gesetzt ist, hat object_pairs_hook Vorrang. Standard ist None.
parse_float (Aufrufbar | None) – Wenn gesetzt, eine Funktion, die mit der Zeichenkette jedes zu dekodierenden JSON-Gleitkommawerts aufgerufen wird. Wenn None (Standard), ist dies äquivalent zu float(num_str). Dies kann verwendet werden, um JSON-Gleitkommawerts in benutzerdefinierte Datentypen zu parsen, z. B. decimal.Decimal.
parse_int (Aufrufbar | None) – Wenn gesetzt, eine Funktion, die mit der Zeichenkette jedes zu dekodierenden JSON-Ganzzahlwerts aufgerufen wird. Wenn None (Standard), ist dies äquivalent zu int(num_str). Dies kann verwendet werden, um JSON-Ganzzahlen in benutzerdefinierte Datentypen zu parsen, z. B. float.
parse_constant (Aufrufbar | None) – Wenn gesetzt, eine Funktion, die mit einer der folgenden Zeichenketten aufgerufen wird: '-Infinity', 'Infinity' oder 'NaN'. Dies kann verwendet werden, um eine Ausnahme auszulösen, wenn ungültige JSON-Zahlen angetroffen werden. Standard ist None.

Löst aus:

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

Geändert in Version 3.1

Der optionale Parameter object_pairs_hook wurde hinzugefügt.
parse_constant wird nicht mehr für „null“, „true“, „false“ aufgerufen.

Geändert in Version 3.6

Alle optionalen Parameter sind nun keyword-only.
fp kann nun eine Binärdatei sein. Die Eingabekodierung sollte UTF-8, UTF-16 oder UTF-32 sein.

Geändert in Version 3.11: Die Standardfunktion parse_int von int() beschränkt nun die maximale Länge der Ganzzahlzeichenkette über die Beschränkung der Länge der Ganzzahlzeichenkettenkonvertierung des Interpreters, um Denial-of-Service-Angriffe zu vermeiden.

json.loads(s, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)¶: Identisch mit load(), aber anstatt eines Datei-ähnlichen Objekts wird s (eine Instanz von str, bytes oder bytearray, das ein JSON-Dokument enthält) mithilfe dieser Konvertierungstabelle zu einem Python-Objekt deserialisiert.

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

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

Encoder und Decoder¶

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

Einfacher JSON-Decoder.

Führt standardmäßig die folgenden Übersetzungen bei der Dekodierung durch

JSON	Python
Objekt	dict
array	Liste
string	str
number (int)	int
number (real)	float
true	True
false	False
null	None

Er versteht auch NaN, Infinity und -Infinity als ihre entsprechenden float-Werte, was außerhalb der JSON-Spezifikation liegt.

object_hook ist eine optionale Funktion, die mit dem Ergebnis jedes dekodierten JSON-Objekts aufgerufen wird und deren Rückgabewert anstelle des gegebenen dict verwendet wird. Dies kann verwendet werden, um benutzerdefinierte Deserialisierungen bereitzustellen (z. B. zur Unterstützung von JSON-RPC-Klassenhinweisen).

object_pairs_hook ist eine optionale Funktion, die mit dem Ergebnis jedes JSON-Objekts aufgerufen wird, das mit einer geordneten Liste von Paaren dekodiert wurde. Der Rückgabewert von object_pairs_hook wird anstelle des dict verwendet. Diese Funktion kann zur Implementierung benutzerdefinierter Dekoder verwendet werden. Wenn object_hook ebenfalls definiert ist, hat object_pairs_hook Vorrang.

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

parse_float ist eine optionale Funktion, die mit der Zeichenkette jedes zu dekodierenden JSON-Gleitkommawerts aufgerufen wird. Standardmäßig ist dies äquivalent zu float(num_str). Dies kann verwendet werden, um einen anderen Datentyp oder Parser für JSON-Gleitkommawerts zu verwenden (z. B. decimal.Decimal).

parse_int ist eine optionale Funktion, die mit der Zeichenkette jedes zu dekodierenden JSON-Ganzzahlwerts aufgerufen wird. Standardmäßig ist dies äquivalent zu int(num_str). Dies kann verwendet werden, um einen anderen Datentyp oder Parser für JSON-Ganzzahlen zu verwenden (z. B. float).

parse_constant ist eine optionale Funktion, die mit einer der folgenden Zeichenketten aufgerufen wird: '-Infinity', 'Infinity', 'NaN'. Dies kann verwendet werden, um eine Ausnahme auszulösen, wenn ungültige JSON-Zahlen angetroffen werden.

Wenn strict false ist (True ist der Standard), dann werden Steuerzeichen innerhalb von Zeichenketten erlaubt. Steuerzeichen sind in diesem Kontext solche mit Zeichencodes im Bereich 0–31, einschließlich '\t' (Tabulator), '\n', '\r' und '\0'.

Wenn die zu dekodierenden Daten kein gültiges JSON-Dokument sind, wird ein JSONDecodeError ausgelöst.

Geändert in Version 3.6: Alle Parameter sind nun keyword-only.

decode(s)¶

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

Es wird eine JSONDecodeError ausgelöst, wenn das angegebene JSON-Dokument ungültig ist.

raw_decode(s)¶

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

Dies kann verwendet werden, um ein JSON-Dokument aus einer Zeichenfolge zu dekodieren, die zusätzliche Daten am Ende enthalten kann.

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-Encoder für Python-Datenstrukturen.

Unterstützt standardmäßig die folgenden Objekte und Typen

Python	JSON
dict	Objekt
list, tuple	array
str	string
int, float, von int und float abgeleitete Enums	Nummer
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.

Um dies zu erweitern und andere Objekte zu erkennen, leiten Sie eine Unterklasse ab und implementieren Sie eine default()-Methode, die ein serialisierbares Objekt für o zurückgibt, falls möglich, andernfalls sollte sie die Implementierung der Basisklasse aufrufen (um TypeError auszulösen).

Wenn skipkeys false (Standard) ist, wird ein TypeError ausgelöst, wenn versucht wird, Schlüssel zu kodieren, die keine str, int, float, bool oder None sind. Wenn skipkeys true ist, werden solche Elemente einfach übersprungen.

Wenn ensure_ascii true (Standard) ist, wird die Ausgabe garantiert alle eingehenden Nicht-ASCII-Zeichen maskiert haben. Wenn ensure_ascii false ist, werden diese Zeichen unverändert ausgegeben.

Wenn check_circular true (Standard) ist, werden Listen, Dictionaries und benutzerdefiniert kodierte Objekte während der Kodierung auf zirkuläre Referenzen geprüft, um eine unendliche Rekursion (die zu einem RecursionError führen würde) zu verhindern. Andernfalls findet keine solche Prüfung statt.

Wenn allow_nan true (Standard) ist, werden NaN, Infinity und -Infinity als solche kodiert. Dieses Verhalten ist nicht konform mit der JSON-Spezifikation, stimmt aber mit den meisten JavaScript-basierten Encodern und Decodern überein. Andernfalls wird die Kodierung solcher Gleitkommazahlen mit einem ValueError abgelehnt.

Wenn sort_keys true (Standard: False) ist, werden die Ausgaben von Dictionaries alphabetisch nach Schlüssel sortiert; dies ist nützlich für Regressionstests, um sicherzustellen, dass JSON-Serialisierungen täglich verglichen werden können.

Wenn indent eine nicht-negative Ganzzahl oder Zeichenkette ist, werden JSON-Array-Elemente und Objektmember mit diesem Einrückungslevel hübsch gedruckt. Ein Einrückungslevel von 0, negativ oder "" fügt nur Zeilenumbrüche ein. None (Standard) wählt die kompakteste Darstellung. Die Verwendung einer positiven Ganzzahl-Einrückung rückt jede Ebene um so viele Leerzeichen ein. Wenn indent eine Zeichenkette ist (wie z.B. "\t"), wird diese Zeichenkette zur Einrückung jeder Ebene verwendet.

Geändert in Version 3.2: Zeichenketten für indent zusätzlich zu Ganzzahlen erlaubt.

Falls angegeben, sollte separators ein (item_separator, key_separator) Tupel sein. Der Standardwert ist (', ', ': '), wenn indent None ist, und (',', ': ') andernfalls. Um die kompakteste JSON-Darstellung zu erhalten, sollten Sie (',', ':') angeben, um Leerzeichen zu eliminieren.

Geändert in Version 3.4: Verwendet (',', ': ') als Standard, wenn indent nicht None ist.

Falls angegeben, sollte default eine Funktion sein, die für Objekte aufgerufen wird, die nicht anderweitig serialisiert werden können. Sie sollte eine JSON-kodierbare Version des Objekts zurückgeben oder einen TypeError auslösen. Wenn nicht angegeben, wird ein TypeError ausgelöst.

Geändert in Version 3.6: Alle Parameter sind nun keyword-only.

default(o)¶

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

Um beispielsweise beliebige Iteratoren zu unterstützen, könnten Sie default() wie folgt implementieren

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-Zeichenkettenrepräsentation einer Python-Datenstruktur, o, zurück. Zum Beispiel

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

iterencode(o)¶

Kodiert das gegebene Objekt o und liefert jede Zeichenkettenrepräsentation, 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 ungeformatierte Fehlermeldung.

doc¶: Das zu parsende JSON-Dokument.

pos¶: Der Startindex von doc, an dem die Analyse fehlgeschlagen ist.

lineno¶: Die Zeile, die pos entspricht.

colno¶: Die Spalte, die pos entspricht.

Hinzugefügt in Version 3.5.

Konformität und Interoperabilität mit Standards¶

Das JSON-Format wird von RFC 7159 und von ECMA-404 spezifiziert. Dieser Abschnitt beschreibt den Grad der Konformität dieses Moduls mit dem RFC. Der Einfachheit halber werden JSONEncoder- und JSONDecoder-Unterklassen und Parameter, die nicht ausdrücklich erwähnt werden, nicht berücksichtigt.

Dieses Modul ist nicht streng konform mit dem RFC, sondern implementiert einige Erweiterungen, die gültiges JavaScript, aber kein gültiges JSON sind. Insbesondere

Unendliche und NaN-Zahlenwerte werden akzeptiert und ausgegeben;
Wiederholte Namen innerhalb eines Objekts werden akzeptiert, und nur der Wert des letzten Namens-Wert-Paares wird verwendet.

Da der RFC RFC-konforme Parser erlaubt, Eingabetexte zu akzeptieren, die nicht RFC-konform sind, ist der Deserialisierer dieses Moduls unter Standardeinstellungen technisch RFC-konform.

Zeichenkodierungen¶

Der RFC verlangt, dass JSON entweder mit UTF-8, UTF-16 oder UTF-32 dargestellt wird, wobei UTF-8 als empfohlener Standard für maximale Interoperabilität gilt.

Wie vom RFC erlaubt, aber nicht vorgeschrieben, setzt der Serialisierer dieses Moduls standardmäßig ensure_ascii=True und maskiert somit die Ausgabe, so dass die resultierenden Zeichenketten nur ASCII-Zeichen enthalten.

Abgesehen vom Parameter ensure_ascii ist dieses Modul streng in Bezug auf die Konvertierung zwischen Python-Objekten und Unicode-Zeichenketten definiert und befasst sich somit nicht direkt mit dem Problem der Zeichenkodierungen.

Der RFC verbietet das Hinzufügen eines Byte Order Mark (BOM) am Anfang eines JSON-Textes, und der Serialisierer dieses Moduls fügt seiner Ausgabe keinen BOM hinzu. Der RFC erlaubt, aber schreibt nicht vor, dass JSON-Deserialisierer einen anfänglichen BOM in ihrer Eingabe ignorieren. Der Deserialisierer dieses Moduls löst einen ValueError aus, wenn ein anfänglicher BOM vorhanden ist.

Der RFC verbietet nicht ausdrücklich JSON-Zeichenketten, die Byte-Sequenzen enthalten, die keinen gültigen Unicode-Zeichen entsprechen (z.B. ungepaarte UTF-16-Surrogate), aber er stellt fest, dass sie Interoperabilitätsprobleme verursachen können. Standardmäßig akzeptiert und gibt dieses Modul (wenn in der ursprünglichen str vorhanden) Codepunkte für solche Sequenzen aus.

Unendliche und NaN-Zahlenwerte¶

Der RFC erlaubt nicht die Darstellung von unendlichen oder NaN-Zahlenwerten. Trotzdem akzeptiert und gibt dieses Modul standardmäßig Infinity, -Infinity und NaN 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 kann der Parameter allow_nan verwendet werden, um dieses Verhalten zu ändern. Im Deserialisierer kann der Parameter parse_constant verwendet werden, um dieses Verhalten zu ändern.

Wiederholte Namen innerhalb eines Objekts¶

Der RFC legt fest, dass die Namen innerhalb eines JSON-Objekts eindeutig sein sollten, gibt jedoch nicht vor, wie wiederholte Namen in JSON-Objekten behandelt werden sollen. Standardmäßig löst dieses Modul keine Ausnahme aus; stattdessen ignoriert es alle außer dem letzten Namens-Wert-Paar für einen gegebenen Namen.

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

Der Parameter object_pairs_hook kann verwendet werden, um dieses Verhalten zu ändern.

Werte auf oberster Ebene, die keine Objekte oder Arrays sind¶

Die alte Version von JSON, die durch die veraltete RFC 4627 spezifiziert wurde, verlangte, dass der Wert auf oberster Ebene eines JSON-Textes entweder ein JSON-Objekt oder ein Array (Python dict oder list) sein musste und kein JSON-Null-, boolescher, numerischer oder Zeichenkettenwert sein konnte. RFC 7159 hat diese Einschränkung aufgehoben, und dieses Modul hat diese Einschränkung weder in seinem Serialisierer noch in seinem Deserialisierer implementiert oder jemals implementiert.

Unabhängig davon möchten Sie zur Maximierung der Interoperabilität möglicherweise die Einschränkung freiwillig selbst einhalten.

Implementierungsbeschränkungen¶

Einige JSON-Deserialisierer-Implementierungen können Grenzwerte festlegen für

die Größe akzeptierter JSON-Texte
die maximale Verschachtelungstiefe von JSON-Objekten und -Arrays
den Bereich und die Präzision von JSON-Zahlen
den Inhalt und die maximale Länge von JSON-Zeichenketten

Dieses Modul legt keine solchen Grenzen fest, außer denen der jeweiligen Python-Datentypen selbst oder des Python-Interpreters selbst.

Beim Serialisieren nach JSON sollten Sie sich vor solchen Einschränkungen in Anwendungen in Acht nehmen, die Ihr JSON konsumieren könnten. Insbesondere ist es üblich, dass JSON-Zahlen in IEEE 754 doppelt genaue Gleitkommazahlen deserialisiert werden und somit den Bereichs- und Präzisionsbeschränkungen dieser Darstellung unterliegen. Dies ist besonders relevant beim Serialisieren von Python int-Werten von extrem großer Magnitude oder beim Serialisieren von Instanzen „exotischer“ numerischer Typen wie decimal.Decimal.

Befehlszeilenschnittstelle¶

Quellcode: Lib/json/tool.py

Das Modul json kann als Skript über python -m json aufgerufen werden, um JSON-Objekte zu validieren und hübsch zu drucken. Das Untermodul json.tool implementiert diese Schnittstelle.

Wenn die optionalen Argumente infile und outfile nicht angegeben sind, werden sys.stdin bzw. 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 erfolgt nun in der gleichen Reihenfolge wie die Eingabe. Verwenden Sie die Option --sort-keys, um die Ausgabe von Dictionaries alphabetisch nach Schlüssel zu sortieren.

Geändert in Version 3.14: Das Modul json kann jetzt direkt als python -m json ausgeführt werden. Aus Kompatibilitätsgründen bleibt die Ausführung der CLI als python -m json.tool unterstützt.

Kommandozeilenoptionen¶

infile¶

Die zu validierende oder hübsch zu druckende JSON-Datei.

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

Wenn infile nicht angegeben ist, wird von sys.stdin gelesen.

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

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

Hinzugefügt in Version 3.5.

--no-ensure-ascii¶: Deaktiviert das Maskieren von Nicht-ASCII-Zeichen. Weitere Informationen finden Sie unter json.dumps().

Hinzugefügt in Version 3.9.

--json-lines¶: Parst jede Eingabezeile als separates JSON-Objekt.

Hinzugefügt in Version 3.8.

--indent, --tab, --no-indent, --compact¶: Sich gegenseitig ausschließende Optionen für die Steuerung von Whitespace.

Hinzugefügt in Version 3.9.

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

Fußnoten

`json` — JSON-Encoder und -Decoder¶

Grundlegende Verwendung¶

Encoder und Decoder¶

Ausnahmen¶

Konformität und Interoperabilität mit Standards¶

Zeichenkodierungen¶

Unendliche und NaN-Zahlenwerte¶

Wiederholte Namen innerhalb eines Objekts¶

Werte auf oberster Ebene, die keine Objekte oder Arrays sind¶

Implementierungsbeschränkungen¶

Befehlszeilenschnittstelle¶

Kommandozeilenoptionen¶

Inhaltsverzeichnis

Vorheriges Thema

Nächstes Thema

Diese Seite

json — JSON-Encoder und -Decoder¶

Grundlegende Verwendung¶

Encoder und Decoder¶

Ausnahmen¶

Konformität und Interoperabilität mit Standards¶

Zeichenkodierungen¶

Unendliche und NaN-Zahlenwerte¶

Wiederholte Namen innerhalb eines Objekts¶

Werte auf oberster Ebene, die keine Objekte oder Arrays sind¶

Implementierungsbeschränkungen¶

Befehlszeilenschnittstelle¶

Kommandozeilenoptionen¶

`json` — JSON-Encoder und -Decoder¶