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.

Installation

$ pip install scmver

Requirements

• Python 3.9+
• 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

A regular expression pattern to filter tags.

darcs.tag

A regular expression pattern to filter tags.

fossil.tag

A regular expression pattern to filter tags.

git.tag

It will be passed to git describe as --match.

mercurial.tag

A regular expression pattern to filter tags.

subversion.tag

A regular expression pattern to filter tags.

subversion.trunk

A relative repository path of the trunk directory.

Default: 'trunk'

subversion.branches

A relative repository path of the directory where branches are located.

Default: 'branches'

subversion.tags

A relative repository path of the directory where tags are located.

Default: 'tags'

License

scmver is distributed under the terms of the MIT License.