tomllib — TOML-Dateien parsen

Quellcode: Lib/tomllib

---

Dieses Modul bietet eine Schnittstelle zum Parsen von TOML 1.1.0 (Tom’s Obvious Minimal Language, https://toml.io). Das Schreiben von TOML unterstützt dieses Modul nicht.

Added in version 3.11: Das Modul wurde mit Unterstützung für TOML 1.0.0 hinzugefügt.

Geändert in Version 3.15: Unterstützung für TOML 1.1.0 hinzugefügt. Einzelheiten unter Was ist neu.

Warnung

Sei vorsichtig beim Parsen von Daten aus nicht vertrauenswürdigen Quellen. Eine bösartige TOML-Zeichenkette kann den Decoder dazu bringen, erhebliche CPU- und Speicherressourcen zu verbrauchen. Es empfiehlt sich, die Größe der zu parsenden Daten zu begrenzen.

Siehe auch

Das Paket Tomli-W ist ein TOML-Schreiber, der sich zusammen mit diesem Modul verwenden lässt. Es bietet eine Schreib-API, die Nutzern der Standardbibliotheksmodule marshal und pickle vertraut ist.

Siehe auch

Das Paket TOML Kit ist eine stilerhaltende TOML-Bibliothek, die sowohl lesen als auch schreiben kann. Für das Bearbeiten bereits vorhandener TOML-Dateien ist es der empfohlene Ersatz für dieses Modul.

Dieses Modul definiert die folgenden Funktionen:

tomllib.load(fp, /, *, parse_float=float)

Liest eine TOML-Datei. Das erste Argument sollte ein lesbares, binäres Dateiobjekt sein. Gibt ein dict zurück. Wandelt TOML-Typen anhand dieser Umwandlungstabelle nach Python um.

parse_float wird mit der Zeichenkette jeder zu dekodierenden TOML-Gleitkommazahl aufgerufen. Voreingestellt entspricht das float(num_str). Damit lässt sich ein anderer Datentyp oder Parser für TOML-Gleitkommazahlen verwenden (z. B. decimal.Decimal). Das aufrufbare Objekt darf kein dict und keine list zurückgeben, sonst wird ValueError ausgelöst.

Bei einem ungültigen TOML-Dokument wird TOMLDecodeError ausgelöst.

tomllib.loads(s, /, *, parse_float=float)

Lädt TOML aus einem str-Objekt. Gibt ein dict zurück. Wandelt TOML-Typen anhand dieser Umwandlungstabelle nach Python um. Das Argument parse_float hat dieselbe Bedeutung wie bei load().

Bei einem ungültigen TOML-Dokument wird TOMLDecodeError ausgelöst.

Die folgenden Ausnahmen stehen zur Verfügung:

exception tomllib.TOMLDecodeError(msg, doc, pos)

Unterklasse von ValueError mit den folgenden zusätzlichen Attributen:

msg

Die unformatierte Fehlermeldung.

doc

Das TOML-Dokument, das geparst wird.

pos

Der Index in doc, an dem das Parsen fehlgeschlagen ist.

lineno

Die Zeile, die pos entspricht.

colno

Die Spalte, die pos entspricht.

Geändert in Version 3.14: Die Parameter msg, doc und pos wurden hinzugefügt. Die Attribute msg, doc, pos, lineno und colno wurden hinzugefügt.

Veraltet ab Version 3.14: Das Übergeben formfreier Positionsargumente ist veraltet.

Beispiele

Eine TOML-Datei parsen:

import tomllib

with open("pyproject.toml", "rb") as f:
    data = tomllib.load(f)

Eine TOML-Zeichenkette parsen:

import tomllib

toml_str = """
python-version = "3.11.0"
python-implementation = "CPython"
"""

data = tomllib.loads(toml_str)

Umwandlungstabelle

TOML	Python
TOML-Dokument	dict
Zeichenkette	str
Ganzzahl	int
float	float (über parse_float einstellbar)
boolescher Wert	bool
Datum und Uhrzeit mit Zeitzonenversatz	datetime.datetime (Attribut tzinfo auf eine Instanz von datetime.timezone gesetzt)
lokales Datum mit Uhrzeit	datetime.datetime (Attribut tzinfo auf None gesetzt)
lokales Datum	datetime.date
lokale Uhrzeit	datetime.time
Array	Liste
Tabelle	dict
Inline-Tabelle	dict
Array von Tabellen	list of dicts

Grenzen und Hinweise zur Interoperabilität

tomllib setzt den Dokumenten, die es verarbeiten kann, einige Grenzen und bewahrt Einzelheiten, die andere TOML-Parser ignorieren dürfen. Verwende beim Schreiben portabler TOML-Dateien nur Features, die der Standard zusichert oder empfiehlt.

Die hier aufgeführten Einzelheiten der Umsetzung können sich in künftigen Python-Versionen ändern.

Tabellen/Dictionarys

Die TOML-Spezifikation sichert nicht zu, dass Schlüssel-Wert-Paare in TOML-Dokumenten und Tabellen in einer bestimmten Reihenfolge stehen.

tomllib lädt Dictionary-Einträge in der Reihenfolge, in der sie in der Quelle stehen.

Ganze Zahlen

TOML empfiehlt, ganze Zahlen im Bereich range(-2**63, 2**63) zu unterstützen.

tomllib verwendet Pythons Grenze für die Umwandlung ganzer Zahlen in Zeichenketten (voreingestellt 4300 Stellen).

Gleitkommazahlen

TOML empfiehlt, mindestens Werte nach IEEE 754 binary64 zu unterstützen. Zahlen mit mehr als 15 signifikanten Dezimalstellen werden daher wahrscheinlich gerundet.

tomllib verwendet voreingestellt Pythons float. Auf vielen verbreiteten Plattformen ist das das empfohlene binary64. Näheres unter sys.float_info.

Verschachtelungsgrenze

TOML 1.1.0 empfiehlt keine Grenze dafür, wie tief Arrays und Tabellen ineinander verschachtelt sein dürfen. (Für eine künftige TOML-Version ist eine Grenze von 100 vorgeschlagen.)

In tomllib wird die Verschachtelungstiefe im Wesentlichen durch Pythons Rekursionsgrenze begrenzt. Beachte, dass auch Code, der tomllib aufruft, zu dieser Grenze beiträgt.