Dateiformat

Die Build-System-Abhängigkeiten werden in einer Datei namens pyproject.toml gespeichert, die im TOML-Format [6] geschrieben ist.

Dieses Format wurde gewählt, da es für Menschen nutzbar ist (im Gegensatz zu JSON [7]), es flexibel genug ist (im Gegensatz zu configparser [9]), auf einem Standard basiert (auch im Gegensatz zu configparser [9]) und nicht übermäßig komplex ist (im Gegensatz zu YAML [8]). Das TOML-Format wird bereits von der Rust-Community als Teil ihres Cargo-Paketmanagers verwendet [14] und sie äußerten in privaten E-Mails, dass sie mit ihrer Wahl von TOML recht zufrieden waren. Eine ausführlichere Diskussion darüber, warum verschiedene Alternativen nicht gewählt wurden, finden Sie im Abschnitt Andere Dateiformate. Die Autoren erkennen jedoch an, dass die Wahl des Konfigurationsdateiformats letztlich subjektiv ist und eine Entscheidung getroffen werden musste, und die Autoren bevorzugen TOML für diese Situation.

Im Folgenden listen wir die Tabellen auf, die Werkzeuge erkennen/respektieren sollen. Tabellen, die in diesem PEP nicht spezifiziert sind, sind für die zukünftige Verwendung durch andere PEPs reserviert.

Tabelle build-system

Die Tabelle [build-system] wird zur Speicherung von Build-bezogenen Daten verwendet. Anfänglich ist nur ein Schlüssel dieser Tabelle gültig und für die Tabelle zwingend erforderlich: requires. Dieser Schlüssel muss einen Wert haben, der eine Liste von Zeichenketten ist, die PEP 508-Abhängigkeiten repräsentieren, die zur Ausführung des Build-Systems erforderlich sind (derzeit bedeutet das, welche Abhängigkeiten zur Ausführung einer setup.py-Datei erforderlich sind).

Für die überwiegende Mehrheit der Python-Projekte, die auf setuptools angewiesen sind, wird die Datei pyproject.toml wie folgt aussehen:

[build-system]
# Minimum requirements for the build system to execute.
requires = ["setuptools"]  # PEP 508 specifications.

Da die Verwendung von setuptools in der Community derzeit so weit verbreitet ist, wird erwartet, dass Build-Werkzeuge die obige Beispielkonfigurationsdatei als Standardsemantik verwenden, wenn keine pyproject.toml-Datei vorhanden ist.

Werkzeuge sollten die Existenz der Tabelle [build-system] nicht erzwingen. Eine pyproject.toml-Datei kann verwendet werden, um andere Konfigurationsdetails als Build-bezogene Daten zu speichern, und daher legitim eine [build-system]-Tabelle fehlen lassen. Wenn die Datei existiert, aber die Tabelle [build-system] fehlt, sollten die oben spezifizierten Standardwerte verwendet werden. Wenn die Tabelle angegeben ist, aber erforderliche Felder fehlen, sollte das Werkzeug dies als Fehler betrachten.

Tabelle tool

Die Tabelle [tool] ist der Ort, an dem jedes Werkzeug, das mit Ihrem Python-Projekt zusammenhängt, nicht nur Build-Werkzeuge, vom Benutzer Konfigurationsdaten angeben lassen kann, solange es eine Untertabelle innerhalb von [tool] verwendet, z.B. das flit-Werkzeug würde seine Konfiguration in [tool.flit] speichern.

Wir benötigen einen Mechanismus zur Zuweisung von Namen im Namensraum tool.*, um sicherzustellen, dass verschiedene Projekte nicht versuchen, dieselbe Untertabelle zu verwenden und zu kollidieren. Unsere Regel ist, dass ein Projekt die Untertabelle tool.$NAME verwenden kann, wenn und nur wenn es den Eintrag für $NAME im Cheeseshop/PyPI besitzt.

JSON-Schema

Um eine typenspezifische Darstellung der aus der TOML-Datei resultierenden Daten zu Illustrationszwecken bereitzustellen, würde das folgende JSON-Schema [15] dem Datenformat entsprechen:

{
    "$schema": "http://json-schema.org/schema#",

    "type": "object",
    "additionalProperties": false,

    "properties": {
        "build-system": {
            "type": "object",
            "additionalProperties": false,

            "properties": {
                "requires": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            },
            "required": ["requires"]
        },

        "tool": {
            "type": "object"
        }
    }
}

Ein semantischer Versionsschlüssel

Zur Zukunftssicherheit der Struktur der Konfigurationsdatei wurde zunächst ein Schlüssel semantics-version vorgeschlagen. Standardmäßig auf 1 gesetzt, war die Idee, dass, wenn sich die Semantik von zuvor definierten Schlüsseln oder Tabellen rückwärtsinkompatibel ändert, die semantics-version auf eine neue Nummer erhöht würde.

Letztendlich wurde jedoch entschieden, dass dies eine voreilige Optimierung war. Die Erwartung ist, dass Änderungen an dem, was semantisch in der Konfigurationsdatei vordefiniert ist, eher konservativ sein werden. Und in Fällen, in denen eine rückwärtsinkompatible Änderung aufgetreten wäre, können neue Namen für die neuen Semantiken verwendet werden, um ältere Werkzeuge nicht zu brechen.

Ein verschachtelterer Namensraum

Ein früherer Entwurf dieses PEP hatte eine [package]-Tabelle auf oberster Ebene. Die Idee war, eine gewisse Abgrenzung für ein Semantik-Versionierungsschema zu erzwingen (siehe Ein semantischer Versionsschlüssel, warum diese Idee abgelehnt wurde). Mit dem Wegfall der Notwendigkeit einer Abgrenzung wurde der Sinn einer Tabelle auf oberster Ebene überflüssig.

Andere Tabellennamen

Ein anderer Name, der für die Tabelle [build-system] vorgeschlagen wurde, war [build]. Der alternative Name ist kürzer, vermittelt aber nicht die Absicht, welche Informationen in der Tabelle gespeichert sind. Nach einer Abstimmung in der Mailingliste distutils-sig setzte sich der aktuelle Name durch.

Andere Dateiformate

Mehrere andere Dateiformate wurden zur Prüfung vorgelegt, alle aus verschiedenen Gründen abgelehnt. Wichtige Anforderungen waren, dass das Format von Menschen bearbeitet werden kann und eine Implementierung hat, die von Projekten leicht mitgeliefert werden kann. Dies schloss Formate wie XML, die für Menschen nicht benutzerfreundlich sind, von vornherein aus und wurden nie ernsthaft diskutiert.

{
    "build": {
        "requires": [
            "setuptools",
            "wheel>=0.27"
        ]
    }
}

build:
    requires:
        - setuptools
        - wheel>=0.27

[build]
requires =
    setuptools
    wheel>=0.27

# The build configuration
{"build": {"requires": ["setuptools",
                        "wheel>=0.27", # note the trailing comma
                        # "numpy>=1.10" # a commented out data line
                        ]
# and here is an arbitrary comment.
           }
 }

Beibehaltung von setup.cfg

Es gibt zwei Probleme mit setup.cfg, das von setuptools als allgemeines Format verwendet wird. Erstens sind es .ini-Dateien, die Probleme haben, wie im Abschnitt configparser oben erwähnt. Das andere ist, dass das Schema für diese Datei nie streng definiert wurde und daher unbekannt ist, welches Format sicher für die Zukunft verwendet werden kann, ohne setuptools-Installationen möglicherweise zu verwirren.

Andere Dateinamen

Mehrere andere Dateinamen wurden in Betracht gezogen und abgelehnt (obwohl dies ein sehr starkes "Bikeshedding"-Thema ist und die Entscheidung hauptsächlich auf Geschmack beruht).

pysettings.toml

Die vernünftigste Alternative.

pypa.toml

Obwohl es sinnvoll ist, sich auf PyPA [11] zu beziehen, ist dies ein etwas nischiger Begriff. Es ist besser, wenn der Dateiname ohne domänenspezifisches Wissen Sinn ergibt.

pybuild.toml

Aus der restriktiven Perspektive dieses PEP ist dieser Dateiname sinnvoll, aber wenn jemals Nicht-Build-Metadaten zu der Datei hinzugefügt werden, hört der Name auf, sinnvoll zu sein.

pip.toml

Zu werkzeugspezifisch.

meta.toml

Zu generisch; ein Projekt möchte möglicherweise eine eigene Metadaten-Datei haben.

setup.toml

Obwohl es traditionell dank setup.py ist, passt es nicht unbedingt zu dem, was die Datei in Zukunft enthalten könnte (z.B. ist die Kenntnis des Namens eines Projekts zwangsläufig Teil seines Setups?).

pymeta.toml

Für Neulinge in der Programmierung und/oder Python nicht offensichtlich.

pypackage.toml & pypackaging.toml

Namensverwechslung dessen, was ein „Paket“ ist (Projekt versus Namensraum).

pydevelop.toml

Die Datei kann Details enthalten, die nicht speziell für die Entwicklung bestimmt sind.

pysource.toml

Nicht direkt mit Quellcode verwandt.

pytools.toml

Irreführend, da die Datei (derzeit) auf die Projektverwaltung ausgerichtet ist.

dstufft.toml

Zu personenspezifisch. ;)