setuptools_scm travis-ci python

the blessed package to manage your versions by scm tags


:code: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 scm’s.

.. image:: :target: usage

To use setuptools_scm just modify your project’s file like this:

  1. Add :code:'setuptools_scm' to the :code:setup_requires parameter
  2. Add the :code:use_scm_version parameter and set it to True


.. code:: python

   from setuptools import setup

Programmatic usage

In order to use setuptools_scm from code that one directory deeper than the project’s root, you can use:

.. code:: python

from setuptools_scm import get_version
version = get_version(root='..', relative_to=__file__)

Usage from sphinx

It is discouraged to use setuptools_scm from sphinx itself, instead use pkg_resources after editable/real installation:

.. code:: python

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 readthedocs sometimes change the workingdirectory for good reasons and using the installed metadata prevents using needless volatile data there.

Notable Plugins

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.

Default versioning scheme

In the standard configuration setuptools_scm takes a look at 3 things:

  1. latest tag (with a version number)
  2. the distance to this tag (e.g. number of revisions since latest tag)
  3. workdir state (e.g. uncommitted changes since latest tag)
and uses roughly the following logic to render the version:
:code:no distance and clean: :code:{tag} :code:distance and clean: :code:{next_version}.dev{distance}+n{revision hash} :code:no distance and not clean: :code:{tag}+dYYYMMMDD :code:distance and not clean: :code:{next_version}.dev{distance}+n{revision hash}.dYYYMMMDD

The next version is calculated by adding 1 to the last numeric component of the tag.

Semantic Versioning (SemVer) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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.

Builtin mechanisms for obtaining version numbers

  1. the scm itself (git/hg)
  2. :code:.hg_archival files (mercurial archives)

.. note::

git archives are not supported due to git shortcomings

Configuration Parameters

In order to configure the way use_scm_version works 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 :code:.
either an entrypoint name or a callable
either an entrypoint name or a callable
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: declares a text file or python file which is replaced with a file containing the current version. its ideal or creating a file within the package

.. warning::

  only :code:`*.py` and :code:`*.txt` have builtin templates,
  for other extensions it is necessary
  to provide a :code:`write_to_template`
the :code:version keyword argument for formatting
the :code:version keyword argument for formatting
d argument for formatting
root of the repository by supplying __file__.
root of the repository by supplying __file__.
root of the repository by supplying __file__.
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_scm internals to use it

To use setuptools_scm in other Python code you can use the get_version function:

.. code:: python

from setuptools_scm import get_version
my_version = get_version()

It optionally accepts the keys of the use_scm_version parameter as keyword arguments.

Environment Variables

: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

Extending setuptools_scm

setuptools_scm ships with a few setuptools entrypoints based hooks to extend its default capabilities.

Adding a new SCM ~~~~~~~~~~~~~~~~

setuptools_scm provides 2 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 :code:.git and references :code:'setuptools_scm.git:parse'.

The return value MUST be a :code:`setuptools.version.ScmVersion` instance
created by the function :code:`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.

Version number construction ~~~~~~~~~~~~~~~~~~~~~~~~~~~

setuptools_scm.version_scheme Configures how the version number is constructed given a :code:setuptools.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 :code:`postN`)

setuptools_scm.local_scheme Configures how the local part of a version is rendered given a :code:setuptools.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)
:dirty-tag: adds :code:`+dirty` if the current workdir has changes

Importing in ~~~~~~~~~~~~~~~~~~~~~

To support usage in passing a callable into use_scm_version is supported.

Within that callable, setuptools_scm is available for import. The callable must return the configuration.

.. code:: python

def myversion():
    from setuptools_scm.version import dirty_tag
    def clean_scheme(version):
        return dirty_tag(version) if version.dirty else '+clean'

    return {'local_scheme': clean_scheme}

Code of Conduct

Everyone interacting in the setuptoolsscm project’s codebases, issue trackers, chat rooms, and mailing lists is expected to follow the PyPA Code of Conduct.

.. _PyPA Code of Conduct:

Related Repositories



the blessed package to manage your versions by scm tags ...

Top Contributors

RonnyPfannschmidt jaraco userzimmermann untitaker te-je mindw majuscule mcmtroffaes brianmay esben HolgerPeters peacetara agronholm anarcat davidszotten dstufft felixonmars ionelmc jezdez mihaic petrem reece mineo cclauss


-   v1.15.0rc1 zip tar
-   v1.14.0 zip tar
-   v1.14.0rc1 zip tar
-   v1.13.1 zip tar
-   v1.13.0 zip tar
-   v1.12.0 zip tar
-   v1.11.1 zip tar
-   v1.11.0 zip tar
-   v1.10.1 zip tar
-   v1.10.0 zip tar
-   v1.9.0 zip tar
-   v1.8.0 zip tar
-   v1.7.0 zip tar
-   v1.6.0 zip tar
- zip tar
-   v1.5.5 zip tar
-   v1.5.4 zip tar
-   v1.5.3 zip tar
-   v1.5.2 zip tar
-   v1.5.1 zip tar
-   v1.5.0 zip tar
-   v1.4.1 zip tar
-   v1.4.0 zip tar
-   v1.3.0 zip tar
-   v1.2.0 zip tar
-   v1.1.0 zip tar
-   v1.0.0 zip tar
-   v0.26 zip tar
-   v0.25 zip tar
-   v0.24 zip tar