vcsver 0.2

Setuptools without pyproject.toml

Note that this method is deprecated and will be removed in the future releases.

1. Add vcsver to setup_requires

2. Set vcsver argument

   The value can be mapping, (a dict, for example) containing configuration or any Python value that evaluates as True.

Use with default settings

import setuptools

setup(
    name='example-package',
    vcsver=True,
    setup_requires=['vcsver'],
)

Use with custom settings

import setuptools

setup(
    name='example-package',
    vcsver={
      'root_version': '0.0',
      'parse_tag': lambda tag: tag.lstrip('v'),
      'create_version': lambda ver: '{}.post{}'.format(ver.latest_version, ver.distance),
    },
    setup_requires=['vcsver'],
)

Note that if the setup function is called for source tree not having version info available, vcsver.RevisionInfoNotFoundError is raised.

{
    'root_version': '0',
    'read_revision_info': vcsver.GitRevisionInfoReader(),
    'parse_tag': lambda tag: tag,
    'create_version': vcsver.pep440.post,
}

{
    'root_version': '0',
    'read_revision_info': 'git',
    'parse_tag': 'plain',
    'create_version': 'pep440.post',
}

Functions

def get_version(
    root_version: str = '0',
    read_revision_info: types.RevisionInfoReader = git.GitRevisionInfoReader(),
    parse_tag: types.TagParser = lambda tag: tag,
    create_version: types.VersionStringFactory = pep440.post,
) -> str:

Get version using read_revision_info or from Python’s PKG-INFO file (to support building Python sdists).

Arguments

• root_version: Version string used as root version if no releases are found from VCS

• read_revision_info: Callable that return RevisionInfo object based on VCS

• parse_tag: Callable returning version string from tag found from VCS

• create_version: Callable returning version string based on VersionInfo

If read_revision_info returns None, the distance part of RevisionInfo is assumed to contain the amount of commit since start of history. In this case the value of root_version is used as value for VersionInfo.latest_release , i.e. parse_tag is not used for mapping the latest tag into version string.

def post(
    version_info: types.VersionInfo,
) -> str:

Create version that uses post part for version between releases.

The version is created using the following rules:

• distance == 0 and not dirty ⇒ {latest_version}

  Released version

• distance == 0 and dirty ⇒ {latest_version+dirty}

  Released version with modified source tree

• distance > 0 and not dirty ⇒ {latest_version}.post{distance}+{commit}

  Released version

• distance > 0 and dirty ⇒ {latest_version+dirty}.post{distance}+{commit}-dirty

  Released version with modified source tree

def post_with_dev(
    version_info: types.VersionInfo,
) -> str:

Create version that uses post and dev parts for version between releases.

The version is created using the following rules:

• distance == 0 and not dirty ⇒ {latest_version}

  Released version

• distance == 0 and dirty ⇒ {latest_version+dirty}

  Released version with modified source tree

• distance > 0 and not dirty ⇒ {latest_version}.post0.dev{distance}+{commit}

  Released version

• distance > 0 and dirty ⇒ {latest_version+dirty}.post0.dev{distance}+{commit}-dirty

  Released version with modified source tree

Classes

vcsver.GitRevisionInfoReader

Read revision info from Git repository.

Constructor arguments:

path

Path to repository root. If None, current working directory is used.

Default value: None

Members:

__call__(self)

Return vcsver.RevisionInfo generated from Git history of HEAD.

Exceptions

vcsver.VcsverError

Base class for exceptions thrown by vcsver

vcsver.InvalidConfigurationError

The configuration is invalid

vcsver.RevisionInfoNotFoundError

Version could not be generated because revision info was not found

Types

vcsver.RevisionInfo

Named tuple containing revision info:

• latest_tag: The most recent tag (None if there is no tags before the current revision)

• distance: Number of commits since the most recent tag (0 if current revision is tagged)

• commit: Commit identifier for current revision

• dirty: Is the source tree dirty (not exactly the same as the code in the current revision). If there is no commits, the lastest_tag and commit should be None and dirty should be set to True

vcsver.VersionInfo

Named tuple containing version info:

• latest_version: The most recent version (None if there is no released version before the current revision)

• distance: Number of commits since the most recent tag (0 if current revision is tagged)

• commit: Commit identifier for current revision

• dirty: Is the source tree dirty (not exactly the same as the code in the current revision)

RevisionInfo is information returned by VCS readers and is turned into VersionInfo using the parse_tag function.

RevisionInfoReader

typing.Callable[
    [],
    typing.Optional[RevisionInfo],
]

RevisionInfoReaderFactory

typing.Callable[
    [],
    RevisionInfoReader,
]

TagParser

typing.Callable[
    [str],
    str,
]

VersionStringFactory

typing.Callable[
    [VersionInfo],
    str,
]