Lizenz

Eine kurze Zeichenkette, die die für diese Distribution verwendete Lizenz zusammenfasst.

Beachten Sie, dass Distributionen, die dieses Feld bereitstellen, weiterhin alle zutreffenden Lizenz-Trove-Klassifizierer im Feld Klassifizierer angeben sollten. Auch wenn ein geeigneter Trove-Klassifizierer verfügbar ist, kann die Lizenzzusammenfassung eine gute Möglichkeit sein, eine bestimmte Version dieser Lizenz anzugeben oder Variationen oder Ausnahmen von der Lizenz zu kennzeichnen.

Dieses Feld SOLLTE weniger als 512 Zeichen und MUSS weniger als 2048 Zeichen enthalten.

Dieses Feld SOLLTE keine Zeilenumbrüche enthalten.

Der vollständige Lizenztext SOLLTE als separate Datei im Quellarchiv der Distribution enthalten sein. Details finden Sie unter Dokumentennamen.

Beispiel

"license": "GPL version 3, excluding DRM provisions"

Schlüsselwörter

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": ["comfy", "chair", "cushions", "too silly", "monty python"]

Klassifizierer

Eine Liste von Zeichenketten, wobei jede einen einzelnen Klassifizierungswert für die Distribution angibt. Klassifizierer werden in PEP 301 [2] beschrieben.

Beispiel

"classifiers": [
  "Development Status :: 4 - Beta",
  "Environment :: Console (Text Based)",
  "License :: OSI Approved :: GNU General Public License v3 (GPLv3)"
]

Dokumentennamen

Dateinamen für unterstützende Dokumente, die im Metadatenverzeichnis dist-info der Distribution enthalten sind.

Die folgenden unterstützenden Dokumente können benannt werden

• description: eine Datei, die eine lange Beschreibung der Distribution enthält
• license: eine Datei mit dem vollständigen Text der Lizenz der Distribution
• changelog: eine Datei, die Änderungen an der Distribution beschreibt

Unterstützende Dokumente MÜSSEN direkt im Verzeichnis dist-info enthalten sein. Verzeichnistrennzeichen sind in Dokumentennamen NICHT gestattet.

Das Markup-Format (falls vorhanden) der Datei wird durch die Dateierweiterung angegeben. Dies ermöglicht es Indexservern und anderen automatisierten Tools, enthaltene Textdokumente korrekt darzustellen und Feedback zu Rendering-Fehlern zu geben, anstatt das beabsichtigte Format erraten zu müssen.

Wenn die Dateierweiterung fehlt oder die Erweiterung nicht erkannt wird, MUSS das Standard-Rendering-Format reiner Text sein.

Die folgenden Markup-Renderer SOLLTEN für die angegebenen Dateierweiterungen verwendet werden

• Reiner Text: .txt, keine Erweiterung, unbekannte Erweiterung
• reStructured Text: .rst
• Markdown: .md
• AsciiDoc: .adoc, .asc, .asciidoc
• HTML: .html, .htm

Automatisierte Tools KÖNNEN eines oder mehrere der angegebenen Formate als reinen Text rendern und KÖNNEN andere Markup-Formate über die aufgeführten hinaus rendern.

Automatisierte Tools SOLLTEN keine Annahmen hinsichtlich der maximalen Länge von unterstützenden Dokumentinhalten treffen, außer soweit es zum Schutz der Integrität eines Dienstes erforderlich ist.

Beispiel

"document_names": {
    "description": "README.rst",
    "license": "LICENSE.rst",
    "changelog": "NEWS"
}

Kontaktinformationen

Details zu Einzelpersonen und Organisationen werden als Mappings mit den folgenden Unterfeldern aufgezeichnet

• name: der Name einer Einzelperson oder Gruppe
• email: eine E-Mail-Adresse (dies kann eine Mailingliste sein)
• url: eine URL (z. B. eine Profilseite auf einem Quellcode-Hosting-Dienst)
• role: einer von "author", "maintainer" oder "contributor"

Das Unterfeld name ist erforderlich, die anderen Unterfelder sind optional.

Wenn keine spezifische Rolle angegeben ist, ist der Standard contributor.

E-Mail-Adressen müssen im Format local-part@domain vorliegen, wobei der lokale Teil bis zu 64 Zeichen lang sein darf und die gesamte E-Mail-Adresse nicht mehr als 254 Zeichen enthält. Die formale Spezifikation des Formats ist in RFC 5322 (Abschnitte 3.2.3 und 3.4.1) und RFC 5321 enthalten, mit einer lesbareren Form in der informativen RFC 3696 und den zugehörigen Errata.

Die definierten Mitwirkenden-Rollen sind wie folgt

• author: der ursprüngliche Ersteller einer Distribution
• maintainer: der aktuelle Hauptmitwirkende für eine Distribution, wenn er nicht der ursprüngliche Ersteller ist
• contributor: alle anderen Einzelpersonen oder Organisationen, die an der Erstellung der Distribution beteiligt waren

Kontakt- und Mitwirkenden-Metadaten sind optional. Automatisierte Werkzeuge MÜSSEN korrekt funktionieren, wenn eine Distribution sie nicht bereitstellt, einschließlich eines sauberen Fehlers, wenn eine auf einem dieser Felder basierende Operation angefordert wird.

Kontakte

Eine Liste von Mitwirkenden-Einträgen, die die empfohlenen Kontaktpunkte für weitere Informationen über das Projekt angeben.

Das folgende Beispiel wäre für ein Projekt geeignet, das gerade vom ursprünglichen Autor an einen neuen Hauptwart übergeben wird und als Teil einer größeren Entwicklungsgruppe fungiert.

Beispiel

"contacts": [
  {
    "name": "Python Packaging Authority/Distutils-SIG",
    "email": "distutils-sig@python.org",
    "url": "https://bitbucket.org/pypa/"
  },
  {
    "name": "Samantha C.",
    "role": "maintainer",
    "email": "dontblameme@example.org"
  },
  {
    "name": "Charlotte C.",
    "role": "author",
    "email": "iambecomingasketchcomedian@example.com"
  }
]

Mitwirkende

Eine Liste von Mitwirkenden-Einträgen für andere Mitwirkende, die nicht bereits als aktuelle Projektkontaktpunkte aufgeführt sind. Die Unterfelder innerhalb der Listenelemente sind dieselben wie die für das Hauptkontaktfeld.

Beispiel

"contributors": [
  {"name": "John C."},
  {"name": "Erik I."},
  {"name": "Terry G."},
  {"name": "Mike P."},
  {"name": "Graeme C."},
  {"name": "Terry J."}
]

Projekt-URLs

Ein Mapping von beliebigen Textlabels zu zusätzlichen URLs, die für das Projekt relevant sind.

Während Projekte frei sind, ihre eigenen Labels und spezifischen URLs zu wählen, wird EMPFOHLEN, Links zur Homepage, zur Quellcodeverwaltung, zum Issue Tracker und zur Dokumentation mit den im folgenden Beispiel genannten Labels bereitzustellen.

URL-Labels MÜSSEN von automatisierten Tools als nicht case-sensitiv behandelt werden, sie müssen aber keine gültigen Python-Bezeichner sein. Jede legale JSON-Zeichenkette ist als URL-Label zulässig.

Beispiel

"project_urls": {
  "Documentation": "https://distlib.readthedocs.org",
  "Home": "https://bitbucket.org/pypa/distlib",
  "Repository": "https://bitbucket.org/pypa/distlib/src",
  "Tracker": "https://bitbucket.org/pypa/distlib/issues"
}

Export-Spezifizierer

Ein Export-Spezifizierer ist eine Zeichenkette, die aus einem vollqualifizierten Namen sowie einem optionalen zusätzlichen Namen in eckigen Klammern besteht. Dies ergibt die folgenden vier möglichen Formen für einen Export-Spezifizierer

module
module:name
module[requires_extra]
module:name[requires_extra]

Die Bedeutung der Unterfelder ist wie folgt

• module: das Modul, das den Export bereitstellt
• name: falls zutreffend, der qualifizierte Name des Exports innerhalb des Moduls
• requires_extra: gibt an, dass der Export nur korrekt funktioniert, wenn die zusätzlichen Abhängigkeiten, die im angegebenen Extra genannt sind, in der installierten Umgebung verfügbar sind

Module

Eine Liste von qualifizierten Namen von Modulen und Paketen, die die Distribution zum Import bereitstellt.

Bei Namen, die Punkte enthalten, MUSS der Teil des Namens vor dem letzten Punkt entweder in der Liste der installierten Module oder in der Liste der Namespace-Pakete enthalten sein.

Um Namenskonflikte zu vermeiden, wird EMPFOHLEN, dass Distributionen ein einzelnes Top-Level-Modul oder -Paket bereitstellen, das dem Distributionsnamen (oder einer Kleinbuchstaben-Entsprechung) entspricht. Dies erfordert, dass der Distributionsname auch die Anforderungen eines Python-Bezeichners erfüllt, die strenger sind als die für Distributionsnamen). Diese Praxis erleichtert auch das Auffinden autoritativer Quellen für Module.

Indexserver SOLLTEN es mehreren Distributionen erlauben, dieselben Module zu veröffentlichen, KÖNNEN aber die Autoren der Distributionen über potenzielle Konflikte informieren.

Installationstools SOLLTEN einen Fehler melden, wenn sie aufgefordert werden, eine Distribution zu installieren, die ein Modul bereitstellt, das auch von einer anderen, bereits installierten, Distribution bereitgestellt wird.

Beachten Sie, dass der Versuch, einige deklarierte Module zu importieren, zu einer Ausnahme führen kann, wenn die entsprechenden Extras nicht installiert sind.

Beispiel

"modules": ["chair", "chair.cushions", "python_sketches.nobody_expects"]

Namespaces

Eine Liste von qualifizierten Namen von Namespace-Paketen, zu denen die Distribution Module beiträgt.

Bei Python-Versionen vor Python 3.3 (das native Namespace-Paket-Unterstützung bietet) SOLLTEN Installationstools eine geeignete __init__.py-Datei ausgeben, um den Namespace ordnungsgemäß zu initialisieren, anstatt eine von der Distribution bereitgestellte Datei zu verwenden.

Installationstools SOLLTEN eine Warnung ausgeben und KÖNNEN einen Fehler ausgeben, wenn eine Distribution ein Namespace-Paket deklariert, das mit dem Namen eines bereits installierten Moduls kollidiert oder umgekehrt.

Beispiel

"namespaces": ["python_sketches"]

Exporte

Das Feld exports ist ein Mapping, das vorangestellte Namen als Schlüssel enthält. Jeder Schlüssel identifiziert eine Exportgruppe, die einen oder mehrere von der Distribution veröffentlichte Exporte enthält.

Exportgruppen-Namen werden von Distributionen definiert, die dann die veröffentlichten Exportinformationen auf irgendeine Weise nutzen werden. Der primäre Anwendungsfall sind Distributionen, die ein Plugin-Modell unterstützen: die Definition einer Exportgruppe ermöglicht es anderen Distributionen, anzugeben, welche Plugins sie bereitstellen, wie sie importiert und darauf zugegriffen werden können und welche zusätzlichen Abhängigkeiten (falls vorhanden) für das korrekte Funktionieren des Plugins erforderlich sind.

Um die Wahrscheinlichkeit von Namenskonflikten zu verringern, SOLLTEN Exportgruppen-Namen ein Präfix verwenden, das einem Modulnamen in der Distribution entspricht, der die Bedeutung der Exportgruppe definiert. Diese Praxis erleichtert auch das Auffinden autoritativer Dokumentation für Exportgruppen.

Jeder einzelne Export ist dann ein Mapping von beliebigen nicht-leeren Zeichenketten-Schlüsseln zu Export-Spezifizierern. Die Bedeutung der Exportnamen innerhalb einer Exportgruppe liegt beim der Exportgruppe definierenden Distribution. Die Erstellung einer geeigneten Definition für das Exportnamenformat kann es der importierenden Distribution ermöglichen, festzustellen, ob ein Export relevant ist oder nicht, ohne jedes exportierende Modul importieren zu müssen.

Beispiel

"exports": {
  "nose.plugins.0.10": {
    "chairtest": "chair:NosePlugin"
  }
}

Unterstützte Umgebungen

Das Unterfeld environments ist eine Liste von Zeichenketten, die die Umgebungen angeben, die die Distribution explizit unterstützt. Eine Umgebung gilt als unterstützt, wenn sie mit mindestens einem der angegebenen Umgebungsmarker übereinstimmt.

Wenn dieses Feld nicht in den Metadaten angegeben ist, wird angenommen, dass die Distribution jede von Python unterstützte Plattform unterstützt.

Einzelne Einträge sind Umgebungsmarker, wie in PEP 426 beschrieben.

Die beiden Hauptanwendungen dieses Feldes sind die Deklaration, welche Python-Versionen und welche zugrundeliegenden Betriebssysteme unterstützt werden.

Beispiele für unterstützte Python-Versionen

# Supports Python 2.6+
"environments": ["python_version >= '2.6'"]

# Supports Python 2.6+ (for 2.x) or 3.3+ (for 3.x)
"environments": ["python_version >= '3.3'",
                 "'3.0' > python_version >= '2.6'"]

Beispiele für unterstützte Betriebssysteme

# Windows only
"environments": ["sys_platform == 'win32'"]

# Anything except Windows
"environments": ["sys_platform != 'win32'"]

# Linux or BSD only
"environments": ["'linux' in sys_platform",
                 "'bsd' in sys_platform"]

Beispiel, bei dem die unterstützte Python-Version je nach Plattform variiert

# The standard library's os module has long supported atomic renaming
# on POSIX systems, but only gained atomic renaming on Windows in Python
# 3.3. A distribution that needs atomic renaming support for reliable
# operation might declare the following supported environments.
"environment": ["python_version >= '2.6' and sys_platform != 'win32'",
                "python_version >= '3.3' and sys_platform == 'win32'"]

Metadatenerweiterungs-Constraints

Das Unterfeld extension_metadata ist ein Mapping von Distributionsnamen zu Metadatenschnipseln von Erweiterungen, die exakt mit den Metadaten der benannten Distribution in der Zielinstallationsumgebung übereinstimmen müssen.

Jedes Unter-Mapping besteht dann aus einem Mapping von Metadatenerweiterungsnamen zu den exakten erwarteten Werten einer Teilmenge von Feldern.

Zum Beispiel kann eine Distribution namens fortranlib je nach Build-Art eine andere FORTRAN ABI veröffentlichen, und alle verwandten Projekte, die in dieselbe Laufzeitumgebung installiert werden, sollten übereinstimmende Build-Optionen verwenden. Dies kann dadurch erreicht werden, dass die Basisdistribution eine benutzerdefinierte Erweiterung veröffentlicht, die die für die Erstellung der Binärerweiterungen verwendete Build-Option angibt

"extensions": {
  "fortranlib.compatibility": {
    "fortran_abi": "openblas-g77"
  }
}

Andere Distributionen, die Binärerweiterungen enthalten, die mit der Basisdistribution kompatibel sein müssen, würden dann eine entsprechende Einschränkung in ihren eigenen Metadaten definieren

"python.constraints": {
  "installer_must_handle": true,
  "extension_metadata": {
    "fortranlib": {
      "fortranlib.compatibility": {
        "fortran_abi": "openblas-g77"
      }
    }
  }
}

Diese Einschränkung gibt an, dass

• fortranlib installiert sein muss (dies sollte auch als normale Abhängigkeit ausgedrückt werden, damit Installer sicherstellen, dass sie erfüllt ist)
• Die installierte Version von fortranlib muss die benutzerdefinierte Erweiterung fortranlib.compatibility in ihren veröffentlichten Metadaten enthalten
• Das Unterfeld fortan_abi dieser Erweiterung muss den *exakten* Wert openblas-g77 haben.

Wenn all diese Bedingungen erfüllt sind (die Distribution ist installiert, die angegebene Erweiterung ist in den Metadaten enthalten, die angegebenen Unterfelder haben den exakten angegebenen Wert), dann gilt die Einschränkung als erfüllt.