Following system colour scheme Selected dark colour scheme Selected light colour scheme

Python Enhancement Proposals

PEP 345 – Metadaten für Python-Softwarepakete 1.2

Autor:
Richard Jones <richard at python.org>
Discussions-To:
Distutils-SIG Liste
Status:
Abgelöst
Typ:
Standards Track
Thema:
Packaging
Erstellt:
28. April 2005
Python-Version:
2.7
Post-History:
22. Dezember 2009
Ersetzt:
314
Ersetzt-Durch:
566
Resolution:
Python-Dev thread
Inhaltsverzeichnis

Wichtig

Dieses PEP ist ein historisches Dokument. Die aktuelle, kanonische Spezifikation, Kernmetadatenspezifikationen, wird auf der PyPA Specs-Seite gepflegt.

×

Siehe den PyPA-Spezifikations-Update-Prozess, um Änderungen vorzuschlagen.

Zusammenfassung

Dieser PEP beschreibt einen Mechanismus zum Hinzufügen von Metadaten zu Python-Distributionen. Er enthält Einzelheiten zu den Feldnamen sowie deren Semantik und Verwendung.

Dieses Dokument spezifiziert Version 1.2 des Metadatenformats. Version 1.0 ist in PEP 241 spezifiziert. Version 1.1 ist in PEP 314 spezifiziert.

Version 1.2 des Metadatenformats fügt eine Reihe optionaler Felder hinzu, die darauf ausgelegt sind, die Erstellung von Drittanbieterpaketen für Python-Software zu erleichtern. Diese Felder sind „Requires-Python“, „Requires-External“, „Requires-Dist“, „Provides-Dist“ und „Obsoletes-Dist“. Diese Version ändert auch das Feld „Platform“. Außerdem wurden drei neue Felder hinzugefügt: „Maintainer“, „Maintainer-email“ und „Project-URL“.

Schließlich fügt diese neue Version auch Umgebungsmarker hinzu.

Felder

Dieser Abschnitt spezifiziert die Namen und die Semantik jedes unterstützten Metadatenfeldes.

Felder, die mit „(Mehrfachverwendung)“ gekennzeichnet sind, können in einer einzelnen PKG-INFO-Datei mehrmals angegeben werden. Andere Felder dürfen nur einmal in einer PKG-INFO-Datei vorkommen. Felder, die mit „(optional)“ gekennzeichnet sind, müssen nicht in einer gültigen PKG-INFO-Datei enthalten sein; alle anderen Felder müssen vorhanden sein.

Metadata-Version

Version des Dateiformats; „1.2“ ist der einzig zulässige Wert.

Beispiel

Metadata-Version: 1.2

Name

Der Name der Distributionen.

Beispiel

Name: BeagleVote

Version

Ein String, der die Versionsnummer der Distribution enthält. Dieses Feld muss im in PEP 440 spezifizierten Format vorliegen.

Beispiel

Version: 1.0a2

Platform (mehrfache Verwendung)

Eine Plattformspezifikation, die ein Betriebssystem beschreibt, das von der Distribution unterstützt wird und das nicht in den Trove-Klassifikatoren für „Operating System“ aufgeführt ist. Siehe „Classifier“ unten.

Beispiele

Platform: ObscureUnix
Platform: RareDOS

Supported-Platform (mehrfache Verwendung)

Binäre Distributionen, die eine PKG-INFO-Datei enthalten, verwenden das Feld Supported-Platform in ihren Metadaten, um das Betriebssystem und die CPU anzugeben, für die die Binärdistribution kompiliert wurde. Die Semantik des Feldes Supported-Platform ist in diesem PEP nicht spezifiziert.

Beispiel

Supported-Platform: RedHat 7.2
Supported-Platform: i386-win32-2791

Zusammenfassung

Eine einzeilige Zusammenfassung dessen, was die Distribution tut.

Beispiel

Summary: A module for collecting votes from beagles.

Description (optional)

Eine längere Beschreibung der Distribution, die mehrere Absätze umfassen kann. Software, die mit Metadaten arbeitet, sollte keine maximale Größe für dieses Feld annehmen, obwohl man sein Handbuch nicht als Beschreibung einfügen sollte.

Der Inhalt dieses Feldes kann unter Verwendung von reStructuredText-Markup [1] geschrieben werden. Für Programme, die mit den Metadaten arbeiten, ist die Unterstützung von Markup optional; Programme können den Inhalt des Feldes auch unverändert anzeigen. Das bedeutet, dass Autoren bei der Verwendung von Markup vorsichtig sein sollten.

Um leere Zeilen und Zeilen mit Einrückung im Hinblick auf das RFC 822-Format zu unterstützen, muss jedes CRLF-Zeichen mit 7 Leerzeichen gefolgt von einem Pipe („|“) Zeichen ergänzt werden. Infolgedessen wird das Description-Feld in ein gefaltetes Feld kodiert, das von einem RFC 822#section-3.1.1-Parser interpretiert werden kann.

Beispiel

Description: This project provides powerful math functions
        |For example, you can use ``sum()`` to sum numbers:
        |
        |Example::
        |
        |    >>> sum(1, 2)
        |    3
        |

Diese Kodierung impliziert, dass alle Vorkommen eines CRLF gefolgt von 7 Leerzeichen und einem Pipe-Zeichen durch ein einzelnes CRLF ersetzt werden müssen, wenn das Feld mit einem RFC 822-Leser entfaltet wird.

Keywords (optional)

Eine Liste zusätzlicher Schlüsselwörter, die zur Unterstützung der Suche nach der Distribution in einem größeren Katalog verwendet werden.

Beispiel

Keywords: dog puppy voting election

Home-page (optional)

Ein String, der die URL der Homepage der Distribution enthält.

Beispiel

Home-page: http://www.example.com/~cschultz/bvote/

Download-URL

Ein String, der die URL enthält, von der diese Version der Distribution heruntergeladen werden kann. (Das bedeutet, dass die URL nicht etwas wie „…/BeagleVote-latest.tgz“ sein kann, sondern stattdessen „…/BeagleVote-0.45.tgz“ sein muss.)

Author (optional)

Ein String, der mindestens den Namen des Autors enthält; zusätzliche Kontaktinformationen können angegeben werden.

Beispiel

Author: C. Schultz, Universal Features Syndicate,
        Los Angeles, CA <cschultz@peanuts.example.com>

Author-email (optional)

Ein String, der die E-Mail-Adresse des Autors enthält. Er kann einen Namen und eine E-Mail-Adresse in den gültigen Formen für eine RFC 822 From:-Kopfzeile enthalten.

Beispiel

Author-email: "C. Schultz" <cschultz@example.com>

Maintainer (optional)

Ein String, der mindestens den Namen des Betreuers enthält; zusätzliche Kontaktinformationen können angegeben werden.

Beachten Sie, dass dieses Feld für die Verwendung bestimmt ist, wenn ein Projekt von jemand anderem als dem ursprünglichen Autor betreut wird: Es sollte weggelassen werden, wenn es mit Author identisch ist.

Beispiel

Maintainer: C. Schultz, Universal Features Syndicate,
        Los Angeles, CA <cschultz@peanuts.example.com>

Maintainer-email (optional)

Ein String, der die E-Mail-Adresse des Betreuers enthält. Er kann einen Namen und eine E-Mail-Adresse in den gültigen Formen für eine RFC 822 From:-Kopfzeile enthalten.

Beachten Sie, dass dieses Feld für die Verwendung bestimmt ist, wenn ein Projekt von jemand anderem als dem ursprünglichen Autor betreut wird: Es sollte weggelassen werden, wenn es mit Author-email identisch ist.

Beispiel

Maintainer-email: "C. Schultz" <cschultz@example.com>

License (optional)

Text, der die Lizenz angibt, die die Distribution abdeckt, wenn die Lizenz keine Auswahl aus den „License“-Trove-Klassifikatoren ist. Siehe „Classifier“ unten. Dieses Feld kann auch verwendet werden, um eine bestimmte Version einer Lizenz anzugeben, die über das Feld Classifier benannt wird, oder um eine Variante oder Ausnahme von einer solchen Lizenz anzugeben.

Beispiele

License: This software may only be obtained by sending the
        author a postcard, and then the user promises not
        to redistribute it.

License: GPL version 3, excluding DRM provisions

Classifier (mehrfache Verwendung)

Jeder Eintrag ist ein String, der einen einzelnen Klassifizierungswert für die Distribution angibt. Klassifikatoren werden in PEP 301 beschrieben.

Beispiele

Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console (Text Based)

Requires-Dist (mehrfache Verwendung)

Jeder Eintrag enthält einen String, der einen anderen Distutils-Projekt benennt, das von dieser Distribution benötigt wird.

Das Format eines Anforderungsstrings ist identisch mit dem eines Distutils-Projektnamens (z. B. wie im Feld Name: zu finden), optional gefolgt von einer Versionsdeklaration in Klammern.

Die Distutils-Projektnamen sollten den Namen entsprechen, wie sie auf dem Python Package Index zu finden sind.

Versionsdeklarationen müssen den Regeln folgen, die in Versionsspezifizierer beschrieben sind.

Beispiele

Requires-Dist: pkginfo
Requires-Dist: PasteDeploy
Requires-Dist: zope.interface (>3.5.0)

Provides-Dist (mehrfache Verwendung)

Jeder Eintrag enthält einen String, der ein Distutils-Projekt benennt, das in dieser Distribution enthalten ist. Dieses Feld *muss* das im Feld Name identifizierte Projekt gefolgt von der Version enthalten: Name (Version).

Eine Distribution kann zusätzliche Namen bereitstellen, z. B. um anzuzeigen, dass mehrere Projekte zusammengebündelt wurden. Zum Beispiel enthielten Distributionen im Quellformat des Projekts ZODB historisch das Projekt transaction, das jetzt als separate Distribution verfügbar ist. Die Installation einer solchen Quellformat-Distribution erfüllt die Anforderungen sowohl für ZODB als auch für transaction.

Eine Distribution kann auch einen „virtuellen“ Projektnamen bereitstellen, der keinem separat verteilten Projekt entspricht: Ein solcher Name könnte verwendet werden, um eine abstrakte Fähigkeit anzuzeigen, die von einem von mehreren Projekten bereitgestellt werden könnte. Z. B. könnten mehrere Projekte RDBMS-Bindings für die Verwendung durch ein gegebenes ORM bereitstellen: Jedes Projekt könnte deklarieren, dass es ORM-bindings bereitstellt, wodurch andere Projekte nur davon abhängen können, dass höchstens eines davon installiert ist.

Eine Versionsdeklaration kann angegeben werden und muss den Regeln folgen, die in Versionsspezifizierer beschrieben sind. Die Versionsnummer der Distribution wird angenommen, wenn keine angegeben ist.

Beispiele

Provides-Dist: OtherProject
Provides-Dist: AnotherProject (3.4)
Provides-Dist: virtual_package

Obsoletes-Dist (mehrfache Verwendung)

Jeder Eintrag enthält einen String, der eine Distribution eines Distutils-Projekts beschreibt, das diese Distribution veraltet macht, d. h. die beiden Projekte sollten nicht gleichzeitig installiert werden.

Versionsdeklarationen können angegeben werden. Versionsnummern müssen im Format vorliegen, das in Versionsspezifizierer beschrieben ist.

Der häufigste Anwendungsfall für dieses Feld ist, wenn sich ein Projektname ändert, z. B. Gorgon 2.3 wird in Torqued Python 1.0 integriert. Wenn Sie Torqued Python installieren, sollte die Gorgon-Distribution entfernt werden.

Beispiele

Obsoletes-Dist: Gorgon
Obsoletes-Dist: OtherProject (<3.0)

Requires-Python

Dieses Feld gibt die Python-Version(en) an, mit denen die Distribution garantiert kompatibel ist.

Versionsnummern müssen im Format vorliegen, das in Versionsspezifizierer beschrieben ist.

Beispiele

Requires-Python: 2.5
Requires-Python: >2.1
Requires-Python: >=2.3.4
Requires-Python: >=2.5,<2.7

Requires-External (mehrfache Verwendung)

Jeder Eintrag enthält einen String, der eine Abhängigkeit im System beschreibt, mit der die Distribution verwendet werden soll. Dieses Feld soll nachgelagerten Projektbetreuern als Hinweis dienen und hat keine für die distutils-Distribution bedeutsame Semantik.

Das Format eines Anforderungsstrings ist der Name einer externen Abhängigkeit, optional gefolgt von einer Versionsdeklaration in Klammern.

Da sie sich auf Nicht-Python-Software-Releases beziehen, müssen Versionsnummern für dieses Feld **nicht** dem in PEP 440 spezifizierten Format entsprechen: Sie sollten dem vom externen Abhängigkeit verwendeten Schemaschema entsprechen.

Beachten Sie, dass es keine spezifische Regel für die zu verwendenden Strings gibt.

Beispiele

Requires-External: C
Requires-External: libpng (>=1.5)

Project-URL (mehrfache Verwendung)

Ein String, der eine zusätzliche URL für das Projekt und eine Bezeichnung dafür enthält, getrennt durch ein Komma. Dies sollte verwendet werden, wenn zusätzliche URLs zusätzlich zum Feld „Home-page“ in den Metadaten aufgeführt werden sollen.

Beispiele

Project-URL: Bug Tracker, https://github.com/pypa/setuptools/issues
Project-URL: Documentation, https://setuptools.readthedocs.io/
Project-URL: Funding, https://donate.pypi.org

Die Bezeichnung ist freier Text mit einer maximalen Länge von 32 Zeichen. Beachten Sie, dass Distributionen, die auf PyPI hochgeladen werden, diese zusätzlichen Einträge im Abschnitt „Project links“ ihrer Landingpage angezeigt bekommen.

Versionsspezifizierer

Versionsspezifizierer sind eine Reihe von bedingten Operatoren und Versionsnummern, getrennt durch Kommas. Bedingte Operatoren müssen einer der folgenden sein: „<“, „>“, „<=“, „>=“, „==“ und „!=“.

Beliebig viele bedingte Operatoren können angegeben werden, z. B. ist der String „>1.0, !=1.3.4, <2.0“ eine legale Versionsdeklaration. Das Komma („,“) ist äquivalent zum **und**-Operator.

Jede Versionsnummer muss im Format vorliegen, das in PEP 440 spezifiziert ist.

Wenn eine Version angegeben wird, umfasst sie immer alle Versionen, die mit demselben Wert beginnen. Beispielsweise umfasst die Version „2.5“ von Python Versionen wie „2.5.2“ oder „2.5.3“. Vor- und Nachveröffentlichungen sind in diesem Fall ausgeschlossen. So sind in unserem Beispiel Versionen wie „2.5a1“ nicht enthalten, wenn „2.5“ verwendet wird. Wenn die erste Version des Bereichs erforderlich ist, muss sie explizit angegeben werden. In unserem Beispiel wäre dies „2.5.0“.

Beachten Sie, dass einige Projekte das Suffix „.0“ für die erste Veröffentlichung der Serie „2.5.x“ weglassen könnten.

  • 2.5
  • 2.5.1
  • 2.5.2
  • usw.

In diesem Fall muss „2.5.0“ explizit verwendet werden, um Verwechslungen zwischen der Notation „2.5“, die den gesamten Bereich darstellt, zu vermeiden. Es ist eine empfohlene Vorgehensweise, Schemas gleicher Länge für eine Serie zu verwenden, um dieses Problem vollständig zu vermeiden.

Einige Beispiele

  • Requires-Dist: zope.interface (3.1): jede Version, die mit 3.1 beginnt, einschließlich Vor- oder Nachveröffentlichungen.
  • Requires-Dist: zope.interface (3.1.0): jede Version, die mit 3.1.0 beginnt, einschließlich Vor- oder Nachveröffentlichungen. Da dieses spezielle Projekt nicht mehr als 3 Ziffern verwendet, bedeutet dies auch „nur die Veröffentlichung 3.1.0“.
  • Requires-Python: 3: Jede Python 3-Version, egal welche, einschließlich Vor- oder Nachveröffentlichungen.
  • Requires-Python: >=2.6,<3: Jede Version von Python 2.6 oder 2.7, einschließlich Nachveröffentlichungen von 2.6, Vor- und Nachveröffentlichungen von 2.7. Sie schließt Vorveröffentlichungen von Python 3 aus.
  • Requires-Python: 2.6.2: Äquivalent zu „>=2.6.2,<2.6.3“. Dies schließt also nur Python 2.6.2 ein. Wenn Python mit 4 Ziffern nummeriert wäre, würde es alle Versionen der 2.6.2-Serie umfassen.
  • Requires-Python: 2.5.0: Äquivalent zu „>=2.5.0,<2.5.1“.
  • Requires-Dist: zope.interface (3.1,!=3.1.3): Jede Version, die mit 3.1 beginnt, ausschließlich Vor- oder Nachveröffentlichungen von 3.1 *und* ausschließlich jede Version, die mit „3.1.3“ beginnt. Für dieses spezielle Projekt bedeutet dies: „Jede Version der 3.1-Serie, aber nicht 3.1.3“. Dies ist äquivalent zu: „>=3.1,!=3.1.3,<3.2“.

Umgebungsmarkierer

Ein **Umgebungsmarker** ist ein Marker, der am Ende eines Feldes nach einem Semikolon („;“) hinzugefügt werden kann, um eine Bedingung für die Ausführungsumgebung hinzuzufügen.

Hier sind einige Beispiele für Felder, die solche Marker verwenden

Requires-Dist: pywin32 (>1.0); sys.platform == 'win32'
Obsoletes-Dist: pywin31; sys.platform == 'win32'
Requires-Dist: foo (1,!=1.3); platform.machine == 'i386'
Requires-Dist: bar; python_version == '2.4' or python_version == '2.5'
Requires-External: libxslt; 'linux' in sys.platform

Die Mikrosprache dahinter ist die einfachste mögliche: Sie vergleicht nur Strings, mit den Operatoren == und in (und deren Gegenteile) und mit der Möglichkeit, Ausdrücke zu kombinieren. Sie ist auch für Nicht-Pythoneer 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])
  • python_full_version = sys.version.split()[0]
  • os.name = os.name
  • sys.platform = sys.platform
  • platform.version = platform.version()
  • platform.machine = platform.machine()
  • platform.python_implementation = platform.python_implementation()
  • ein freier String, wie '2.4' oder 'win32'

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

Die Felder, die von diesem Marker profitieren, sind:

  • Requires-External
  • Requires-Dist
  • Provides-Dist
  • Obsoletes-Dist
  • Classifier

Zusammenfassung der Unterschiede zu PEP 314

  • Metadata-Version ist jetzt 1.2.
  • Umgebungsmarker hinzugefügt.
  • Geänderte Felder
    • Platform (Syntaxänderung)
    • Author-email (Änderung zu optionalem Feld)
  • Hinzugefügte Felder
    • Maintainer
    • Maintainer-email
    • Requires-Python
    • Requires-External
    • Requires-Dist
    • Provides-Dist
    • Obsoletes-Dist
    • Project-URL
  • Veraltete Felder
    • Requires (zugunsten von Requires-Dist)
    • Provides (zugunsten von Provides-Dist)
    • Obsoletes (zugunsten von Obsoletes-Dist)

Referenzen

Dieses Dokument spezifiziert Version 1.2 des Metadatenformats. Version 1.0 ist in PEP 241 spezifiziert. Version 1.1 ist in PEP 314 spezifiziert.

Danksagungen

Fred Drake, Anthony Baxter und Matthias Klose haben alle zu den Ideen beigetragen, die in diesem PEP präsentiert werden.

Tres Seaver, Jim Fulton, Marc-André Lemburg, Martin von Löwis, Tarek Ziadé, David Lyon und andere Personen bei der Distutils-SIG haben zu der neuen aktualisierten Version beigetragen.

Quelle: https://github.com/python/peps/blob/main/peps/pep-0345.rst

Zuletzt geändert: 2025-02-01 08:55:40 GMT