lock-version

• Typ: String; Wert von "1.0"
• Erforderlich?: Ja
• Inspiration: Metadata-Version
• Aufzeichnung der Dateiformatversion, der die Datei entspricht.
• Dieses PEP spezifiziert die initiale Version – und den einzigen gültigen Wert, bis zukünftige Updates des Standards diese ändern – als "1.0".
• Wenn ein Werkzeug die Hauptversion unterstützt, aber nicht die Nebenversion, SOLLTE ein Werkzeug eine Warnung ausgeben, wenn ein unbekannter Schlüssel gesehen wird.
• Wenn ein Werkzeug keine Hauptversion unterstützt, MUSS es einen Fehler ausgeben.

environments

• Typ: Array von Strings
• Erforderlich?: Nein
• Inspiration: uv
• Eine Liste von Umgebungsmarkern, für die die Sperrdatei als kompatibel gilt.
• Werkzeuge SOLLTEN exklusive/nicht überlappende Umgebungsmarker schreiben, um das Verständnis zu erleichtern.

requires-python

• Typ: String
• Erforderlich?: Nein
• Inspiration: PDM, Poetry, uv
• Gibt die Requires-Python für die minimale Python-Version an, die mit jeder vom Sperrdatei unterstützten Umgebung kompatibel ist (d. h. die minimale brauchbare Python-Version für die Sperrdatei).

extras

• Typ: Array von Strings
• Erforderlich?: Nein; Standardwert ist []
• Inspiration: Provides-Extra (mehrfache Verwendung)
• Die Liste der Extras, die von dieser Sperrdatei unterstützt werden.
• Lockers KÖNNEN wählen, keine Sperrdateien zu unterstützen, die Extras und Abhängigkeitsgruppen unterstützen (d. h. Werkzeuge können nur eine Einmal-Sperrdatei exportieren).
• Werkzeuge, die Extras unterstützen, MÜSSEN auch Abhängigkeitsgruppen unterstützen.
• Werkzeuge SOLLTEN diesen Schlüssel explizit auf ein leeres Array setzen, um zu signalisieren, dass die zur Generierung der Sperrdatei verwendeten Eingaben keine Extras hatten (z. B. hatte eine pyproject.toml-Datei keine [project.optional-dependencies]-Tabelle), was signalisiert, dass die Sperrdatei effektiv mehrfach verwendet werden kann, auch wenn sie nur als Einmal-Sperrdatei erscheint.

dependency-groups

• Typ: Array von Strings
• Erforderlich?: Nein; Standardwert ist []
• Inspiration: Beliebige Werkzeugkonfiguration: die [tool]-Tabelle
• Die Liste der Abhängigkeitsgruppen, die von dieser Sperrdatei öffentlich unterstützt werden (d. h. Abhängigkeitsgruppen, die Benutzer voraussichtlich über eine Benutzeroberfläche eines Werkzeugs angeben können).
• Lockers KÖNNEN wählen, keine Sperrdateien zu unterstützen, die Extras und Abhängigkeitsgruppen unterstützen (d. h. Werkzeuge können nur eine Einmal-Sperrdatei exportieren).
• Werkzeuge, die Abhängigkeitsgruppen unterstützen, MÜSSEN auch Extras unterstützen.
• Werkzeuge SOLLTEN diesen Schlüssel explizit auf ein leeres Array setzen, um zu signalisieren, dass die zur Generierung der Sperrdatei verwendeten Eingaben keine Abhängigkeitsgruppen hatten (z. B. hatte eine pyproject.toml-Datei keine [dependency-groups]-Tabelle), was signalisiert, dass die Sperrdatei effektiv mehrfach verwendet werden kann, auch wenn sie nur als Einmal-Sperrdatei erscheint.

default-groups

• Typ: Array von Strings
• Erforderlich?: Nein; Standardwert ist []
• Inspiration: Poetry, PDM
• Der Name von synthetischen Abhängigkeitsgruppen, die darstellen, was standardmäßig installiert werden soll (z. B. was project.dependencies implizit darstellt).
• Sollte in Situationen verwendet werden, in denen packages.marker eine solche Gruppe erfordert.
• Die von diesem Schlüssel aufgelisteten Gruppen SOLLTEN NICHT in dependency-groups aufgeführt werden, da die Gruppen nicht direkt namentlich für Benutzer bestimmt sind, sondern über die Benutzeroberfläche eines Installers.

created-by

• Typ: String
• Erforderlich?: Ja
• Inspiration: Werkzeuge mit ihrem Namen im Sperrdateinamen
• Zeichnet den Namen des Werkzeugs auf, das zum Erstellen der Sperrdatei verwendet wurde.
• Werkzeuge KÖNNEN die [tool]-Tabelle verwenden, um genügend Details aufzuzeichnen, dass abgeleitet werden kann, welche Eingaben zur Erstellung der Sperrdatei verwendet wurden.
• Werkzeuge SOLLTEN den normalisierten Namen des Werkzeugs aufzeichnen, wenn es als Python-Paket verfügbar ist, um die Suche nach dem Werkzeug zu erleichtern.

[[packages]]

• Typ: Array von Tabellen
• Erforderlich?: Ja
• Inspiration: PDM, Poetry, uv
• Ein Array, das alle Pakete enthält, die installiert werden *können*.
• Pakete KÖNNEN mehrmals mit unterschiedlichen Daten aufgeführt werden, aber alle zu installierenden Pakete MÜSSEN zur Installationszeit auf einen einzigen Eintrag reduziert werden.

[tool]

• Typ: Tabelle
• Erforderlich?: Nein
• Inspiration: Beliebige Werkzeugkonfiguration: die [tool]-Tabelle
• Siehe packages.tool.

Verwendung von *.pylock.toml als Dateiname

Es wurde vorgeschlagen, den pylock-Konstante Teil des Dateinamens nach der Kennung für den Zweck der Lock-Datei zu setzen. Dies wurde abgelehnt, damit Lock-Dateien beim Betrachten von Verzeichnisinhalten zusammen sortiert werden und nicht rein nach ihrem Zweck, was sie in einem Verzeichnis verteilen könnte.

Verwendung von *.pylock als Dateiname

Es wurde vorgeschlagen, nicht .toml als Dateierweiterung zu verwenden und stattdessen .pylock selbst zu verwenden. Dies wurde abgelehnt, damit Code-Editoren die Syntaxhervorhebung für eine Lock-Datei ohne spezielle Kenntnisse der Dateierweiterung bereitstellen können.

Keine Namenskonvention für die Datei

Es wurde erwogen, keine Anforderungen oder Anleitungen für den Namen einer Lock-Datei zu haben, dies wurde jedoch letztendlich abgelehnt. Durch eine standardisierte Namenskonvention ist es einfach, eine Lock-Datei sowohl für einen Menschen als auch für einen Code-Editor zu identifizieren. Dies erleichtert die Entdeckung, wenn z. B. ein Werkzeug alle verfügbaren Lock-Dateien identifizieren möchte.

JSON statt TOML verwenden

Da das Vorhandensein eines maschinenbeschreibbaren Formats ein Ziel dieses PEP war, wurde JSON vorgeschlagen. Dies wurde jedoch als weniger lesbar als TOML angesehen, ohne den maschinenbeschreibbaren Aspekt ausreichend zu verbessern, um die Änderung zu rechtfertigen.

YAML statt TOML verwenden

Einige argumentierten, dass YAML die Anforderung maschinenbeschreibbar/menschenlesbar besser erfüllt als TOML. Da dies jedoch subjektiv ist und pyproject.toml bereits als menschenlesbare Datei existierte, die von Python-Packaging-Standards verwendet wurde, wurde es als wichtiger erachtet, weiterhin TOML zu verwenden.

Ein einziger Hash-Algorithmus für die gesamte Datei

Frühere Versionen dieses PEP schlugen vor, nur einen einzigen Hash-Algorithmus pro Datei anzugeben, anstatt eine beliebige Anzahl von Algorithmen pro Datei. Die Überlegung war, dass die Angabe eines einzelnen Algorithmus die Überprüfung der Datei erleichtert, wenn ein bestimmter Hash-Algorithmus zur Verwendung vorgeschrieben war.

Letztendlich gab es Einwände gegen diese Idee. Typischerweise drehten sie sich um die Kosten des Rehashing großer Wheel-Dateien (z. B. PyTorch). Es gab auch Bedenken, dass Hashing-Entscheidungen im Voraus vom Installer getroffen werden, mit denen dieser möglicherweise nicht einverstanden ist. Letztendlich wurde es als besser angesehen, Flexibilität zu bieten und den Leuten die Überprüfung der Lock-Datei nach Belieben zu überlassen.

Hashing des Inhalts der Sperrdatei selbst

Es wurde zu einem bestimmten Zeitpunkt vorgeschlagen, die Inhalte der Bytes der Datei zu hashen und den Hash-Wert in der Datei selbst zu speichern. Dies wurde entfernt, um das Zusammenführen von Änderungen an der Lock-Datei zu erleichtern, da jede Zusammenführung den Hash-Wert neu berechnen müsste, um einen Merge-Konflikt zu vermeiden.

Das Hashing des semantischen Inhalts der Datei wurde ebenfalls vorgeschlagen, aber es würde zu demselben Merge-Konfliktproblem führen.

Unabhängig davon, welche Inhalte gehasht wurden, könnte in beiden Fällen der Hash-Wert außerhalb der Datei gespeichert werden, wenn ein solcher Hash gewünscht wird.

Aufzeichnung des Erstellungsdatums der Sperrdatei

Um zu wissen, wie potenziell veraltet die Lock-Datei war, schlug ein früherer Vorschlag vor, das Erstellungsdatum der Lock-Datei aufzuzeichnen. Aus denselben Gründen wie beim Speichern des Hashs des Datei-Inhalts wurde diese Idee jedoch verworfen, um Merge-Konflikte zu vermeiden.

Aufzeichnung der verwendeten Paketindizes bei der Suche

Die Aufzeichnung, welche Paketindizes zur Erstellung der Lock-Datei verwendet wurden, wurde in Betracht gezogen. Letztendlich wurde dies jedoch abgelehnt, da es als unnötige Buchhaltung angesehen wurde.

Sperrung von Build-Anforderungen für sdists

Eine frühere Version dieses PEP versuchte, die Build-Anforderungen für sdists unter einem packages.build-requires-Schlüssel zu sperren. Leider hat es genügend Leute verwirrt, wie es betrieben werden sollte, und es gab genügend Randfälle, um zu entscheiden, dass es sich nicht lohnt, dies in diesem PEP im Voraus zu versuchen. Stattdessen könnte ein zukünftiges PEP eine Lösung vorschlagen.

Ein dedizierter direct-Schlüssel

Frühere Versionen hatten einen dedizierten packages.direct-Schlüssel, um zu kennzeichnen, wann etwas aus einer direkten URL-Referenz stammt. Es gibt jedoch explizit nur drei Fälle, in denen eine direkte URL-Referenz auftreten kann (VCS, Verzeichnis und Archiv). Da alle drei Fälle in [[packages]] explizit sind, war die Einstellung des Schlüssels technisch überflüssig.

Der einzige Nachteil, diesen Schlüssel nicht zu haben, betrifft Wheels und sdists, die nun unter packages.archive fallen. Mit dem separaten Schlüssel (oder wenn er als Teil von packages.sdist oder packages.wheels angegeben wird) wäre es möglich, in der Lock-Datei selbst zu identifizieren, dass eine Archivdatei ein sdist oder Wheel ist. Aktuell muss ein Installer dieses Detail selbst ableiten.

Löschen der Aufzeichnung der Paketversion

Die Paketversion ist optional, da sie nur zuverlässig aufgezeichnet werden kann, wenn eine sdist- oder Wheel-Datei verwendet wird. Da beide Quellen die Version in den Dateinamen aufzeichnen, ist sie technisch redundant.

In Diskussionen wurde jedoch entschieden, dass die Versionsnummer für die Überprüfung nützlich ist, um sie weiterhin separat anzugeben.

Löschen der Anforderung, den Speicherort einer sdist und/oder Wheels anzugeben

Mindestens eine Person hat kommentiert, dass ihre Arbeit instabile URLs für alle sdists und Wheels hat. Daher müssen sie bei der Installation nach allen Dateien suchen, unabhängig davon, wo die Datei zuvor gefunden wurde. Das Wegfallen der Anforderung, die URL oder den Pfad zu einer Datei anzugeben, hätte geholfen, das Problem der Aufzeichnung von als bekannt schlecht eingestuften Informationen zu lösen.

Die Entscheidung, Werkzeugen zu erlauben, nach einer Datei auf andere Weise als über die bereitgestellte URL zu suchen, beseitigte die Notwendigkeit, die URL optional zu machen.

Löschen der Anforderung von Dateigröße und Hashes

Mindestens eine Person hat gesagt, dass ihre Arbeit alle Wheels und sdists mit internen Dateien modifiziert. Das bedeutet, dass alle aufgezeichneten Hashes und Dateigrößen falsch sind. Indem die Dateigröße und die Hashes optional gemacht werden – sehr wahrscheinlich über einen Opt-out-Mechanismus –, könnten sie weiterhin Lock-Dateien produzieren, die die Anforderungen dieses PEP erfüllen.

Es wurde entschieden, dass dies die Sicherheit zu stark schwächt. Es verhindert auch die Installation von Dateien aus alternativen Speicherorten.

Löschen der Aufzeichnung des sdist-Dateinamens

Obwohl mit dem Wegfall der URL/Pfad-Anforderung, der Paketversion und der Hashes nicht kompatibel, ist die Aufzeichnung des sdist-Dateinamens technisch überhaupt nicht notwendig (derzeit ist die Aufzeichnung des Dateinamens optional). Der Dateiname kodiert nur den Projektnamen und die Version, sodass keine neuen Informationen über die Datei übermittelt werden (wenn die Paketversion angegeben ist). Und wenn der Speicherort aufgezeichnet wird, ist das Abrufen der Datei unabhängig vom Dateinamen erledigt.

Die Aufzeichnung des Dateinamens kann jedoch hilfreich sein, wenn nach einer geeigneten Datei gesucht wird, wenn der aufgezeichnete Dateispeicherort nicht mehr verfügbar ist (während sdist-Dateinamen dank PEP 625 inzwischen standardisiert sind, ist dies nur seit 2020 der Fall, und daher gibt es viele ältere sdists mit Namen, die möglicherweise nicht erratbar sind).

Es wurde die Entscheidung getroffen, den sdist-Dateinamen aus Gründen der Einfachheit vorzuschreiben.

Machen von packages.wheels zu einer Tabelle

Man könnte sich vorstellen, die Details von Wheel-Dateien als Tabelle mit dem Dateinamen als Schlüssel zu schreiben. Zum Beispiel

[[packages]]
name = "attrs"
version = "23.2.0"
requires-python = ">=3.7"
index = "https://pypi.org/simple/"

[packages.wheels]
"attrs-23.2.0-py3-none-any.whl" = {upload-time = 2023-12-31T06:30:30.772444Z, url = "https://files.pythonhosted.org/packages/e0/44/827b2a91a5816512fcaf3cc4ebc465ccd5d598c45cefa6703fcf4a79018f/attrs-23.2.0-py3-none-any.whl", size = 60752, hashes = {sha256 = "99b87a485a5820b23b879f04c2305b44b951b502fd64be915879d77a7e8fc6f1"}

[[packages]]
name = "numpy"
version = "2.0.1"
requires-python = ">=3.9"
index = "https://pypi.org/simple/"

[packages.wheels]
"numpy-2.0.1-cp312-cp312-macosx_10_9_x86_64.whl" = {upload-time = 2024-07-21T13:37:15.810939Z, url = "https://files.pythonhosted.org/packages/64/1c/401489a7e92c30db413362756c313b9353fb47565015986c55582593e2ae/numpy-2.0.1-cp312-cp312-macosx_10_9_x86_64.whl", size = 20965374, hashes = {sha256 = "6bf4e6f4a2a2e26655717a1983ef6324f2664d7011f6ef7482e8c0b3d51e82ac"}
"numpy-2.0.1-cp312-cp312-macosx_11_0_arm64.whl" = {upload-time = 2024-07-21T13:37:36.460324Z, url = "https://files.pythonhosted.org/packages/08/61/460fb524bb2d1a8bd4bbcb33d9b0971f9837fdedcfda8478d4c8f5cfd7ee/numpy-2.0.1-cp312-cp312-macosx_11_0_arm64.whl", size = 13102536, hashes = {sha256 = "7d6fddc5fe258d3328cd8e3d7d3e02234c5d70e01ebe377a6ab92adb14039cb4"}
"numpy-2.0.1-cp312-cp312-macosx_14_0_arm64.whl" = {upload-time = 2024-07-21T13:37:46.601144Z, url = "https://files.pythonhosted.org/packages/c2/da/3d8debb409bc97045b559f408d2b8cefa6a077a73df14dbf4d8780d976b1/numpy-2.0.1-cp312-cp312-macosx_14_0_arm64.whl", size = 5037809, hashes = {sha256 = "5daab361be6ddeb299a918a7c0864fa8618af66019138263247af405018b04e1"}
"numpy-2.0.1-cp312-cp312-macosx_14_0_x86_64.whl" = {upload-time = 2024-07-21T13:37:58.784393Z, url = "https://files.pythonhosted.org/packages/6d/59/85160bf5f4af6264a7c5149ab07be9c8db2b0eb064794f8a7bf6d/numpy-2.0.1-cp312-cp312-macosx_14_0_x86_64.whl", size = 6631813, hashes = {sha256 = "ea2326a4dca88e4a274ba3a4405eb6c6467d3ffbd8c7d38632502eaae3820587"}
"numpy-2.0.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl" = {upload-time = 2024-07-21T13:38:19.714559Z, url = "https://files.pythonhosted.org/packages/5e/e3/944b77e2742fece7da8dfba6f7ef7dccdd163d1a613f7027f4d5b/numpy-2.0.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", size = 13623742, hashes = {sha256 = "529af13c5f4b7a932fb0e1911d3a75da204eff023ee5e0e79c1751564221a5c8"}
"numpy-2.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl" = {upload-time = 2024-07-21T13:38:48.972569Z, url = "https://files.pythonhosted.org/packages/2c/f3/61eee37decb58e7cb29940f19a1464b8608f2cab8a8616aba75fd/numpy-2.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", size = 19242336, hashes = {sha256 = "6790654cb13eab303d8402354fabd47472b24635700f631f041bd0b65e37298a"}
"numpy-2.0.1-cp312-cp312-musllinux_1_1_x86_64.whl" = {upload-time = 2024-07-21T13:39:19.213811Z, url = "https://files.pythonhosted.org/packages/77/b5/c74cc436114c1de5912cdb475145245f6e645a6a1a29b5d08c774/numpy-2.0.1-cp312-cp312-musllinux_1_1_x86_64.whl", size = 19637264, hashes = {sha256 = "cbab9fc9c391700e3e1287666dfd82d8666d10e69a6c4a09ab97574c0b7ee0a7"}
"numpy-2.0.1-cp312-cp312-musllinux_1_2_aarch64.whl" = {upload-time = 2024-07-21T13:39:41.812321Z, url = "https://files.pythonhosted.org/packages/da/89/c8856e12e0b3f6af371ccb90d604600923b08050c58f0cd26eac9/numpy-2.0.1-cp312-cp312-musllinux_1_2_aarch64.whl", size = 14108911, hashes = {sha256 = "99d0d92a5e3613c33a5f01db206a33f8fdf3d71f2912b0de1739894668b7a93b"}
"numpy-2.0.1-cp312-cp312-win32.whl" = {upload-time = 2024-07-21T13:39:52.932102Z, url = "https://files.pythonhosted.org/packages/15/96/310c6f6d146518479b0a6ee6eb92a537954ec3b1acfa2894d1347/numpy-2.0.1-cp312-cp312-win32.whl", size = 6171379, hashes = {sha256 = "173a00b9995f73b79eb0191129f2455f1e34c203f559dd118636858cc452a1bf"}
"numpy-2.0.1-cp312-cp312-win_amd64.whl" = {upload-time = 2024-07-21T13:40:17.532627Z, url = "https://files.pythonhosted.org/packages/b5/59/f6ad378ad85ed9c2785f271b39c3e5b6412c66e810d2c60934c9f/numpy-2.0.1-cp312-cp312-win_amd64.whl", size = 16255757, hashes = {sha256 = "bb2124fdc6e62baae159ebcfa368708867eb56806804d005860b6007388df171"}

Im Allgemeinen bevorzugten die Leute dies jedoch nicht gegenüber dem Ansatz, den dieses PEP verfolgt.

Löschen der [tool]-Tabelle

Die [tool]-Tabelle ist enthalten, da sie sich für pyproject.toml-Dateien als sehr nützlich erwiesen hat. Die Bereitstellung ähnlicher Flexibilität in diesem PEP soll hoffen, dass ähnliche Vorteile entstehen.

Einige Leute haben jedoch Bedenken geäußert, dass eine solche Tabelle für Werkzeuge zu verlockend sein wird und zu werkzeugspezifischen und von anderen Werkzeugen unbrauchbaren Dateien führen wird. Dies könnte Probleme für Werkzeuge verursachen, die Installationen, Überprüfungen usw. durchführen, da sie nicht wissen würden, welche Details in der [tool]-Tabelle kritisch sind.

Als Kompromiss legt dieses PEP fest, dass die in [tool] aufgezeichneten Details verwerfbar sein müssen und die Installation von Paketen nicht beeinträchtigen dürfen.

Auflistung der Anforderungseingaben für die Datei

Derzeit werden in der Datei nicht die Anforderungen aufgezeichnet, die als Eingaben für die Datei dienten. Dies geschieht aus Gründen der Einfachheit und um die Datei nicht auf eine unvorhergesehene Weise explizit einzuschränken (z. B. die Aktualisierung der Datei nach der anfänglichen Erstellung für eine neue Plattform mit anderen Anforderungen, ohne auflösen zu müssen, wie ein umfassendes Anforderungsspektrum geschrieben werden soll).

Es könnte jedoch bei der Überprüfung und jeder Neuerstellung der Datei helfen, wenn die ursprünglichen Anforderungen irgendwie aufgezeichnet wurden. Dies könnte eine einzelne Zeichenkette oder ein Array von Zeichenketten sein, wenn mehrere Anforderungen mit der Datei verwendet wurden.

Letztendlich wurde es als zu kompliziert erachtet, die Eingaben, die ein Werkzeug zum Erstellen der Lock-Datei verwendet hat, auf generische Weise zu erfassen.

Aufzeichnung von Abhängigen

Die Aufzeichnung der Abhängigkeiten eines Pakets ist nicht erforderlich, um es zu installieren. Daher wurde es aus dem PEP ausgeschlossen, da es über [tool] enthalten werden kann.

Das Wissen, wie kritisch ein Paket für andere Pakete ist, kann jedoch von Vorteil sein. Diese Information ist in pip-tools enthalten, es gibt also bereits Beispiele dafür. Ein flexibler Ansatz könnte verwendet werden, um die Abhängigkeiten aufzuzeichnen, z. B. so viele Details wie nötig, um sie von jedem anderen Eintrag für dasselbe Paket in der Datei zu unterscheiden (inspiriert von uv).

Letztendlich wurde jedoch entschieden, dass die Aufzeichnung der Abhängigkeiten sinnvoller ist.