the blessed package to manage your versions by scm tags
Project description
About
setuptools_scm is a simple utility for the setup_requires
feature of setuptools for use in Mercurial
and Git based projects.
It uses metadata from the SCM to generate the version of a project
and is able to list the files belonging to that project
(which makes the MANIFEST.in file unnecessary in many cases).
It falls back to PKG-INFO/.hg_archival.txt when necessary.
Default behavior
In the standard configuration setuptools_scm 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}+n{revision hash}- no distance and not clean:
{tag}+dYYYMMMDD- distance and not clean:
{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.
Setup.py usage
To use setuptools_scm simple modify your project’s setup.py file like this:
Add the
use_scm_versionparameter and set it to TrueAdd
'setuptools_scm'to thesetup_requiresparameterE.g.:
from setuptools import setup setup( ..., use_scm_version=True, setup_requires=['setuptools_scm'], ..., )
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:
- 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
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.
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
.gitand references'setuptools_scm.git:parse'.The return value MUST be a
setuptools.version.ScmVersioninstance created by the functionsetuptools_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
setuptools.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 (adds
postN)
- setuptools_scm.local_scheme
Configures how the local part of a version is rendered given a
setuptools.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 changes
Importing in setup.py
To support usage in setup.py passing a callable into use_scm_version
is supported.
Within that callable, setuptools_scm is availiable for import. The callable must return the configuration.
def myversion():
from setuptools_scm.version import dirty_tag
def clean_scheme(version):
if not version.dirty:
return '+clean'
else:
return dirty_tag(version)
return {'local_scheme': clean_scheme}Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for setuptools_scm-1.1.0-py2.py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | f6525d17c104a794fc20c2a0639d620a4075f87326ded38fa06d34a90ace8f72 |
|
| MD5 | 23aac620812841c765113c339eff08b6 |
|
| BLAKE2b-256 | f2d05b01f9c07439d364761a47451e700126dfdb6c07debb3899b14222ed8153 |
