Stabilität von TOML

Die Veröffentlichung von TOML 1.0.0 im Januar 2021 deutet darauf hin, dass das TOML-Format nun offiziell als stabil betrachtet werden sollte. Empirisch hat sich TOML auch vor der Veröffentlichung von TOML 1.0.0 als stabiles Format erwiesen. Aus dem Changelog geht hervor, dass TOML seit April 2020 keine größeren Änderungen mehr erfahren hat und in den letzten fünf Jahren (2017-2021) zwei Versionen hatte.

Im Falle von Änderungen an der TOML-Spezifikation können wir kleinere Überarbeitungen als Fehlerbehebungen behandeln und die Implementierung an Ort und Stelle aktualisieren. Im Falle von größeren, nicht abwärtskompatiblen Änderungen sollten wir die Unterstützung für TOML 1.x beibehalten.

Wartbarkeit der vorgeschlagenen Implementierung

Die vorgeschlagene Implementierung (tomli) ist reines Python, gut getestet und wiegt unter 1000 Zeilen Code. Sie ist minimalistisch und bietet eine geringere API-Oberfläche als andere TOML-Implementierungen.

Der Autor von tomli ist bereit, bei der Integration von tomli in die Standardbibliothek zu helfen und bei der Wartung zu unterstützen, wie in diesem Beitrag dargelegt. Darüber hinaus hat der Python-Core-Entwickler Petr Viktorin seine Bereitschaft signalisiert, eine Lese-API zu warten, wie in diesem Beitrag.

Eine Neufassung des Parsers in C wird derzeit nicht als notwendig erachtet. Es ist selten, dass das Parsen von TOML ein Flaschenhals in Anwendungen ist, und Benutzer mit höheren Leistungsanforderungen können eine Drittanbieterbibliothek verwenden (wie es bei JSON oft der Fall ist, obwohl Python ein C-Erweiterungsmodul in der Standardbibliothek anbietet).

TOML-Unterstützung: eine rutschige Bahn für andere Dinge

Wie im Abschnitt Motivation diskutiert, hat TOML im Python-Ökosystem einen besonderen Stellenwert für das Lesen von PEP 518 pyproject.toml-Paketierungs- und Toolkonfigurationsdateien. Dieser Hauptgrund für die Aufnahme von TOML in die Standardbibliothek trifft nicht auf andere Formate wie YAML oder MessagePack zu.

Darüber hinaus unterscheidet die Einfachheit von TOML es von anderen Formaten wie YAML, die äußerst komplex zu erstellen und zu parsen sind.

Eine API zum Schreiben von TOML kann jedoch in einem zukünftigen PEP hinzugefügt werden.

Basierend auf einer anderen TOML-Implementierung

Mehrere potenzielle alternative Implementierungen existieren

• tomlkit ist gut etabliert, aktiv gewartet und unterstützt TOML 1.0.0. Ein wichtiger Unterschied ist, dass tomlkit das Roundtripping von Stil unterstützt. Infolgedessen hat es eine komplexere API und Implementierung (etwa 5x so viel Code wie tomli). Sein Autor glaubt nicht, dass tomlkit eine gute Wahl für die Standardbibliothek ist.
• toml ist eine sehr weit verbreitete Bibliothek. Sie wird jedoch nicht aktiv gewartet, unterstützt TOML 1.0.0 nicht und hat eine Reihe bekannter Fehler. Ihre API ist komplexer als die von tomli. Sie ermöglicht die Anpassung des Ausgabeformats über eine komplizierte Encoder-API und einige sehr begrenzte und meist ungenutzte Funktionen zur Erhaltung des Eingabestils über eine undokumentierte Decoder-API. Weitere Details zu ihren API-Unterschieden zu diesem PEP finden Sie in Anhang A.
• pytomlpp ist ein Python-Wrapper für das C++-Projekt toml++. Reine Python-Bibliotheken sind einfacher zu warten als Erweiterungsmodule.
• rtoml ist ein Python-Wrapper für das Rust-Projekt toml-rs und hat daher ähnliche Nachteile wie pytomlpp. Außerdem unterstützt es TOML 1.0.0 nicht.
• Eine Implementierung von Grund auf neu zu schreiben. Es ist unklar, was wir dadurch gewinnen würden; tomli erfüllt unsere Bedürfnisse und der Autor ist bereit, bei der Aufnahme in die Standardbibliothek zu helfen.

Einbeziehung einer API zum Schreiben von TOML

Es gibt mehrere Gründe, keine API zum Schreiben von TOML aufzunehmen.

Die Fähigkeit, TOML zu schreiben, wird für die Anwendungsfälle, die dieses PEP motivieren, nicht benötigt: Kern Python-Paketierungswerkzeuge und Projekte, die TOML-Konfigurationsdateien lesen müssen.

Anwendungsfälle, die die Bearbeitung einer vorhandenen TOML-Datei beinhalten (im Gegensatz zum Schreiben einer völlig neuen), werden besser von einer stil-erhaltenden Bibliothek bedient. TOML ist als menschenlesbares und -editierbares Konfigurationsformat gedacht, daher ist es wichtig, Kommentare, Formatierungen und andere Markierungen zu erhalten. Dies erfordert einen Parser, dessen Ausgabe stilbezogene Metadaten enthält, was es unpraktisch macht, reine Python-Typen wie str und dict auszugeben. Darüber hinaus verkompliziert dies das Design der API erheblich.

Selbst ohne Berücksichtigung der Stilwahrung gibt es zu viele Freiheitsgrade bei der Gestaltung einer Schreib-API. Zum Beispiel, welcher Standardstil (Einrückung, vertikale und horizontale Abstände, Anführungszeichen usw.) sollte die Bibliothek für die Ausgabe verwenden, und wie viel Kontrolle sollten Benutzer darüber haben? Wie soll die Bibliothek die Eingabe- und Ausgabevalidierung handhaben? Soll sie die Serialisierung benutzerdefinierter Typen unterstützen und wenn ja, wie? Obwohl es vernünftige Optionen zur Lösung dieser Probleme gibt, sind wir aufgrund der Natur der Standardbibliothek nur "einmal auf die richtige Art und Weise" die Chance.

Derzeit hat sich kein CPython-Core-Entwickler bereit erklärt, eine Schreib-API zu warten oder ein PEP zu sponsern, das eine solche enthält. Da es schwierig ist, etwas in der Standardbibliothek zu ändern oder zu entfernen, ist es sicherer, vorerst auf der Seite des Ausschlusses zu irren und dies möglicherweise später erneut zu prüfen.

Daher bleibt das Schreiben von TOML Drittanbieterbibliotheken überlassen. Wenn später eine gute API und relevante Anwendungsfälle dafür gefunden werden, kann die Schreibunterstützung in einem zukünftigen PEP hinzugefügt werden.

Verschiedene API-Details

Kontrolle des Typs von Abbildungen, die von tomllib.load[s] zurückgegeben werden

Die toml-Bibliothek auf PyPI akzeptiert ein _dict-Argument in ihren load[s]-Funktionen, das ähnlich wie das object_hook-Argument in json.load[s] funktioniert. Es gibt mehrere Verwendungen von _dict, die auf https://grep.app gefunden wurden; fast alle davon übergeben jedoch _dict=OrderedDict, was ab Python 3.7 unnötig sein sollte. Wir fanden zwei Instanzen relevanter Verwendung: In einem Fall wurde eine benutzerdefinierte Klasse für freundlichere KeyErrors übergeben; im anderen hatte die benutzerdefinierte Klasse mehrere zusätzliche Lookup- und Mutationsmethoden (z.B. zur Auflösung von Punktnotation-Schlüsseln).

Ein solcher Parameter ist für die Kern-Anwendungsfälle, die im Abschnitt Motivation skizziert sind, nicht notwendig. Das Fehlen davon kann leicht durch eine Wrapper-Klasse, eine Transformationsfunktion oder eine Drittanbieterbibliothek umgangen werden. Schließlich könnte die Unterstützung später rückwärtskompatibel hinzugefügt werden.

Entfernung der Unterstützung für parse_float in tomllib.load[s]

Diese Option ist nicht unbedingt notwendig, da TOML-Floats als "IEEE 754 binäre 64-Werte" implementiert werden sollten, was auf den meisten Architekturen einem Python float entspricht.

Die TOML-Spezifikation verwendet das Wort "SOLLTE", was jedoch eine Empfehlung impliziert, die aus gültigen Gründen ignoriert werden kann. Das Parsen von Floats anders, z.B. zu decimal.Decimal, ermöglicht Benutzern zusätzliche Präzision über die vom TOML-Format zugesicherte hinaus. Nach Erfahrung des Autors von tomli ist dies besonders nützlich in wissenschaftlichen und finanziellen Anwendungen. Dies ist auch nützlich für andere Fälle, die größere Präzision benötigen oder bei denen Endbenutzer Nicht-Entwickler sind, die sich der Grenzen von binären 64-Bit-Floats möglicherweise nicht bewusst sind.

Es gibt auch Nischenarchitekturen, bei denen der Python float kein IEEE 754 binärer 64-Wert ist. Das Argument parse_float ermöglicht es Benutzern, auch auf solchen Architekturen korrekte TOML-Semantiken zu erzielen.

Alternative Namen für das Modul

Idealerweise könnten wir den Modulnamen toml verwenden.

Das toml-Paket auf PyPI ist jedoch weit verbreitet, daher gibt es Rückwärtskompatibilitätsprobleme. Da die Standardbibliothek Vorrang vor Drittanbieterpaketen hat, würden Bibliotheken und Anwendungen, die derzeit vom toml-Paket abhängen, wahrscheinlich beim Upgrade von Python-Versionen fehlschlagen, da die vielen API-Inkompatibilitäten, die in Anhang A aufgeführt sind, auch wenn sie ihre Abhängigkeitsversionen fixieren.

Um dies weiter zu verdeutlichen, sind Anwendungen mit fixierten Abhängigkeiten hier von größter Bedeutung. Selbst wenn wir die Kontrolle über den PyPI-Paketnamen toml erhalten und ihn für ein Backport des vorgeschlagenen neuen Moduls wiederverwenden könnten, würden wir immer noch Benutzer auf neuen Python-Versionen beeinträchtigen, die ihn in der Standardbibliothek enthielten, unabhängig davon, ob sie eine ältere Version des bestehenden toml-Pakets fixiert haben. Dies ist bedauerlich, da das Fixieren wahrscheinlich eine gängige Reaktion auf unterbrechende Änderungen sein würde, die durch die Wiederverwendung des toml-Pakets als Backport (das mit dem heutigen toml inkompatibel ist) eingeführt werden.

Schließlich ist das toml-Paket auf PyPI nicht aktiv gewartet, aber bisher waren Bemühungen, den Autor aufzufordern, andere Maintainer hinzuzufügen nicht erfolgreich, daher müsste hier wahrscheinlich ohne Zustimmung des Autors gehandelt werden.

Stattdessen schlägt dieses PEP den Namen tomllib vor. Dies spiegelt plistlib und xdrlib wider, zwei weitere Dateiformatmodule in der Standardbibliothek, sowie andere Module wie pathlib, contextlib und graphlib.

Andere in Betracht gezogene, aber abgelehnte Namen sind

• tomlparser. Dies spiegelt configparser wider, ist aber möglicherweise weniger geeignet, wenn wir in Zukunft eine Schreib-API aufnehmen.
• tomli. Dies setzt voraus, dass wir tomli als Grundlage für die Implementierung verwenden.
• toml unter einem Namespace, wie z.B. parser.toml. Dies ist jedoch umständlich, zumal bestehende Parsing-Bibliotheken wie json, pickle, xml, html usw. nicht im Namespace enthalten wären.