Incremental est un gestionnaire de versions CalVer qui prend en charge l'avenir.
La documentation de l'API peut être trouvée ici. Une documentation narrative suit.
Contenu
Théorie du fonctionnement
Démarrage rapide
Utilisation des outils de configuration
Utiliser un nouveau-né
Utilisation de setup.py
Initialiser le projet
Intégration d'exécution
Versions incrémentielles
Mise à jour
Versions indéterminées
Un numéro de version a la forme YY.MM.PATCH.
Si votre projet s'appelle "Shrubbery", son code se trouve dans shrubbery/ ou src/shrubbery/ .
Incremental stocke le numéro de version de votre projet dans {src/}shrubbery/_version.py .
Pour mettre à jour la version, exécutez incremental update Shrubbery , en passant --rc et/ou --patch selon le cas (voir Mise à jour ci-dessous).
La modification de la version met également à jour toutes les versions indéterminées de votre base de code, comme "Shrubbery NEXT", afin que vous puissiez référencer la version à venir dans la documentation. C'est ainsi qu'Incremental soutient l'avenir.
Ajoutez un incrémental à votre pyproject.toml :
[build-system]requires = ["setuptools","incremental>=24.7.2", # ← Ajouter incrémental comme dépendance de build]build-backend = "setuptools.build_meta"[project]name = ""dynamic = ["version"] # ← Marquer la version Dynamicdependencies = ["incremental>=24.7.2", # ← Dépend de l'incrémental à runtime]# ...[tool.incremental] # ← Activer le plugin setuptools d'Incremental
Ce n'est pas grave si la table [tool.incremental] est vide, mais elle doit être présente.
Supprimez toute [project] version = entrée et toute [tool.setuptools.dynamic] version = entrée.
Ensuite, initialisez le projet.
Si vous utilisez Hatchling pour empaqueter votre projet, activez le plugin Hatchling d'Incremental en modifiant votre pyproject.toml :
[build-system]requires = ["hatchling","incremental>=24.7.2", # ← Ajouter un incrémentiel en tant que dépendance de build]build-backend = "hatchling.build"[project]name = ""dynamic = ["version"] # ← Marquer la version Dynamicdependencies = ["incremental>=24.7.2", # ← Dépend de l'incrémental au moment de l'exécution]# ...[tool.hatch.version]source = "incremental" # ← Activer le plugin Hatchling d'Incremental
L'incrémental peut être configuré comme d'habitude dans une table facultative [tool.incremental] .
La commande hatch version indiquera la version gérée par incrémentation. Utilisez la commande incremental update pour modifier la version (la définition avec hatch version n'est pas prise en charge).
Ensuite, initialisez le projet.
setup.py L'incrémental peut être utilisé à partir de setup.py au lieu de pyproject.toml . Ajoutez ceci à votre appel setup() , en supprimant tous les autres arguments de version :
setup(use_incremental=True,setup_requires=['incremental'],install_requires=['incremental'], # ainsi que toutes les autres dépendances d'installation... }
Initialisez ensuite le projet.
Installez Incremental dans votre environnement local avec pipx install incremental . Exécutez ensuite incremental update . Il créera un fichier dans votre package nommé _version.py comme ceci :
à partir de l'importation incrémentielle Version__version__ = Version("", 24, 1, 0)__all__ = ["__version__"] Les installations ultérieures de votre projet utiliseront ensuite Incremental pour la gestion des versions.
Vous pouvez exposer l' incremental.Version de _version.py dans l'API de votre package. Pour ce faire, ajoutez au __init__.py de votre package racine :
à partir de ._version importer __version__
Note
Fournir un attribut __version__ est passé de mode suite à l'introduction de importlib.metadata.version() dans Python 3.6, qui peut récupérer la version d'un package installé.
Si vous n'exposez pas cet objet publiquement et ne l'utilisez pas dans votre package, il n'est pas nécessaire de dépendre d'Incremental au moment de l'exécution. Vous pouvez le supprimer du tableau de dependencies de votre projet (ou, dans setup.py , de install_requires ).
incremental.Version est une classe qui représente une version d'un projet donné. Il est composé des éléments suivants (qui sont donnés lors de l'instanciation) :
package (obligatoire), le nom du package que cette Version représente.
major , minor , micro (tous obligatoires), le XYZ de la Version .
release_candidate (facultatif), défini sur 0 ou supérieur pour marquer que cette Version est une version candidate (également parfois appelée « préversion »).
post (facultatif), défini sur 0 ou supérieur pour marquer cette Version comme postrelease.
dev (facultatif), défini sur 0 ou supérieur pour marquer cette Version comme version de développement.
Vous pouvez extraire une chaîne de version compatible PEP-440 en utilisant la méthode .public() , qui renvoie une str contenant la version complète. Il s'agit de la version que vous devez fournir aux utilisateurs ou utiliser publiquement. Un exemple de sortie serait "13.2.0" , "17.1.2dev1" ou "18.8.0rc2" .
L'appel de repr() avec une Version en donnera une représentation du code source Python, et l'appel de str() sur une Version produit une chaîne comme '[Incremental, version 16.10.1]' .
Incremental inclut un outil pour automatiser la mise à jour de la version de votre projet utilisant Incremental appelé incremental . Il met à jour le fichier _version.py et met automatiquement à jour certaines utilisations des versions incrémentielles d'une version indéterminée vers la version actuelle. Cela nécessite click depuis PyPI.
incremental update effectuera des mises à jour sur ce package. Les commandes qui peuvent être données par la suite déterminent quelle sera la prochaine version.
--newversion= , pour définir la version du projet sur une version entièrement spécifiée (comme 1.2.3 ou 17.1.0dev1).
--rc , pour définir la version du projet sur
--dev , pour définir le numéro de version de développement du projet sur 0 s'il ne s'agit pas d'une version de développement, ou augmenter le numéro de version de développement de 1 s'il l'est.
--patch , pour incrémenter le numéro de patch de la version. Cela réinitialisera également le numéro de version candidate, passez --rc en même temps pour incrémenter le numéro de correctif et en faire une version candidate.
--post , pour définir le numéro de post-version du projet sur 0 s'il ne s'agit pas d'une post-version, ou augmenter le numéro de post-version de 1 s'il l'est. Cela réinitialisera également les numéros de version candidate et de version de développement.
Si vous ne donnez aucun argument, le numéro de version candidate sera supprimé, ce qui en fera une "version complète".
Incrémental prend en charge les versions « indéterminées », en remplacement de la prochaine version « complète ». Ceci peut être utilisé lorsque la version qui sera affichée à l'utilisateur final est inconnue (par exemple « introduite dans » ou « obsolète dans »). Incrémental prend en charge les versions indéterminées suivantes :
Version("
Lorsque vous exécutez incremental update , celles-ci seront mises à jour vers les versions réelles (en supposant que la version finale cible est 17.1.0) :
Version("
Une fois la version finale réalisée, elle deviendra :
Version("
