Thinly scoped and opinionated tool that computes a version number from git tags and trailers
Project description
Opinionated version numbering CLIs, and library
This project aims at easing the burden of computing and managing a project's
version numbers by leveraging git
tags and commit trailers.
simple-git-versioning
provides two CLIs: semver2
and pep440
, one for each
supported versioning sheme of the same name: SemVer2
and
PEP440
.
Integration with setuptools
is supported.
Snippets to expose your project's version number programatically are provided in
the Libraries
section.
Installation
With pip
:
pip install simple-git-versioning
Usage
By default, pep440
and semver2
will compute a version number of the form
X.Y.Z
. Every project starts at 0.0.0
on their initial commit, and each
commit after that increments the number Z
by one, unless they include a
Version-Bump
trailer (case-insensitive) with a value of:
major
:X
is incremented;minor
:Y
is incremented;patch
:Z
is incremented (same as the default).
Each tool then provides the ability to switch to a pre-release mode; or
post-release, and/or dev release, etc. in the case of pep440
.
CLIs
All CLIs provide comprehensive help messages, available via the --help
option.
Libraries
Libraries that wish to expose their version number programatically may do so by including the following snippet:
PEP440
from importlib.metadata import PackageNotFoundError, version
from pathlib import Path
from versioning.pep440 import NoVersion, Project
try:
__version__ = version("<your python package's name>")
except PackageNotFoundError:
# package is not installed
with Project(path=Path(__file__).parent) as project:
try:
__version__ = str(project.version())
except NoVersion:
__version__ = str(project.release(dev=0))
SemVer2
from importlib.metadata import PackageNotFoundError, version
from pathlib import Path
from versioning.semver2 import NoVersion, Project
try:
__version__ = version("<your python package's name>")
except PackageNotFoundError:
# package is not installed
with Project(path=Path(__file__).parent) as project:
try:
__version__ = str(project.version())
except NoVersion:
__version__ = str(project.release(pre=("dev", 0))
setuptools
If you use setuptools
as a build backend for your project, you can configure
your project to use simple-git-versioning
to derive a build's version
automatically as follows:
In your pyproject.toml
:
- declare
version
as a dynamic metadata field; - add
simple-git-versioning
to your project'sbuild-system.requires
; - enable the
setuptools
integration in yourpyproject.toml
, and pick the versioning scheme you wish to apply.
[project]
name = ...
dynamic = ["version"]
[build-system]
requires = ["setuptools>=63", "simple-git-versioning"]
build-backend = "setuptools.build_meta"
[tool.simple-git-versioning]
setuptools = "pep440" # or "semver2"
I recommend checking out
setuptools-scm
andsetuptools-pipfile
, two othersetuptools
extensions I find greatly helpful.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for simple-git-versioning-0.1.18.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 74f28c50e0f0275790eeb46b42b4845e35094391ea443794db907debbd5210f2 |
|
MD5 | 0efdf783d5c396088c7c513d2b02f77e |
|
BLAKE2b-256 | a6e9a15397e649fb8a7618f707befb09d1e9a9e1d5c0475cb3953190d09a44f5 |
Hashes for simple_git_versioning-0.1.18-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7c7976429f37d6a3f86a9b63cc16f720a60011c2e7c9ab08c7e6e7882d513ba7 |
|
MD5 | fe96973666fc7c674edd138f5e49dfc2 |
|
BLAKE2b-256 | 4e8aea1808c0df47ecf1680d0c9054618017c559165ff9b967538a209057e809 |