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
simple-git-versioning
to derive a 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.25.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 399c4e9f0ac0ed277216a37837de5a0b4b63c8059876e49c44e53eb0946fcdbb |
|
MD5 | ff6636f8201fddb61985550973b6cf1a |
|
BLAKE2b-256 | 59791300ee4c8c4fd06f90b23056e8dfd892b7721d0b53f7eea5a70ed48b1ed9 |
Hashes for simple_git_versioning-0.1.25-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 55cac368c4e64bc8115e4e56a77e07290ace88ee64f667310ab22f89eede212f |
|
MD5 | 37854cd16880c0181252515a3ca9b24a |
|
BLAKE2b-256 | 6349419e83b99bbafdacb66d598cc6e32f1691d4a1d43a60bb85f215fb8f0b12 |