scmver

scmver is a package version manager based on SCM tags.

It can be used to pass the version to the setup function in a setup.py, or to generate a file which contains the version.

https://ci.appveyor.com/api/projects/status/l9flwehcgr5pxi33?svg=true

Installation

$ pip install scmver

Requirements

Python 3.10+
setuptools

Usage

pyproject.toml

[build-system]
requires = [
    "setuptools >= 42.0",
    "scmver[toml] >= 1.7",
]
build-backend = "setuptools.build_meta"

[tool.scmver]
spec = "micro"
write-to = "scmver/__version__.py"
fallback = {attr = "scmver:__version__"}

write-to

An alias for write_to, but it takes precedence.

fallback

attr: A string which is described in fallback in Configuration.
path (optional): A path to import the module.

See Configuration for key/value pairs.

setuptools

from setuptools import setup

setup(setup_requires=['scmver'],
      scmver=True)

scmver is either following values:

True: It is same as an empty dict.
callable object: It should return a dict.
dict: See Configuration for details.

distutils

from distutils.core import setup

import scmver

setup(version=scmver.get_version())

See Configuration for the scmver.get_version arguments.

Configuration

root

A path of the working directory.

Default: '.'

spec

A version specifier to construct the public version identifiers. It will be incremented by the number of commits from the latest tag.

major: It will increment the major version.
minor: It will increment the minor version.
micro or patch: It will increment the micro (patch) version.
post: It will increment the post-release segment.
major.dev: It will increment the development release segment after incrementing the major version by 1.
minor.dev: It will increment the development release segment after incrementing the minor version by 1.
micro.dev or patch.dev: It will increment the development release segment after incrementing the micro (patch) version by 1.

Default: 'post'

local

A string or callable object to construct the local version identifiers.

string

A format string.

Available keywords:

{distance}
{revision}
{branch}
{utc} - Return value of datetime.datetime.now(datetime.timezone.utc)
{local} - Return value of datetime.datetime.now()

callable object

It will be called with scmver.core.SCMInfo.

Default: '{local:%Y-%m-%d}'

version

A regular expression object to extract the version from SCM tags. It should contain the version group.

write_to

A path to a file which will be generated using template.

template

A format string which is used by write_to.

Available keywords:

{version}
{revision}
{branch}

fallback

It will be used when there is outside of a working copy.

string: It is in the 'package.module:some.attribute' format (ex: 'scmver:__version__').
list: It consists of a string which is described above, and a path to import the module.
callable object: It should return the version.

bazaar.tag