Package: setuptools-autover
AboutA package allowing generating PEP-440 compatible version numbers from version
control.Currently only git is supported but it is possible to add support for other
version control systems.The goal of the project is to provide reasonable defaults and an easy way to
customize how version numbers are generated from version control system.The code is currently considered stable and ready for production use. The API
should not change in such way that the change would break current usage.Usagesetup.pyAddsetuptools_autovertosetup_requiresargumentSetuse_autoverargumentThe 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',use_autover=True,setup_requires=['setuptools_autover'],)Use with custom settingsimportsetuptoolssetup(name='example-package',use_autover={'root_version':'0.0','parse_tag':lambdatag:tag.lstrip('v'),'create_version':lambdaver:'{}.post{}'.format(ver.latest_version,ver.distance),},setup_requires=['setuptools_autover'],)Note that if thesetupfunction is called for source tree not having version info available,setuptools_autover.RevisionInfoNotFoundErroris raised.From Python Codefromsetuptools_autoverimportget_version# Using default settingsversion=get_version()# Using custom settingsversion=get_version(root_version='0.0')Version Number GenerationIf setup.py is not run on code in a repository, version information is read fromPKG-INFOto
allowsdistto work.When running setup.py on code in a repository,setuptools_autover.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.ConfigurationTheuse_autoverargument can be used for configuring version generation behaviour
by proving the configuration as mapping.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 ofsetuptools_autover.RevisionInfoor None in case revision info is not available.By defaultsetuptools_autover.GitRevisionInfoReaderinstance with default arguments is used.parse_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: tagcreate_versionFunction creating version string fromsetuptools_autover.VersionInfo.The function takes one argument of typesetuptools_autover.VersionInfo.Default value:setuptools_autover.pep440.create_post_with_devConfiguration matching the default settings:{'root_version':'0','read_revision_info':setuptools_autover.GitRevisionInfoReader(),'parse_tag':lambdatag:tag,'create_version':setuptools_autover.pep440.create_post_with_dev,}APIFunctionssetuptools_autover.config_to_get_version_kwargs(config)Return kwargs dictionary forsetuptools_autover.get_versionbased on the given configuration.setuptools_autover.get_version(root_version=’0’, parse_tag=lambda tag: tag, create_version=pep440.create_post_with_dev)The arguments are the same as the configurations passed foruse_autoverargument fromsetup.pyReturn generated versionsetuptools_autover.pep440.create_post_with_devCreate 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 treeClassessetuptools_autover.GitRevisionInfoReaderRead revision info from Git repository.Constructor arguments:pathPath to repository root. IfNone, current working directory is used.Default value:NoneMembers:__call__(self)Return setuptools_autover.RevisionInfo generated from Git history ofHEAD.Exceptionssetuptools_autover.AutoverErrorBase class for exceptions thrown bysetuptools_autoversetuptools_autover.InvalidConfigErrorThe configuration dict is not valid.setuptools_autover.RevisionInfoNotFoundErrorVersion could not be generated because revision info was not foundTypessetuptools_autover.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 toTruesetuptools_autover.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.