Zusammenfassung

Dieses PEP beschreibt einen neuen Abschnitt und ein neues Format für die Datei setup.cfg, die es ermöglicht, die Metadaten eines Pakets zu beschreiben, ohne setup.py zu verwenden.

Ablehnungsbescheid

Da distutils2 nicht mehr in die Standardbibliothek aufgenommen wird, wurde dieses PEP im späten April 2013 von Alyssa Coghlan abgelehnt.

Ein Ersatz-PEP, das auf PEP 426 (Metadaten 2.0) basiert, wird erstellt, das die minimale Informationsmenge definiert, die zur Generierung eines sdist-Archivs aus einem Quell-Tarball oder VCS-Checkout benötigt wird.

Begründung

Heute muss man die Kommandozeilenschnittstelle von setup.py verwenden, um alle Metadaten einer Distribution aufzulisten (siehe PEP 314), die nicht installiert ist.

Man lädt sie also im Grunde herunter und führt aus

$ python setup.py --name
Distribute

$ python setup.py --version
0.6.4

Wobei name und version Metadatenfelder sind. Das funktioniert gut, aber sobald die Entwickler mehr Code in setup.py hinzufügen, kann diese Funktion fehlschlagen oder im schlimmsten Fall unerwünschte Dinge auf dem Zielsystem tun.

Darüber hinaus kann es bei einem OS-Paketer, der die Metadaten einer Distribution, die er neu verpackt, erhalten möchte, zu Problemen beim Verständnis der setup.py-Datei kommen, mit der er arbeitet.

Der Grundgedanke dieses PEP ist es daher, eine Möglichkeit zu bieten, die Metadaten in einer statischen Konfigurationsdatei neben setup.py zu deklarieren, die keine Ausführung von Drittanbietercode erfordert.

Hinzufügen eines metadata-Abschnitts in setup.cfg

Das erste, was wir einführen wollen, ist ein Abschnitt [metadata] in der Datei setup.cfg, der jedes Feld aus den Metadaten enthalten kann.

[metadata]
name = Distribute
version = 0.6.4

Die Datei setup.cfg wird verwendet, um die Einführung einer weiteren Konfigurationsdatei für Distutils zu vermeiden.

Diese Datei wird bereits von Distutils gelesen, wenn ein Befehl ausgeführt wird, und wenn der Abschnitt metadata gefunden wird, wird er verwendet, um die Metadatenfelder zu füllen. Wenn eine Option, die einem Metadatenfeld entspricht, an setup() übergeben wird, überschreibt sie den Wert, der möglicherweise in setup.cfg vorhanden war.

Beachten Sie, dass setup.py weiterhin verwendet wird und erforderlich sein kann, um einige Optionen zu definieren, die nicht zu den Metadatenfeldern gehören. Beispielsweise kann der Befehl sdist Optionen wie packages oder scripts verwenden.

Mehrzeilige Werte

Einige Metadatenfelder können mehrere Werte haben. Um setup.cfg mit ConfigParser und den RFC 822 LONG HEADER FIELDS (siehe Abschnitt 3.1.1) kompatibel zu halten, werden diese mit durch , getrennten Werten ausgedrückt.

requires = pywin32, bar > 1.0, foo

Wenn diese Variable gelesen wird, werden die Werte analysiert und in eine Liste umgewandelt: ['pywin32', 'bar > 1.0', 'foo'].

Kontextabhängige Abschnitte

Der Abschnitt metadata wird auch kontextabhängige Abschnitte verwenden können.

Ein kontextabhängiger Abschnitt ist ein Abschnitt mit einer Bedingung für die Ausführungsumgebung. Hier sind einige Beispiele.

[metadata]
name = Distribute
version = 0.6.4

[metadata:sys_platform == 'win32']
requires = pywin32, bar > 1.0
obsoletes = pywin31

[metadata:os_machine == 'i386']
requires = foo

[metadata:python_version == '2.4' or python_version == '2.5']
requires = bar

[metadata:'linux' in sys_platform]
requires = baz

Jeder Abschnitt [metadata:condition] wird nur verwendet, wenn die Bedingung beim Lesen der Datei erfüllt ist. Die zugrundeliegende Motivation für diese kontextabhängigen Abschnitte ist die Möglichkeit, Anforderungen zu definieren, die sich je nach Plattform, auf der die Distribution installiert werden könnte, unterscheiden. (siehe PEP 314).

Die Mikrosprache dahinter ist die einfachste denkbare: Sie vergleicht nur Zeichenketten mit den Operatoren == und in (und ihren Gegenteilen) und kann Ausdrücke kombinieren. Das macht sie auch für Nicht-Python-Entwickler leicht verständlich.

Die Pseudo-Grammatik ist:

EXPR [in|==|!=|not in] EXPR [or|and] ...

wobei EXPR zu einem der folgenden gehört

• python_version = ‘%s.%s’ % (sys.version_info[0], sys.version_info[1])
• os_name = os.name
• sys_platform = sys.platform
• platform_version = platform.version()
• platform_machine = platform.machine()
• eine freie Zeichenkette, wie 2.4 oder win32

Beachten Sie, dass in auf Zeichenketten beschränkt ist, d.h. es ist nicht möglich, andere Sequenzen wie Tupel oder Listen auf der rechten Seite zu verwenden.

Distutils stellt eine Funktion bereit, die die Metadaten einer Distribution anhand einer setup.cfg-Datei für die Ausführungsumgebung generieren kann.

>>> from distutils.util import local_metadata
>>> local_metadata('setup.cfg')
<DistributionMetadata instance>

Das bedeutet, dass ein reines Python die Metadaten eines Pakets lesen kann, ohne Code von Drittanbietern auszuführen.

Beachten Sie, dass diese Funktion nicht auf den Namensraum metadata beschränkt ist. Folglich kann jeder andere Abschnitt mit solchen kontextabhängigen Abschnitten erweitert werden.

Auswirkungen auf die PKG-INFO-Generierung und PEP 314

Wenn PKG-INFO von Distutils generiert wird, wird für jedes Feld, das auf einer Bedingung basiert, diese Bedingung am Ende der Zeile nach einem ;-Trennzeichen geschrieben.

Metadata-Version: 1.2
Name: distribute
Version: 0.6.4
...
Requires: pywin32, bar > 1.0; sys_platform == 'win32'
Requires: foo; os_machine == 'i386'
Requires: bar; python_version == '2.4' or python_version == '2.5'
Requires: baz; 'linux' in sys_platform
Obsoletes = pywin31; sys_platform == 'win32'
...
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Python Software Foundation License

Beachten Sie, dass diese Datei mit der Klasse DistributionMetadata geöffnet werden kann. Diese Klasse kann die Mikrosprache mithilfe der Ausführungsumgebung verwenden.

Lassen Sie uns dies auf einem Python 2.5 i386 Linux ausführen.

>>> from distutils.dist import DistributionMetadata
>>> metadata = DistributionMetadata('PKG_INFO')
>>> metadata.get_requires()
['foo', 'bar', 'baz']

Die Ausführungsumgebung kann überschrieben werden, falls wir die Metadaten für eine andere Umgebung erhalten möchten.

>>> env = {'python_version': '2.4',
...        'os_name': 'nt',
...        'sys_platform': 'win32',
...        'platform_version': 'MVCC++ 6.0'
...        'platform_machine': 'i386'}
...
>>> metadata = DistributionMetadata('PKG_INFO', environment=env)
>>> metadata.get_requires()
['bar > 1.0', 'foo', 'bar']

PEP 314 wird entsprechend geändert, was bedeutet, dass jedes Feld diesen zusätzlichen Bedingungskennzeichner haben kann.

Kompatibilität

Diese Änderung basiert auf einem neuen Metadatenformat 1.2, was bedeutet, dass Distutils alte PKG-INFO-Dateien von neuen unterscheiden kann.

Die Änderung der setup.cfg-Datei bleibt ConfigParser-kompatibel und bricht bestehende setup.cfg-Dateien nicht.

Einschränkungen

Wir bieten derzeit keine Operatoren < und > an, und python_version ist eine reguläre Zeichenkette. Dies bedeutet die Verwendung von or-Operatoren, wenn ein Abschnitt auf einige Python-Versionen beschränkt werden soll. Wenn jedoch PEP 386 angenommen wird, könnte python_version intern in etwas umgewandelt werden, das mit Zeichenketten vergleichbar ist, und Operatoren wie < und > könnten eingeführt werden.

Schließlich, wenn eine Distribution nicht in der Lage ist, alle Metadatenfelder in setup.cfg festzulegen, ist das in Ordnung. Die Felder werden auf UNKNOWN gesetzt, wenn local_metadata aufgerufen wird. Das Erhalten von UNKNOWN-Werten bedeutet, dass es notwendig sein kann, die Kommandozeilenschnittstelle setup.py auszuführen, um den gesamten Satz von Metadaten zu erhalten.

Danksagungen

Das Distutils-SIG.

Urheberrecht

Dieses Dokument wurde gemeinfrei erklärt.