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))
poetry
If you use poetry
as a build frontend and backend for your project, you can
configure simple-git-versioning
to derive a version automatically as follows:
Install simple-git-versioning
alongside poetry
:
poetry self add "simple-git-versioning>=0.2"
Enable the poetry
integration in your pyproject.toml
, and pick the
versioning scheme you wish to apply:
[tool.poetry]
...
[tool.simple-git-versioning]
poetry = "pep440" # or "semver2"
Note that
poetry
mandates aversion
always be set inpyproject.toml
, so you will have to keep a placeholder there (e.g.version: "0.0.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.2.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4b9303a7721887abad7faf247ff12f0adb3381a40c2e81793c9dd395759e42f5 |
|
MD5 | 2839b2e9517f441c831ff97e197345d7 |
|
BLAKE2b-256 | 75f76dc8a44b36e160ba1b69ffc14515f799fcc8ad3cc602860f898c2bd77b7c |
Hashes for simple_git_versioning-0.2.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 80ac27d5954b6925943f731543b7ccb434a9bfe318f1c8c85f16967b4511797f |
|
MD5 | c39c83b7d0a08da10d25018835cb4ddb |
|
BLAKE2b-256 | 9d265bb147a4dfac4823feb80cf97f06c7d9bf70a4f70c6cc439f7c1895617e6 |