setuptools_scm
handles 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 SCMs.
To use setuptools_scm
just modify your project's setup.py
file like this:
- Add
setuptools_scm
to thesetup_requires
parameter. - Add the
use_scm_version
parameter and set it toTrue
.
For example:
from setuptools import setup
setup(
...,
use_scm_version=True,
setup_requires=['setuptools_scm'],
...,
)
Arguments to get_version()
(see below) may be passed as a dictionary to use_scm_version
. For example:
from setuptools import setup
setup(
...,
use_scm_version = {"root": "..", "relative_to": __file__},
setup_requires=['setuptools_scm'],
...,
)
Once configured, you can access the version number in your package via pkg_resources
(PEP-0396). For example:
from pkg_resources import get_distribution, DistributionNotFound
try:
__version__ = get_distribution(__name__).version
except DistributionNotFound:
# package is not installed
pass
You can also confirm the version number locally via setup.py
:
$ python setup.py --version
Note
If you see unusual version numbers for packages but python setup.py --version
reports the expected version number, ensure [egg_info]
is not defined in setup.cfg
.
If using setuptools 30.3.0 or greater, you can store setup_requires
configuration in setup.cfg
. However, use_scm_version
must still be placed in setup.py
. For example:
# setup.py
from setuptools import setup
setup(
use_scm_version=True,
)
# setup.cfg
[metadata]
...
[options]
setup_requires =
setuptools_scm
...
Important
Ensure neither the [metadata]
version
option nor the [egg_info]
section are defined, as these will interfere with setuptools_scm
.
You may also need to define a pyproject.toml
file (PEP-0518) to ensure you have the required version of setuptools
:
# pyproject.toml
[build-system]
requires = ["setuptools>=30.3.0", "wheel", "setuptools_scm"]
For more information, refer to the setuptools issue #1002.
In order to use setuptools_scm
from code that is one directory deeper than the project's root, you can use:
from setuptools_scm import get_version
version = get_version(root='..', relative_to=__file__)
See setup.py Usage above for how to use this within setup.py
.
It is discouraged to use setuptools_scm
from Sphinx itself, instead use pkg_resources
after editable/real installation:
# contents of docs/conf.py
from pkg_resources import get_distribution
release = get_distribution('myproject').version
# for example take major/minor
version = '.'.join(release.split('.')[:2])
The underlying reason is, that services like Read the Docs sometimes change the working directory for good reasons and using the installed metadata prevents using needless volatile data there.
- setuptools_scm_git_archive
Provides 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.
In the standard configuration setuptools_scm
takes a look at three 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}+dYYYMMMDD
- distance and not clean:
{next_version}.dev{distance}+{scm letter}{revision hash}.dYYYMMMDD
The next version is calculated by adding 1
to the last numeric component of the tag.
For Git projects, the version relies on git describe, so you will see an additional g
prepended to the {revision hash}
.
Due to the default behavior it's necessary to always include a patch version (the 3
in 1.2.3
), or else the automatic guessing will increment the wrong part of the SemVer (e.g. tag 2.0
results in 2.1.devX
instead of 2.0.1.devX
). So please make sure to tag accordingly.
Note
Future versions of setuptools_scm
will switch to SemVer by default hiding the the old behavior as an configurable option.
- the SCM itself (git/hg)
.hg_archival
files (mercurial archives)PKG-INFO
Note
Git archives are not supported due to Git shortcomings
setuptools_scm
implements a file_finders entry point which returns all files tracked by your SCM. This eliminates the need for a manually constructed MANIFEST.in
in most cases where this would be required when not using setuptools_scm
, namely:
- To ensure all relevant files are packaged when running the
sdist
command. - When using include_package_data to include package data as part of the
build
orbdist_wheel
.
MANIFEST.in
may still be used: anything defined there overrides the hook. This is mostly useful to exclude files tracked in your SCM from packages, although in principle it can be used to explicitly include non-tracked files too.
In order to configure the way use_scm_version
works you can provide a mapping with options instead of a boolean value.
The currently supported configuration keys are:
- root
Relative path to cwd, used for finding the SCM root; defaults to
.
- version_scheme
Configures how the local version number is constructed; either an entrypoint name or a callable.
- local_scheme
Configures how the local component of the version is constructed; either an entrypoint name or a callable.
- write_to
A path to a file that gets replaced with a file containing the current version. It is ideal for creating a
version.py
file within the package, typically used to avoid using pkg_resources.get_distribution (which adds some overhead).Warning
Only files with
.py
and.txt
extensions have builtin templates, for other file types it is necessary to providewrite_to_template
.- write_to_template
A newstyle format string that is given the current version as the
version
keyword argument for formatting.- relative_to
A file from which the root can be resolved. Typically called by a script or module that is not in the root of the repository to point
setuptools_scm
at the root of the repository by supplying__file__
.- tag_regex
A Python regex string to extract the version part from any SCM tag. The regex needs to contain three named groups prefix, version and suffix, where
version
captures the actual version information.Defaults to the value of
setuptools_scm.config.DEFAULT_TAG_REGEX
(see config.py).- fallback_version
A version string that will be used if no other method for detecting the version worked (e.g., when using a tarball with no metadata). If this is unset (the default), setuptools_scm will error if it fails to detect the version.
- parse
A function that will be used instead of the discovered SCM for parsing the version. Use with caution, this is a function for advanced use, and you should be familiar with the
setuptools_scm
internals to use it.- git_describe_command
This command will be used instead the default
git describe
command. Use with caution, this is a function for advanced use, and you should be familiar with thesetuptools_scm
internals to use it.Defaults to the value set by
setuptools_scm.git.DEFAULT_DESCRIBE
(see git.py).
To use setuptools_scm
in other Python code you can use the get_version
function:
from setuptools_scm import get_version
my_version = get_version()
It optionally accepts the keys of the use_scm_version
parameter as keyword arguments.
Example configuration in setup.py
format:
from setuptools import setup
setup(
use_scm_version={
'write_to': 'version.py',
'write_to_template': '__version__ = "{version}"',
'tag_regex': r'^(?P<prefix>v)?(?P<version>[^\+]+)(?P<suffix>.*)?$',
}
)
- SETUPTOOLS_SCM_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 string
- SETUPTOOLS_SCM_DEBUG
when defined and not empty, a lot of debug information will be printed as part of
setuptools_scm
operating
setuptools_scm
ships with a few setuptools
entrypoints based hooks to extend its default capabilities.
setuptools_scm
provides two entrypoints for adding new SCMs:
setuptools_scm.parse_scm
A 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
.git
and referencessetuptools_scm.git:parse
- The return value MUST be a
setuptools_scm.version.ScmVersion
instance created by the function
setuptools_scm.version:meta
.setuptools_scm.files_command
Either 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.
setuptools_scm.version_scheme
Configures how the version number is constructed given a
setuptools_scm.version.ScmVersion
instance 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 (adds
postN
)
setuptools_scm.local_scheme
Configures how the local part of a version is rendered given a
setuptools_scm.version.ScmVersion
instance 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)
- node-and-timestamp
like
node-and-date
but with a timestamp of the form{:%Y%m%d%H%M%S}
instead- dirty-tag
adds
+dirty
if the current workdir has changes
To support usage in setup.py
passing a callable into use_scm_version
is supported.
Within that callable, setuptools_scm
is available for import. The callable must return the configuration.
# content of setup.py
import setuptools
def myversion():
from setuptools_scm.version import get_local_dirty_tag
def clean_scheme(version):
return get_local_dirty_tag(version) if version.dirty else '+clean'
return {'local_scheme': clean_scheme}
setup(
...,
use_scm_version=myversion,
...
)
While the general advice is to test against a installed version, some environments require a test prior to install,
$ python setup.py egg_info
$ PYTHONPATH=$PWD:$PWD/src pytest
Everyone interacting in the setuptools_scm
project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the PyPA Code of Conduct.
To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.