Package: vcsver
OverviewAutomate your project’s version numbering; just create annotated tag in Git and
always have correct version number with your built packages. You don’t need to
spend time updating version numbers in source code anymore, just tag and you are
good to go. And you are always able to go back to the commit from which a package
has been built.Currently only Git and PEP-440 compatible version numbers with setuptools are
supported but the design allows adding other version control systems and other
versioning schemes.UsageTo enable automatic version in PEP 517 compatible way, configure source for versions
intool.vcsvertable inpyproject.toml:[tool.vcsver]source="git"Setuptools without pyproject.tomlNote that this method is deprecated and will be removed in the future releases.Addvcsvertosetup_requiresSetvcsverargumentThe value can be mapping, (a dict, for example) containing configuration or
any Python value that evaluates as True.Use with default settingsimportsetuptoolssetup(name='example-package',vcsver=True,setup_requires=['vcsver'],)Use with custom settingsimportsetuptoolssetup(name='example-package',vcsver={'root_version':'0.0','parse_tag':lambdatag:tag.lstrip('v'),'create_version':lambdaver:'{}.post{}'.format(ver.latest_version,ver.distance),},setup_requires=['vcsver'],)Note that if thesetupfunction is called for source tree not having version info available,vcsver.RevisionInfoNotFoundErroris raised.ConfigurationThevcsverargument can be used for configuring version generation behaviour
by proving the configuration as mapping.The items in the mapping can either be actual Python objects or identifiers (strings)
that are mapped to actual values.root_versionIf repository does not contain any tags, this string is used.Default value:'0'read_revision_infoCallable used for reading revision information from VCS (or other source).The function should not take any arguments and should return instance ofvcsver.RevisionInfoor None in case revision info is not available.Default value:vcsver.GitRevisionInfoReader()Available identifiers:gitUsevcsvver.GitRevisionInfoReaderinstance with default argumentsparse_tagFunction parsing version string from a tag.The function takes one string argument (the tag) and returns version extracted from
the tag as stringDefault value:lambda tag: tagAvailable identifiers:plainUse the tag as it is in the version control systemcreate_versionFunction creating version string fromvcsver.VersionInfo.The function takes one argument of typevcsver.VersionInfo.Default value:vcsver.pep440.postAvailable identifiers:pep440.postPEP 440 string using postNpep440.post_with_devPEP 440 string using post0+devNConfiguration matching the default settings:{'root_version':'0','read_revision_info':vcsver.GitRevisionInfoReader(),'parse_tag':lambdatag:tag,'create_version':vcsver.pep440.post,}The same configuration can also be defined without importingvcsver:{'root_version':'0','read_revision_info':'git','parse_tag':'plain','create_version':'pep440.post',}Version Number GenerationWhen building package from code in a repository,vcsver.RevisionInfoobject is filled
based on current revision.If latest tag is available, latest release version is read from it by usingparse_tagfunction. Otherwiseroot_versionis used as latest version and distance is the number
of commits since the start of the commit history.The version string is generated based on the above info using thecreate_versionfunction.If package is being built from extractedsdist, version information is read fromPKG-INFO.APIFunctionsdefget_version(root_version:str='0',read_revision_info:types.RevisionInfoReader=git.GitRevisionInfoReader(),parse_tag:types.TagParser=lambdatag:tag,create_version:types.VersionStringFactory=pep440.post,)->str:Get version usingread_revision_infoor from Python’s PKG-INFO file (to support building
Python sdists).Argumentsroot_version: Version string used as root version if no releases are found from VCSread_revision_info: Callable that returnRevisionInfoobject based on VCSparse_tag: Callable returning version string from tag found from VCScreate_version: Callable returning version string based onVersionInfoIfread_revision_inforeturnsNone, thedistancepart ofRevisionInfois
assumed to contain the amount of commit since start of history. In this case the value ofroot_versionis used as value forVersionInfo.latest_release, i.e.parse_tagis not used for mapping the latest tag into version string.defpost(version_info:types.VersionInfo,)->str:Create version that usespostpart for version between releases.The version is created using the following rules:distance == 0 and not dirty⇒{latest_version}Released versiondistance == 0 and dirty⇒{latest_version+dirty}Released version with modified source treedistance > 0 and not dirty⇒{latest_version}.post{distance}+{commit}Released versiondistance > 0 and dirty⇒{latest_version+dirty}.post{distance}+{commit}-dirtyReleased version with modified source treedefpost_with_dev(version_info:types.VersionInfo,)->str:Create version that usespostanddevparts for version between releases.The version is created using the following rules:distance == 0 and not dirty⇒{latest_version}Released versiondistance == 0 and dirty⇒{latest_version+dirty}Released version with modified source treedistance > 0 and not dirty⇒{latest_version}.post0.dev{distance}+{commit}Released versiondistance > 0 and dirty⇒{latest_version+dirty}.post0.dev{distance}+{commit}-dirtyReleased version with modified source treeClassesvcsver.GitRevisionInfoReaderRead revision info from Git repository.Constructor arguments:pathPath to repository root. IfNone, current working directory is used.Default value:NoneMembers:__call__(self)Return vcsver.RevisionInfo generated from Git history ofHEAD.Exceptionsvcsver.VcsverErrorBase class for exceptions thrown byvcsvervcsver.InvalidConfigurationErrorThe configuration is invalidvcsver.RevisionInfoNotFoundErrorVersion could not be generated because revision info was not foundTypesvcsver.RevisionInfoNamed 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 revisiondirty: Is the source tree dirty (not exactly the same as the code in the current revision).
If there is no commits, thelastest_tagandcommitshould beNoneand dirty should be
set toTruevcsver.VersionInfoNamed 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 revisiondirty: Is the source tree dirty (not exactly the same as the code in the current revision)RevisionInfois information returned by VCS readers and is turned intoVersionInfousing theparse_tagfunction.RevisionInfoReadertyping.Callable[[],typing.Optional[RevisionInfo],]RevisionInfoReaderFactorytyping.Callable[[],RevisionInfoReader,]TagParsertyping.Callable[[str],str,]VersionStringFactorytyping.Callable[[VersionInfo],str,]