Inkrementell ist ein CalVer-Versionsmanager, der die Zukunft unterstützt.
Die API-Dokumentation finden Sie hier. Es folgt eine narrative Dokumentation.
Inhalt
Betriebstheorie
Schnellstart
Verwenden von Setuptools
Jungtier verwenden
Verwenden von setup.py
Initialisieren Sie das Projekt
Laufzeitintegration
Inkrementelle Versionen
Aktualisierung
Unbestimmte Versionen
Eine Versionsnummer hat die Form JJ.MM.PATCH.
Wenn Ihr Projekt „Shrubbery“ heißt, befindet sich der Code in shrubbery/ oder src/shrubbery/ .
Inkrementell speichert die Versionsnummer Ihres Projekts in {src/}shrubbery/_version.py .
Um die Version zu aktualisieren, führen Sie incremental update Shrubbery aus und übergeben Sie dabei gegebenenfalls --rc und/oder --patch (siehe Aktualisieren unten).
Durch das Ändern der Version werden auch alle unbestimmten Versionen in Ihrer Codebasis aktualisiert, z. B. „Shrubbery NEXT“, sodass Sie in der Dokumentation auf die kommende Version verweisen können. So unterstützt Inkremental die Zukunft.
Fügen Sie Inkremental zu Ihrem pyproject.toml hinzu:
[build-system]requires = ["setuptools","incremental>=24.7.2", # ← Inkrementell als Build-Abhängigkeit hinzufügen]build-backend = "setuptools.build_meta"[project]name = ""dynamic = ["version"] # ← Markieren Sie die Versiondynamicdependencies = ["incremental>=24.7.2", # ← Zur Laufzeit von Inkremental abhängig machen]# ...[tool.incremental] # ← Aktivieren Sie das Setuptools-Plugin von Incremental
Es ist in Ordnung, wenn die Tabelle [tool.incremental] leer ist, aber sie muss vorhanden sein.
Entfernen Sie alle Einträge [project] version = und alle Einträge für [tool.setuptools.dynamic] version = .
Als nächstes initialisieren Sie das Projekt.
Wenn Sie Hatchling zum Packen Ihres Projekts verwenden, aktivieren Sie das Hatchling-Plugin von Incremental, indem Sie Ihre pyproject.toml ändern:
[build-system]requires = ["hatchling","incremental>=24.7.2", # ← Inkrementell als Build-Abhängigkeit hinzufügen]build-backend = "hatchling.build"[project]name = ""dynamic = ["version"] # ← Markieren Sie die Versiondynamicdependencies = ["inkremental>=24.7.2", # ← Zur Laufzeit von inkrementell abhängig]# ...[tool.hatch.version]source = "inkrementell" # ← Aktivieren Das Hatchling-Plugin von Incremental
Inkrementell kann wie gewohnt in einer optionalen Tabelle [tool.incremental] konfiguriert werden.
Der Befehl hatch version meldet die inkrementell verwaltete Version. Verwenden Sie den Befehl incremental update um die Version zu ändern (das Festlegen mit hatch version wird nicht unterstützt).
Als nächstes initialisieren Sie das Projekt.
setup.py Inkrementell kann von setup.py anstelle von pyproject.toml verwendet werden. Fügen Sie dies zu Ihrem setup() -Aufruf hinzu und entfernen Sie alle anderen Versionierungsargumente:
setup(use_incremental=True,setup_requires=['incremental'],install_requires=['incremental'], # zusammen mit allen anderen Installationsabhängigkeiten ... }
Anschließend initialisieren Sie das Projekt.
Installieren Sie Inkremental mit pipx install incremental in Ihrer lokalen Umgebung. Führen Sie dann incremental update aus. Es wird eine Datei in Ihrem Paket mit dem Namen _version.py wie folgt erstellt:
aus inkrementellem Import Version__version__ = Version("", 24, 1, 0)__all__ = ["__version__"] Nachfolgende Installationen Ihres Projekts verwenden dann Inkrementell zur Versionierung.
Sie können die incremental.Version von _version.py in der API Ihres Pakets verfügbar machen. Fügen Sie dazu __init__.py Ihres Root-Pakets hinzu:
aus ._version import __version__
Notiz
Die Bereitstellung eines __version__ Attributs kommt nach der Einführung von importlib.metadata.version() in Python 3.6 aus der Mode, das die Version eines installierten Pakets abrufen kann.
Wenn Sie dieses Objekt nicht öffentlich verfügbar machen oder es in Ihrem Paket verwenden, besteht keine Notwendigkeit, zur Laufzeit auf Inkremental angewiesen zu sein. Sie können es aus dem dependencies Ihres Projekts entfernen (oder in setup.py aus install_requires ).
incremental.Version ist eine Klasse, die eine Version eines bestimmten Projekts darstellt. Es besteht aus folgenden Elementen (die bei der Instanziierung angegeben werden):
package (erforderlich), der Name des Pakets, das diese Version darstellt.
major , minor , micro (alles erforderlich), das XYZ der Version Ihres Projekts.
release_candidate (optional), auf 0 oder höher gesetzt, um zu kennzeichnen, dass es sich bei dieser Version um einen Release-Kandidaten handelt (manchmal auch als „Vorabversion“ bezeichnet).
post (optional), auf 0 oder höher setzen, um diese Version als Postrelease zu markieren.
dev (optional), auf 0 oder höher setzen, um diese Version als Entwicklungsversion zu kennzeichnen.
Sie können eine PEP-440-kompatible Versionszeichenfolge extrahieren, indem Sie die Methode .public() verwenden, die eine str zurückgibt, die die Vollversion enthält. Dies ist die Version, die Sie Benutzern zur Verfügung stellen oder öffentlich verwenden sollten. Eine Beispielausgabe wäre "13.2.0" , "17.1.2dev1" oder "18.8.0rc2" .
Wenn repr() mit einer Version aufrufen, erhalten Sie eine Python-Quellcode-Darstellung davon, und der Aufruf von str() für eine Version erzeugt eine Zeichenfolge wie '[Incremental, version 16.10.1]' .
Inkremental enthält ein Tool namens incremental , mit dem Sie die Aktualisierung der Version Ihres Inkremental verwendenden Projekts automatisieren können. Es aktualisiert die Datei _version.py und aktualisiert einige Verwendungen inkrementeller Versionen automatisch von einer unbestimmten Version auf die aktuelle. Es erfordert click von PyPI.
incremental update führt Aktualisierungen für dieses Paket durch. Die Befehle, die danach gegeben werden können, bestimmen, was die nächste Version ist.
--newversion= , um die Projektversion auf eine vollständig angegebene Version festzulegen (wie 1.2.3 oder 17.1.0dev1).
--rc , um die Projektversion auf
--dev , um die Entwicklungsversionsnummer des Projekts auf 0 zu setzen, wenn es sich nicht um eine Entwicklungsversion handelt, oder um die Entwicklungsversionsnummer um 1 zu erhöhen, wenn dies der Fall ist.
--patch , um die Patch-Nummer der Veröffentlichung zu erhöhen. Dadurch wird auch die Nummer des Release-Kandidaten zurückgesetzt und gleichzeitig --rc übergeben, um die Patch-Nummer zu erhöhen und ihn zu einem Release-Kandidaten zu machen.
--post , um die Nachveröffentlichungsnummer des Projekts auf 0 zu setzen, wenn es sich nicht um eine Nachveröffentlichung handelt, oder um die Nachveröffentlichungsnummer um 1 zu erhöhen, wenn dies der Fall ist. Dadurch werden auch die Release Candidate- und Development Release-Nummern zurückgesetzt.
Wenn Sie keine Argumente angeben, wird die Nummer des Release-Kandidaten entfernt, sodass es sich um eine „vollständige Veröffentlichung“ handelt.
Inkrementell unterstützt „unbestimmte“ Versionen als Ersatz für die nächste „vollständige“ Version. Dies kann verwendet werden, wenn die Version, die dem Endbenutzer angezeigt wird, unbekannt ist (z. B. „eingeführt in“ oder „veraltet in“). Inkremental unterstützt die folgenden unbestimmten Versionen:
Version("
Wenn Sie incremental update ausführen, werden diese auf echte Versionen aktualisiert (vorausgesetzt, die endgültige Zielversion ist 17.1.0):
Version("
Sobald die endgültige Version erstellt ist, wird sie wie folgt aussehen:
Version("
