Package: setuptools_sky
setuptools_skyhandles managing your python package versions
in scm metadata instead of declaring them as the version argument
or in a scm managed file.It also handles file finders for the supported scm’s.Setup.py usageTo use setuptools_sky just modify your project’s setup.py file like this:Add'setuptools_sky'to thesetup_requiresparameterAdd theuse_scm_versionparameter and set it toTrueE.g.:fromsetuptoolsimportsetupsetup(...,use_scm_version=True,setup_requires=['setuptools_sky'],...,)Arguments toget_version()(see below) may be passed as a
dictionary touse_scm_version. For example:fromsetuptoolsimportsetupsetup(...,use_scm_version={"root":"..","relative_to":__file__},setup_requires=['setuptools_sky'],...,)Access the version number in your package viapkg_resourcesE.g. (PEP-0396):frompkg_resourcesimportget_distribution,DistributionNotFoundtry:__version__=get_distribution(__name__).versionexceptDistributionNotFound:# package is not installedpassProgrammatic usageIn order to usesetuptools_skyfrom code that is one directory deeper
than the project’s root, you can use:fromsetuptools_skyimportget_versionversion=get_version(root='..',relative_to=__file__)Seesetup.py Usageabove for how to use this within setup.py.Usage from sphinxIt is discouraged to use setuptools_sky from sphinx itself,
instead usepkg_resourcesafter editable/real installation:frompkg_resourcesimportget_distributionrelease=get_distribution('myproject').version# for example take major/minorversion='.'.join(release.split('.')[:2])The underlying reason is, that services like readthedocs sometimes change
the workingdirectory for good reasons and using the installed metadata prevents
using needless volatile data there.Notable Pluginssetuptools_sky_git_archiveprovides partial support for obtaining versions from git archives
that belong to tagged versions. The only reason for not including
it in setuptools-scm itself is git/github not supporting
sufficient metadata for untagged/followup commits,
which is preventing a consistent UX.Default versioning schemeIn the standard configuration setuptools_sky takes a look at 3 things:latest tag (with a version number)the distance to this tag (e.g. number of revisions since latest tag)workdir state (e.g. uncommitted changes since latest tag)and uses roughly the following logic to render the version:no distance and clean:{tag}distance and clean:{next_version}.dev{distance}+{scm letter}{revision hash}no distance and not clean:{tag}+dYYYMMMDDdistance and not clean:{next_version}.dev{distance}+{scm letter}{revision hash}.dYYYMMMDDThe next version is calculated by adding1to the last numeric component
of the tag.For git projects, the version relies ongit describe,
so you will see an additionalgprepended to the{revision hash}.Semantic Versioning (SemVer)Due to the default behavior it’s necessary to always include a
patch version (the3in1.2.3), or else the automatic guessing
will increment the wrong part of the semver (e.g. tag2.0results in2.1.devXinstead of2.0.1.devX). So please make sure to tag
accordingly.NoteFuture versions of setuptools_sky will switch toSemVerby default hiding the the old behavior
as an configurable option.Builtin mechanisms for obtaining version numbersthe scm itself (git/hg).hg_archivalfiles (mercurial archives)PKG-INFONotegit archives are not supported due to git shortcomingsConfiguration ParametersIn order to configure the wayuse_scm_versionworks you can provide
a mapping with options instead of simple boolean value.The Currently supported configuration keys are:root:cwd relative path to use for finding the scm root, defaults to.version_scheme:configures how the local version number is constructed.
either an entrypoint name or a callablelocal_scheme:configures how the local component of the version is constructed
either an entrypoint name or a callablewrite_to:declares a text file or python file which is replaced with a file
containing the current version.
its ideal or creating a version.py file within the packageWarningonly*.pyand*.txthave builtin templates,
for other extensions it is necessary
to provide awrite_to_templatewrite_to_template:a newstyle format string thats given the current version as
theversionkeyword argument for formattingrelative_to:a file from which root may be resolved. typically called by a
script or module that is not
in the root of the repository to direct setuptools_sky to the
root of the repository by supplying__file__.parse:a function that will be used instead of the discovered scm for parsing the version,
use with caution, this is a expert function and you should be closely familiar
with the setuptools_sky internals to use itTo use setuptools_sky in other Python code you can use theget_versionfunction:fromsetuptools_skyimportget_versionmy_version=get_version()It optionally accepts the keys of theuse_scm_versionparameter as
keyword arguments.Environment Variablessetuptools_sky_PRETEND_VERSION:when defined and not empty,
its used as the primary source for the version number
in which case it will be a unparsed stringExtending setuptools_skysetuptools_sky ships with a few setuptools entrypoints based hooks to extend
its default capabilities.Adding a new SCMsetuptools_sky provides 2 entrypoints for adding new SCMssetuptools_sky.parse_scmA function used to parse the metadata of the current workdir
using the name of the control directory/file of your SCM as the
entrypoint’s name. E.g. for the built-in entrypoint for git the
entrypoint is named.gitand references'setuptools_sky.git:parse'.The return value MUST be asetuptools.version.ScmVersioninstance
created by the functionsetuptools_sky.version:meta.setuptools_sky.files_commandEither a string containing a shell command that prints all SCM managed
files in its current working directory or a callable, that given a
pathname will return that list.Also use then name of your SCM control directory as name of the entrypoint.Version number constructionsetuptools_sky.version_schemeConfigures how the version number is constructed given asetuptools.version.ScmVersioninstance and should return a string
representing the version.Available implementations:guess-next-dev:automatically guesses the next development version (default)post-release:generates post release versions (addspostN)setuptools_sky.local_schemeConfigures how the local part of a version is rendered given asetuptools.version.ScmVersioninstance and should return a string
representing the local version.Available implementations:node-and-date:adds the node on dev versions and the date on dirty
workdir (default)dirty-tag:adds+dirtyif the current workdir has changesImporting in setup.pyTo support usage insetup.pypassing a callable into use_scm_version
is supported.Within that callable, setuptools_sky is available for import.
The callable must return the configuration.defmyversion():fromsetuptools_sky.versionimportdirty_tagdefclean_scheme(version):returndirty_tag(version)ifversion.dirtyelse'+clean'return{'local_scheme':clean_scheme}Code of ConductEveryone interacting in the setuptools_sky project’s codebases, issue trackers,
chat rooms, and mailing lists is expected to follow thePyPA Code of Conduct.