4 """The Versioneer - like a rocketeer, but for versions.
9 * like a rocketeer, but for versions!
10 * https://github.com/warner/python-versioneer
12 * License: Public Domain
13 * Compatible With: python2.6, 2.7, 3.2, 3.3, 3.4, 3.5, 3.6, and pypy
15 (https://pypip.in/version/versioneer/badge.svg?style=flat)
16 ](https://pypi.python.org/pypi/versioneer/)
18 (https://travis-ci.org/warner/python-versioneer.png?branch=master)
19 ](https://travis-ci.org/warner/python-versioneer)
21 This is a tool for managing a recorded version number in distutils-based
22 python projects. The goal is to remove the tedious and error-prone "update
23 the embedded version string" step from your release process. Making a new
24 release should be as easy as recording a new tag in your version-control
25 system, and maybe making new tarballs.
30 * `pip install versioneer` to somewhere to your $PATH
31 * add a `[versioneer]` section to your setup.cfg (see below)
32 * run `versioneer install` in your source tree, commit the results
34 ## Version Identifiers
36 Source trees come from a variety of places:
38 * a version-control system checkout (mostly used by developers)
39 * a nightly tarball, produced by build automation
40 * a snapshot tarball, produced by a web-based VCS browser, like github's
41 "tarball from tag" feature
42 * a release tarball, produced by "setup.py sdist", distributed through PyPI
44 Within each source tree, the version identifier (either a string or a number,
45 this tool is format-agnostic) can come from a variety of places:
47 * ask the VCS tool itself, e.g. "git describe" (for checkouts), which knows
48 about recent "tags" and an absolute revision-id
49 * the name of the directory into which the tarball was unpacked
50 * an expanded VCS keyword ($Id$, etc)
51 * a `_version.py` created by some earlier build step
53 For released software, the version identifier is closely related to a VCS
54 tag. Some projects use tag names that include more than just the version
55 string (e.g. "myproject-1.2" instead of just "1.2"), in which case the tool
56 needs to strip the tag prefix to extract the version identifier. For
57 unreleased software (between tags), the version identifier should provide
58 enough information to help developers recreate the same tree, while also
59 giving them an idea of roughly how old the tree is (after version 1.2, before
60 version 1.3). Many VCS systems can report a description that captures this,
61 for example `git describe --tags --dirty --always` reports things like
62 "0.7-1-g574ab98-dirty" to indicate that the checkout is one revision past the
63 0.7 tag, has a unique revision id of "574ab98", and is "dirty" (it has
66 The version identifier is used for multiple purposes:
68 * to allow the module to self-identify its version: `myproject.__version__`
69 * to choose a name and prefix for a 'setup.py sdist' tarball
71 ## Theory of Operation
73 Versioneer works by adding a special `_version.py` file into your source
74 tree, where your `__init__.py` can import it. This `_version.py` knows how to
75 dynamically ask the VCS tool for version information at import time.
77 `_version.py` also contains `$Revision$` markers, and the installation
78 process marks `_version.py` to have this marker rewritten with a tag name
79 during the `git archive` command. As a result, generated tarballs will
80 contain enough information to get the proper version.
82 To allow `setup.py` to compute a version too, a `versioneer.py` is added to
83 the top level of your source tree, next to `setup.py` and the `setup.cfg`
84 that configures it. This overrides several distutils/setuptools commands to
85 compute the version when invoked, and changes `setup.py build` and `setup.py
86 sdist` to replace `_version.py` with a small static file that contains just
87 the generated version data.
91 See [INSTALL.md](./INSTALL.md) for detailed installation instructions.
93 ## Version-String Flavors
95 Code which uses Versioneer can learn about its version string at runtime by
96 importing `_version` from your main `__init__.py` file and running the
97 `get_versions()` function. From the "outside" (e.g. in `setup.py`), you can
98 import the top-level `versioneer.py` and run `get_versions()`.
100 Both functions return a dictionary with different flavors of version
103 * `['version']`: A condensed version string, rendered using the selected
104 style. This is the most commonly used value for the project's version
105 string. The default "pep440" style yields strings like `0.11`,
106 `0.11+2.g1076c97`, or `0.11+2.g1076c97.dirty`. See the "Styles" section
107 below for alternative styles.
109 * `['full-revisionid']`: detailed revision identifier. For Git, this is the
110 full SHA1 commit id, e.g. "1076c978a8d3cfc70f408fe5974aa6c092c949ac".
112 * `['date']`: Date and time of the latest `HEAD` commit. For Git, it is the
113 commit date in ISO 8601 format. This will be None if the date is not
116 * `['dirty']`: a boolean, True if the tree has uncommitted changes. Note that
117 this is only accurate if run in a VCS checkout, otherwise it is likely to
120 * `['error']`: if the version string could not be computed, this will be set
121 to a string describing the problem, otherwise it will be None. It may be
122 useful to throw an exception in setup.py if this is set, to avoid e.g.
123 creating tarballs with a version string of "unknown".
125 Some variants are more useful than others. Including `full-revisionid` in a
126 bug report should allow developers to reconstruct the exact code being tested
127 (or indicate the presence of local changes that should be shared with the
128 developers). `version` is suitable for display in an "about" box or a CLI
129 `--version` output: it can be easily compared against release notes and lists
130 of bugs fixed in various releases.
132 The installer adds the following text to your `__init__.py` to place a basic
133 version in `YOURPROJECT.__version__`:
135 from ._version import get_versions
136 __version__ = get_versions()['version']
141 The setup.cfg `style=` configuration controls how the VCS information is
142 rendered into a version string.
144 The default style, "pep440", produces a PEP440-compliant string, equal to the
145 un-prefixed tag name for actual releases, and containing an additional "local
146 version" section with more detail for in-between builds. For Git, this is
147 TAG[+DISTANCE.gHEX[.dirty]] , using information from `git describe --tags
148 --dirty --always`. For example "0.11+2.g1076c97.dirty" indicates that the
149 tree is like the "1076c97" commit but has uncommitted changes (".dirty"), and
150 that this commit is two revisions ("+2") beyond the "0.11" tag. For released
151 software (exactly equal to a known tag), the identifier will only contain the
152 stripped tag, e.g. "0.11".
154 Other styles are available. See [details.md](details.md) in the Versioneer
155 source tree for descriptions.
159 Versioneer tries to avoid fatal errors: if something goes wrong, it will tend
160 to return a version of "0+unknown". To investigate the problem, run `setup.py
161 version`, which will run the version-lookup code in a verbose mode, and will
162 display the full contents of `get_versions()` (including the `error` string,
163 which may help identify what went wrong).
167 Some situations are known to cause problems for Versioneer. This details the
168 most significant ones. More can be found on Github
169 [issues page](https://github.com/warner/python-versioneer/issues).
173 Versioneer has limited support for source trees in which `setup.py` is not in
174 the root directory (e.g. `setup.py` and `.git/` are *not* siblings). The are
175 two common reasons why `setup.py` might not be in the root:
177 * Source trees which contain multiple subprojects, such as
178 [Buildbot](https://github.com/buildbot/buildbot), which contains both
179 "master" and "slave" subprojects, each with their own `setup.py`,
180 `setup.cfg`, and `tox.ini`. Projects like these produce multiple PyPI
181 distributions (and upload multiple independently-installable tarballs).
182 * Source trees whose main purpose is to contain a C library, but which also
183 provide bindings to Python (and perhaps other langauges) in subdirectories.
185 Versioneer will look for `.git` in parent directories, and most operations
186 should get the right version string. However `pip` and `setuptools` have bugs
187 and implementation details which frequently cause `pip install .` from a
188 subproject directory to fail to find a correct version string (so it usually
189 defaults to `0+unknown`).
191 `pip install --editable .` should work correctly. `setup.py install` might
194 Pip-8.1.1 is known to have this problem, but hopefully it will get fixed in
197 [Bug #38](https://github.com/warner/python-versioneer/issues/38) is tracking
198 this issue. The discussion in
199 [PR #61](https://github.com/warner/python-versioneer/pull/61) describes the
200 issue from the Versioneer side in more detail.
201 [pip PR#3176](https://github.com/pypa/pip/pull/3176) and
202 [pip PR#3615](https://github.com/pypa/pip/pull/3615) contain work to improve
203 pip to let Versioneer work correctly.
205 Versioneer-0.16 and earlier only looked for a `.git` directory next to the
206 `setup.cfg`, so subprojects were completely unsupported with those releases.
208 ### Editable installs with setuptools <= 18.5
210 `setup.py develop` and `pip install --editable .` allow you to install a
211 project into a virtualenv once, then continue editing the source code (and
212 test) without re-installing after every change.
214 "Entry-point scripts" (`setup(entry_points={"console_scripts": ..})`) are a
215 convenient way to specify executable scripts that should be installed along
216 with the python package.
218 These both work as expected when using modern setuptools. When using
219 setuptools-18.5 or earlier, however, certain operations will cause
220 `pkg_resources.DistributionNotFound` errors when running the entrypoint
221 script, which must be resolved by re-installing the package. This happens
222 when the install happens with one version, then the egg_info data is
223 regenerated while a different version is checked out. Many setup.py commands
224 cause egg_info to be rebuilt (including `sdist`, `wheel`, and installing into
225 a different virtualenv), so this can be surprising.
227 [Bug #83](https://github.com/warner/python-versioneer/issues/83) describes
228 this one, but upgrading to a newer version of setuptools should probably
231 ### Unicode version strings
233 While Versioneer works (and is continually tested) with both Python 2 and
234 Python 3, it is not entirely consistent with bytes-vs-unicode distinctions.
235 Newer releases probably generate unicode version strings on py2. It's not
236 clear that this is wrong, but it may be surprising for applications when then
237 write these strings to a network connection or include them in bytes-oriented
238 APIs like cryptographic checksums.
240 [Bug #71](https://github.com/warner/python-versioneer/issues/71) investigates
244 ## Updating Versioneer
246 To upgrade your project to a new release of Versioneer, do the following:
248 * install the new Versioneer (`pip install -U versioneer` or equivalent)
249 * edit `setup.cfg`, if necessary, to include any new configuration settings
250 indicated by the release notes. See [UPGRADING](./UPGRADING.md) for details.
251 * re-run `versioneer install` in your source tree, to replace
253 * commit any changed files
257 This tool is designed to make it easily extended to other version-control
258 systems: all VCS-specific components are in separate directories like
259 src/git/ . The top-level `versioneer.py` script is assembled from these
260 components by running make-versioneer.py . In the future, make-versioneer.py
261 will take a VCS name as an argument, and will construct a version of
262 `versioneer.py` that is specific to the given VCS. It might also take the
263 configuration arguments that are currently provided manually during
264 installation by editing setup.py . Alternatively, it might go the other
265 direction and include code from all supported VCS systems, reducing the
266 number of intermediate scripts.
271 To make Versioneer easier to embed, all its code is dedicated to the public
272 domain. The `_version.py` that it creates is also in the public domain.
273 Specifically, both are released under the Creative Commons "Public Domain
274 Dedication" license (CC0-1.0), as described in
275 https://creativecommons.org/publicdomain/zero/1.0/ .
279 from __future__
import print_function
283 import ConfigParser
as configparser
292 class VersioneerConfig
:
293 """Container for Versioneer configuration parameters."""
297 """Get the project root directory.
299 We require that all commands are run from the project root, i.e. the
300 directory that contains setup.py, setup.cfg, and versioneer.py .
302 root
= os
.path
.realpath(os
.path
.abspath(os
.getcwd()))
303 setup_py
= os
.path
.join(root
, "setup.py")
304 versioneer_py
= os
.path
.join(root
, "versioneer.py")
305 if not (os
.path
.exists(setup_py
) or os
.path
.exists(versioneer_py
)):
306 # allow 'python path/to/setup.py COMMAND'
307 root
= os
.path
.dirname(os
.path
.realpath(os
.path
.abspath(sys
.argv
[0])))
308 setup_py
= os
.path
.join(root
, "setup.py")
309 versioneer_py
= os
.path
.join(root
, "versioneer.py")
310 if not (os
.path
.exists(setup_py
) or os
.path
.exists(versioneer_py
)):
311 err
= ("Versioneer was unable to run the project root directory. "
312 "Versioneer requires setup.py to be executed from "
313 "its immediate directory (like 'python setup.py COMMAND'), "
314 "or in a way that lets it use sys.argv[0] to find the root "
315 "(like 'python path/to/setup.py COMMAND').")
316 raise VersioneerBadRootError(err
)
318 # Certain runtime workflows (setup.py install/develop in a setuptools
319 # tree) execute all dependencies in a single python process, so
320 # "versioneer" may be imported multiple times, and python's shared
321 # module-import table will cache the first one. So we can't use
322 # os.path.dirname(__file__), as that will find whichever
323 # versioneer.py was first imported, even in later projects.
324 me
= os
.path
.realpath(os
.path
.abspath(__file__
))
325 me_dir
= os
.path
.normcase(os
.path
.splitext(me
)[0])
326 vsr_dir
= os
.path
.normcase(os
.path
.splitext(versioneer_py
)[0])
327 if me_dir
!= vsr_dir
:
328 print("Warning: build in %s is using versioneer.py from %s"
329 % (os
.path
.dirname(me
), versioneer_py
))
335 def get_config_from_root(root
):
336 """Read the project setup.cfg file to determine Versioneer config."""
337 # This might raise EnvironmentError (if setup.cfg is missing), or
338 # configparser.NoSectionError (if it lacks a [versioneer] section), or
339 # configparser.NoOptionError (if it lacks "VCS="). See the docstring at
340 # the top of versioneer.py for instructions on writing your setup.cfg .
341 setup_cfg
= os
.path
.join(root
, "setup.cfg")
342 parser
= configparser
.SafeConfigParser()
343 with
open(setup_cfg
, "r") as f
:
345 VCS
= parser
.get("versioneer", "VCS") # mandatory
347 def get(parser
, name
):
348 if parser
.has_option("versioneer", name
):
349 return parser
.get("versioneer", name
)
351 cfg
= VersioneerConfig()
353 cfg
.style
= get(parser
, "style") or ""
354 cfg
.versionfile_source
= get(parser
, "versionfile_source")
355 cfg
.versionfile_build
= get(parser
, "versionfile_build")
356 cfg
.tag_prefix
= get(parser
, "tag_prefix")
357 if cfg
.tag_prefix
in ("''", '""'):
359 cfg
.parentdir_prefix
= get(parser
, "parentdir_prefix")
360 cfg
.verbose
= get(parser
, "verbose")
364 class NotThisMethod(Exception):
365 """Exception raised if a method is not valid for the current scenario."""
368 # these dictionaries contain VCS-specific tools
373 def register_vcs_handler(vcs
, method
): # decorator
374 """Decorator to mark a method as the handler for a particular VCS."""
376 """Store f in HANDLERS[vcs][method]."""
377 if vcs
not in HANDLERS
:
379 HANDLERS
[vcs
][method
] = f
384 def run_command(commands
, args
, cwd
=None, verbose
=False, hide_stderr
=False,
386 """Call the given command(s)."""
387 assert isinstance(commands
, list)
391 dispcmd
= str([c
] + args
)
392 # remember shell=False, so use git.cmd on windows, not just git
393 p
= subprocess
.Popen([c
] + args
, cwd
=cwd
, env
=env
,
394 stdout
=subprocess
.PIPE
,
395 stderr
=(subprocess
.PIPE
if hide_stderr
398 except EnvironmentError:
399 e
= sys
.exc_info()[1]
400 if e
.errno
== errno
.ENOENT
:
403 print("unable to run %s" % dispcmd
)
408 print("unable to find command, tried %s" % (commands
,))
410 stdout
= p
.communicate()[0].strip()
411 if sys
.version_info
[0] >= 3:
412 stdout
= stdout
.decode()
413 if p
.returncode
!= 0:
415 print("unable to run %s (error)" % dispcmd
)
416 print("stdout was %s" % stdout
)
417 return None, p
.returncode
418 return stdout
, p
.returncode
421 LONG_VERSION_PY
['git'] = '''
422 # This file helps to compute a version number in source trees obtained from
423 # git-archive tarball (such as those provided by githubs download-from-tag
424 # feature). Distribution tarballs (built by setup.py sdist) and build
425 # directories (produced by setup.py build) will contain a much shorter file
426 # that just contains the computed version number.
428 # This file is released into the public domain. Generated by
429 # versioneer-0.18 (https://github.com/warner/python-versioneer)
431 """Git implementation of _version.py."""
441 """Get the keywords needed to look up the version information."""
442 # these strings will be replaced by git during git-archive.
443 # setup.py/versioneer.py will grep for the variable names, so they must
444 # each be defined on a line of their own. _version.py will just call
446 git_refnames = "%(DOLLAR)sFormat:%%d%(DOLLAR)s"
447 git_full = "%(DOLLAR)sFormat:%%H%(DOLLAR)s"
448 git_date = "%(DOLLAR)sFormat:%%ci%(DOLLAR)s"
449 keywords = {"refnames": git_refnames, "full": git_full, "date": git_date}
453 class VersioneerConfig:
454 """Container for Versioneer configuration parameters."""
458 """Create, populate and return the VersioneerConfig() object."""
459 # these strings are filled in when 'setup.py versioneer' creates
461 cfg = VersioneerConfig()
463 cfg.style = "%(STYLE)s"
464 cfg.tag_prefix = "%(TAG_PREFIX)s"
465 cfg.parentdir_prefix = "%(PARENTDIR_PREFIX)s"
466 cfg.versionfile_source = "%(VERSIONFILE_SOURCE)s"
471 class NotThisMethod(Exception):
472 """Exception raised if a method is not valid for the current scenario."""
479 def register_vcs_handler(vcs, method): # decorator
480 """Decorator to mark a method as the handler for a particular VCS."""
482 """Store f in HANDLERS[vcs][method]."""
483 if vcs not in HANDLERS:
485 HANDLERS[vcs][method] = f
490 def run_command(commands, args, cwd=None, verbose=False, hide_stderr=False,
492 """Call the given command(s)."""
493 assert isinstance(commands, list)
497 dispcmd = str([c] + args)
498 # remember shell=False, so use git.cmd on windows, not just git
499 p = subprocess.Popen([c] + args, cwd=cwd, env=env,
500 stdout=subprocess.PIPE,
501 stderr=(subprocess.PIPE if hide_stderr
504 except EnvironmentError:
505 e = sys.exc_info()[1]
506 if e.errno == errno.ENOENT:
509 print("unable to run %%s" %% dispcmd)
514 print("unable to find command, tried %%s" %% (commands,))
516 stdout = p.communicate()[0].strip()
517 if sys.version_info[0] >= 3:
518 stdout = stdout.decode()
519 if p.returncode != 0:
521 print("unable to run %%s (error)" %% dispcmd)
522 print("stdout was %%s" %% stdout)
523 return None, p.returncode
524 return stdout, p.returncode
527 def versions_from_parentdir(parentdir_prefix, root, verbose):
528 """Try to determine the version from the parent directory name.
530 Source tarballs conventionally unpack into a directory that includes both
531 the project name and a version string. We will also support searching up
532 two directory levels for an appropriately named parent directory
537 dirname = os.path.basename(root)
538 if dirname.startswith(parentdir_prefix):
539 return {"version": dirname[len(parentdir_prefix):],
540 "full-revisionid": None,
541 "dirty": False, "error": None, "date": None}
543 rootdirs.append(root)
544 root = os.path.dirname(root) # up a level
547 print("Tried directories %%s but none started with prefix %%s" %%
548 (str(rootdirs), parentdir_prefix))
549 raise NotThisMethod("rootdir doesn't start with parentdir_prefix")
552 @register_vcs_handler("git", "get_keywords")
553 def git_get_keywords(versionfile_abs):
554 """Extract version information from the given file."""
555 # the code embedded in _version.py can just fetch the value of these
556 # keywords. When used from setup.py, we don't want to import _version.py,
557 # so we do it with a regexp instead. This function is not used from
561 f = open(versionfile_abs, "r")
562 for line in f.readlines():
563 if line.strip().startswith("git_refnames ="):
564 mo = re.search(r'=\s*"(.*)"', line)
566 keywords["refnames"] = mo.group(1)
567 if line.strip().startswith("git_full ="):
568 mo = re.search(r'=\s*"(.*)"', line)
570 keywords["full"] = mo.group(1)
571 if line.strip().startswith("git_date ="):
572 mo = re.search(r'=\s*"(.*)"', line)
574 keywords["date"] = mo.group(1)
576 except EnvironmentError:
581 @register_vcs_handler("git", "keywords")
582 def git_versions_from_keywords(keywords, tag_prefix, verbose):
583 """Get version information from git keywords."""
585 raise NotThisMethod("no keywords at all, weird")
586 date = keywords.get("date")
588 # git-2.2.0 added "%%cI", which expands to an ISO-8601 -compliant
589 # datestamp. However we prefer "%%ci" (which expands to an "ISO-8601
590 # -like" string, which we must then edit to make compliant), because
591 # it's been around since git-1.5.3, and it's too difficult to
592 # discover which version we're using, or to work around using an
594 date = date.strip().replace(" ", "T", 1).replace(" ", "", 1)
595 refnames = keywords["refnames"].strip()
596 if refnames.startswith("$Format"):
598 print("keywords are unexpanded, not using")
599 raise NotThisMethod("unexpanded keywords, not a git-archive tarball")
600 refs = set([r.strip() for r in refnames.strip("()").split(",")])
601 # starting in git-1.8.3, tags are listed as "tag: foo-1.0" instead of
602 # just "foo-1.0". If we see a "tag: " prefix, prefer those.
604 tags = set([r[len(TAG):] for r in refs if r.startswith(TAG)])
606 # Either we're using git < 1.8.3, or there really are no tags. We use
607 # a heuristic: assume all version tags have a digit. The old git %%d
608 # expansion behaves like git log --decorate=short and strips out the
609 # refs/heads/ and refs/tags/ prefixes that would let us distinguish
610 # between branches and tags. By ignoring refnames without digits, we
611 # filter out many common branch names like "release" and
612 # "stabilization", as well as "HEAD" and "master".
613 tags = set([r for r in refs if re.search(r'\d', r)])
615 print("discarding '%%s', no digits" %% ",".join(refs - tags))
617 print("likely tags: %%s" %% ",".join(sorted(tags)))
618 for ref in sorted(tags):
619 # sorting will prefer e.g. "2.0" over "2.0rc1"
620 if ref.startswith(tag_prefix):
621 r = ref[len(tag_prefix):]
623 print("picking %%s" %% r)
624 return {"version": r,
625 "full-revisionid": keywords["full"].strip(),
626 "dirty": False, "error": None,
628 # no suitable tags, so version is "0+unknown", but full hex is still there
630 print("no suitable tags, using unknown + full revision id")
631 return {"version": "0+unknown",
632 "full-revisionid": keywords["full"].strip(),
633 "dirty": False, "error": "no suitable tags", "date": None}
636 @register_vcs_handler("git", "pieces_from_vcs")
637 def git_pieces_from_vcs(tag_prefix, root, verbose, run_command=run_command):
638 """Get version from 'git describe' in the root of the source tree.
640 This only gets called if the git-archive 'subst' keywords were *not*
641 expanded, and _version.py hasn't already been rewritten with a short
642 version string, meaning we're inside a checked out source tree.
645 if sys.platform == "win32":
646 GITS = ["git.cmd", "git.exe"]
648 out, rc = run_command(GITS, ["rev-parse", "--git-dir"], cwd=root,
652 print("Directory %%s not under git control" %% root)
653 raise NotThisMethod("'git rev-parse --git-dir' returned error")
655 # if there is a tag matching tag_prefix, this yields TAG-NUM-gHEX[-dirty]
656 # if there isn't one, this yields HEX[-dirty] (no NUM)
657 describe_out, rc = run_command(GITS, ["describe", "--tags", "--dirty",
658 "--always", "--long",
659 "--match", "%%s*" %% tag_prefix],
661 # --long was added in git-1.5.5
662 if describe_out is None:
663 raise NotThisMethod("'git describe' failed")
664 describe_out = describe_out.strip()
665 full_out, rc = run_command(GITS, ["rev-parse", "HEAD"], cwd=root)
667 raise NotThisMethod("'git rev-parse' failed")
668 full_out = full_out.strip()
671 pieces["long"] = full_out
672 pieces["short"] = full_out[:7] # maybe improved later
673 pieces["error"] = None
675 # parse describe_out. It will be like TAG-NUM-gHEX[-dirty] or HEX[-dirty]
676 # TAG might have hyphens.
677 git_describe = describe_out
679 # look for -dirty suffix
680 dirty = git_describe.endswith("-dirty")
681 pieces["dirty"] = dirty
683 git_describe = git_describe[:git_describe.rindex("-dirty")]
685 # now we have TAG-NUM-gHEX or HEX
687 if "-" in git_describe:
689 mo = re.search(r'^(.+)-(\d+)-g([0-9a-f]+)$', git_describe)
691 # unparseable. Maybe git-describe is misbehaving?
692 pieces["error"] = ("unable to parse git-describe output: '%%s'"
697 full_tag = mo.group(1)
698 if not full_tag.startswith(tag_prefix):
700 fmt = "tag '%%s' doesn't start with prefix '%%s'"
701 print(fmt %% (full_tag, tag_prefix))
702 pieces["error"] = ("tag '%%s' doesn't start with prefix '%%s'"
703 %% (full_tag, tag_prefix))
705 pieces["closest-tag"] = full_tag[len(tag_prefix):]
707 # distance: number of commits since tag
708 pieces["distance"] = int(mo.group(2))
710 # commit: short hex revision ID
711 pieces["short"] = mo.group(3)
715 pieces["closest-tag"] = None
716 count_out, rc = run_command(GITS, ["rev-list", "HEAD", "--count"],
718 pieces["distance"] = int(count_out) # total number of commits
720 # commit date: see ISO-8601 comment in git_versions_from_keywords()
721 date = run_command(GITS, ["show", "-s", "--format=%%ci", "HEAD"],
723 pieces["date"] = date.strip().replace(" ", "T", 1).replace(" ", "", 1)
728 def plus_or_dot(pieces):
729 """Return a + if we don't already have one, else return a ."""
730 if "+" in pieces.get("closest-tag", ""):
735 def render_pep440(pieces):
736 """Build up version string, with post-release "local version identifier".
738 Our goal: TAG[+DISTANCE.gHEX[.dirty]] . Note that if you
739 get a tagged build and then dirty it, you'll get TAG+0.gHEX.dirty
742 1: no tags. git_describe was just HEX. 0+untagged.DISTANCE.gHEX[.dirty]
744 if pieces["closest-tag"]:
745 rendered = pieces["closest-tag"]
746 if pieces["distance"] or pieces["dirty"]:
747 rendered += plus_or_dot(pieces)
748 rendered += "%%d.g%%s" %% (pieces["distance"], pieces["short"])
753 rendered = "0+untagged.%%d.g%%s" %% (pieces["distance"],
760 def render_pep440_pre(pieces):
761 """TAG[.post.devDISTANCE] -- No -dirty.
764 1: no tags. 0.post.devDISTANCE
766 if pieces["closest-tag"]:
767 rendered = pieces["closest-tag"]
768 if pieces["distance"]:
769 rendered += ".post.dev%%d" %% pieces["distance"]
772 rendered = "0.post.dev%%d" %% pieces["distance"]
776 def render_pep440_post(pieces):
777 """TAG[.postDISTANCE[.dev0]+gHEX] .
779 The ".dev0" means dirty. Note that .dev0 sorts backwards
780 (a dirty tree will appear "older" than the corresponding clean one),
781 but you shouldn't be releasing software with -dirty anyways.
784 1: no tags. 0.postDISTANCE[.dev0]
786 if pieces["closest-tag"]:
787 rendered = pieces["closest-tag"]
788 if pieces["distance"] or pieces["dirty"]:
789 rendered += ".post%%d" %% pieces["distance"]
792 rendered += plus_or_dot(pieces)
793 rendered += "g%%s" %% pieces["short"]
796 rendered = "0.post%%d" %% pieces["distance"]
799 rendered += "+g%%s" %% pieces["short"]
803 def render_pep440_old(pieces):
804 """TAG[.postDISTANCE[.dev0]] .
806 The ".dev0" means dirty.
809 1: no tags. 0.postDISTANCE[.dev0]
811 if pieces["closest-tag"]:
812 rendered = pieces["closest-tag"]
813 if pieces["distance"] or pieces["dirty"]:
814 rendered += ".post%%d" %% pieces["distance"]
819 rendered = "0.post%%d" %% pieces["distance"]
825 def render_git_describe(pieces):
826 """TAG[-DISTANCE-gHEX][-dirty].
828 Like 'git describe --tags --dirty --always'.
831 1: no tags. HEX[-dirty] (note: no 'g' prefix)
833 if pieces["closest-tag"]:
834 rendered = pieces["closest-tag"]
835 if pieces["distance"]:
836 rendered += "-%%d-g%%s" %% (pieces["distance"], pieces["short"])
839 rendered = pieces["short"]
845 def render_git_describe_long(pieces):
846 """TAG-DISTANCE-gHEX[-dirty].
848 Like 'git describe --tags --dirty --always -long'.
849 The distance/hash is unconditional.
852 1: no tags. HEX[-dirty] (note: no 'g' prefix)
854 if pieces["closest-tag"]:
855 rendered = pieces["closest-tag"]
856 rendered += "-%%d-g%%s" %% (pieces["distance"], pieces["short"])
859 rendered = pieces["short"]
865 def render(pieces, style):
866 """Render the given version pieces into the requested style."""
868 return {"version": "unknown",
869 "full-revisionid": pieces.get("long"),
871 "error": pieces["error"],
874 if not style or style == "default":
875 style = "pep440" # the default
877 if style == "pep440":
878 rendered = render_pep440(pieces)
879 elif style == "pep440-pre":
880 rendered = render_pep440_pre(pieces)
881 elif style == "pep440-post":
882 rendered = render_pep440_post(pieces)
883 elif style == "pep440-old":
884 rendered = render_pep440_old(pieces)
885 elif style == "git-describe":
886 rendered = render_git_describe(pieces)
887 elif style == "git-describe-long":
888 rendered = render_git_describe_long(pieces)
890 raise ValueError("unknown style '%%s'" %% style)
892 return {"version": rendered, "full-revisionid": pieces["long"],
893 "dirty": pieces["dirty"], "error": None,
894 "date": pieces.get("date")}
898 """Get version information or return default if unable to do so."""
899 # I am in _version.py, which lives at ROOT/VERSIONFILE_SOURCE. If we have
900 # __file__, we can work backwards from there to the root. Some
901 # py2exe/bbfreeze/non-CPython implementations don't do __file__, in which
902 # case we can only use expanded keywords.
905 verbose = cfg.verbose
908 return git_versions_from_keywords(get_keywords(), cfg.tag_prefix,
910 except NotThisMethod:
914 root = os.path.realpath(__file__)
915 # versionfile_source is the relative path from the top of the source
916 # tree (where the .git directory might live) to this file. Invert
917 # this to find the root from __file__.
918 for i in cfg.versionfile_source.split('/'):
919 root = os.path.dirname(root)
921 return {"version": "0+unknown", "full-revisionid": None,
923 "error": "unable to find root of source tree",
927 pieces = git_pieces_from_vcs(cfg.tag_prefix, root, verbose)
928 return render(pieces, cfg.style)
929 except NotThisMethod:
933 if cfg.parentdir_prefix:
934 return versions_from_parentdir(cfg.parentdir_prefix, root, verbose)
935 except NotThisMethod:
938 return {"version": "0+unknown", "full-revisionid": None,
940 "error": "unable to compute version", "date": None}
944 @register_vcs_handler("git", "get_keywords")
945 def git_get_keywords(versionfile_abs
):
946 """Extract version information from the given file."""
947 # the code embedded in _version.py can just fetch the value of these
948 # keywords. When used from setup.py, we don't want to import _version.py,
949 # so we do it with a regexp instead. This function is not used from
953 f
= open(versionfile_abs
, "r")
954 for line
in f
.readlines():
955 if line
.strip().startswith("git_refnames ="):
956 mo
= re
.search(r
'=\s*"(.*)"', line
)
958 keywords
["refnames"] = mo
.group(1)
959 if line
.strip().startswith("git_full ="):
960 mo
= re
.search(r
'=\s*"(.*)"', line
)
962 keywords
["full"] = mo
.group(1)
963 if line
.strip().startswith("git_date ="):
964 mo
= re
.search(r
'=\s*"(.*)"', line
)
966 keywords
["date"] = mo
.group(1)
968 except EnvironmentError:
973 @register_vcs_handler("git", "keywords")
974 def git_versions_from_keywords(keywords
, tag_prefix
, verbose
):
975 """Get version information from git keywords."""
977 raise NotThisMethod("no keywords at all, weird")
978 date
= keywords
.get("date")
980 # git-2.2.0 added "%cI", which expands to an ISO-8601 -compliant
981 # datestamp. However we prefer "%ci" (which expands to an "ISO-8601
982 # -like" string, which we must then edit to make compliant), because
983 # it's been around since git-1.5.3, and it's too difficult to
984 # discover which version we're using, or to work around using an
986 date
= date
.strip().replace(" ", "T", 1).replace(" ", "", 1)
987 refnames
= keywords
["refnames"].strip()
988 if refnames
.startswith("$Format"):
990 print("keywords are unexpanded, not using")
991 raise NotThisMethod("unexpanded keywords, not a git-archive tarball")
992 refs
= set([r
.strip() for r
in refnames
.strip("()").split(",")])
993 # starting in git-1.8.3, tags are listed as "tag: foo-1.0" instead of
994 # just "foo-1.0". If we see a "tag: " prefix, prefer those.
996 tags
= set([r
[len(TAG
):] for r
in refs
if r
.startswith(TAG
)])
998 # Either we're using git < 1.8.3, or there really are no tags. We use
999 # a heuristic: assume all version tags have a digit. The old git %d
1000 # expansion behaves like git log --decorate=short and strips out the
1001 # refs/heads/ and refs/tags/ prefixes that would let us distinguish
1002 # between branches and tags. By ignoring refnames without digits, we
1003 # filter out many common branch names like "release" and
1004 # "stabilization", as well as "HEAD" and "master".
1005 tags
= set([r
for r
in refs
if re
.search(r
'\d', r
)])
1007 print("discarding '%s', no digits" % ",".join(refs
- tags
))
1009 print("likely tags: %s" % ",".join(sorted(tags
)))
1010 for ref
in sorted(tags
):
1011 # sorting will prefer e.g. "2.0" over "2.0rc1"
1012 if ref
.startswith(tag_prefix
):
1013 r
= ref
[len(tag_prefix
):]
1015 print("picking %s" % r
)
1016 return {"version": r
,
1017 "full-revisionid": keywords
["full"].strip(),
1018 "dirty": False, "error": None,
1020 # no suitable tags, so version is "0+unknown", but full hex is still there
1022 print("no suitable tags, using unknown + full revision id")
1023 return {"version": "0+unknown",
1024 "full-revisionid": keywords
["full"].strip(),
1025 "dirty": False, "error": "no suitable tags", "date": None}
1028 @register_vcs_handler("git", "pieces_from_vcs")
1029 def git_pieces_from_vcs(tag_prefix
, root
, verbose
, run_command
=run_command
):
1030 """Get version from 'git describe' in the root of the source tree.
1032 This only gets called if the git-archive 'subst' keywords were *not*
1033 expanded, and _version.py hasn't already been rewritten with a short
1034 version string, meaning we're inside a checked out source tree.
1037 if sys
.platform
== "win32":
1038 GITS
= ["git.cmd", "git.exe"]
1040 out
, rc
= run_command(GITS
, ["rev-parse", "--git-dir"], cwd
=root
,
1044 print("Directory %s not under git control" % root
)
1045 raise NotThisMethod("'git rev-parse --git-dir' returned error")
1047 # if there is a tag matching tag_prefix, this yields TAG-NUM-gHEX[-dirty]
1048 # if there isn't one, this yields HEX[-dirty] (no NUM)
1049 describe_out
, rc
= run_command(GITS
, ["describe", "--tags", "--dirty",
1050 "--always", "--long",
1051 "--match", "%s*" % tag_prefix
],
1053 # --long was added in git-1.5.5
1054 if describe_out
is None:
1055 raise NotThisMethod("'git describe' failed")
1056 describe_out
= describe_out
.strip()
1057 full_out
, rc
= run_command(GITS
, ["rev-parse", "HEAD"], cwd
=root
)
1058 if full_out
is None:
1059 raise NotThisMethod("'git rev-parse' failed")
1060 full_out
= full_out
.strip()
1063 pieces
["long"] = full_out
1064 pieces
["short"] = full_out
[:7] # maybe improved later
1065 pieces
["error"] = None
1067 # parse describe_out. It will be like TAG-NUM-gHEX[-dirty] or HEX[-dirty]
1068 # TAG might have hyphens.
1069 git_describe
= describe_out
1071 # look for -dirty suffix
1072 dirty
= git_describe
.endswith("-dirty")
1073 pieces
["dirty"] = dirty
1075 git_describe
= git_describe
[:git_describe
.rindex("-dirty")]
1077 # now we have TAG-NUM-gHEX or HEX
1079 if "-" in git_describe
:
1081 mo
= re
.search(r
'^(.+)-(\d+)-g([0-9a-f]+)$', git_describe
)
1083 # unparseable. Maybe git-describe is misbehaving?
1084 pieces
["error"] = ("unable to parse git-describe output: '%s'"
1089 full_tag
= mo
.group(1)
1090 if not full_tag
.startswith(tag_prefix
):
1092 fmt
= "tag '%s' doesn't start with prefix '%s'"
1093 print(fmt
% (full_tag
, tag_prefix
))
1094 pieces
["error"] = ("tag '%s' doesn't start with prefix '%s'"
1095 % (full_tag
, tag_prefix
))
1097 pieces
["closest-tag"] = full_tag
[len(tag_prefix
):]
1099 # distance: number of commits since tag
1100 pieces
["distance"] = int(mo
.group(2))
1102 # commit: short hex revision ID
1103 pieces
["short"] = mo
.group(3)
1107 pieces
["closest-tag"] = None
1108 count_out
, rc
= run_command(GITS
, ["rev-list", "HEAD", "--count"],
1110 pieces
["distance"] = int(count_out
) # total number of commits
1112 # commit date: see ISO-8601 comment in git_versions_from_keywords()
1113 date
= run_command(GITS
, ["show", "-s", "--format=%ci", "HEAD"],
1114 cwd
=root
)[0].strip()
1115 pieces
["date"] = date
.strip().replace(" ", "T", 1).replace(" ", "", 1)
1120 def do_vcs_install(manifest_in
, versionfile_source
, ipy
):
1121 """Git-specific installation logic for Versioneer.
1123 For Git, this means creating/changing .gitattributes to mark _version.py
1124 for export-subst keyword substitution.
1127 if sys
.platform
== "win32":
1128 GITS
= ["git.cmd", "git.exe"]
1129 files
= [manifest_in
, versionfile_source
]
1134 if me
.endswith(".pyc") or me
.endswith(".pyo"):
1135 me
= os
.path
.splitext(me
)[0] + ".py"
1136 versioneer_file
= os
.path
.relpath(me
)
1138 versioneer_file
= "versioneer.py"
1139 files
.append(versioneer_file
)
1142 f
= open(".gitattributes", "r")
1143 for line
in f
.readlines():
1144 if line
.strip().startswith(versionfile_source
):
1145 if "export-subst" in line
.strip().split()[1:]:
1148 except EnvironmentError:
1151 f
= open(".gitattributes", "a+")
1152 f
.write("%s export-subst\n" % versionfile_source
)
1154 files
.append(".gitattributes")
1155 run_command(GITS
, ["add", "--"] + files
)
1158 def versions_from_parentdir(parentdir_prefix
, root
, verbose
):
1159 """Try to determine the version from the parent directory name.
1161 Source tarballs conventionally unpack into a directory that includes both
1162 the project name and a version string. We will also support searching up
1163 two directory levels for an appropriately named parent directory
1168 dirname
= os
.path
.basename(root
)
1169 if dirname
.startswith(parentdir_prefix
):
1170 return {"version": dirname
[len(parentdir_prefix
):],
1171 "full-revisionid": None,
1172 "dirty": False, "error": None, "date": None}
1174 rootdirs
.append(root
)
1175 root
= os
.path
.dirname(root
) # up a level
1178 print("Tried directories %s but none started with prefix %s" %
1179 (str(rootdirs
), parentdir_prefix
))
1180 raise NotThisMethod("rootdir doesn't start with parentdir_prefix")
1183 SHORT_VERSION_PY
= """
1184 # This file was generated by 'versioneer.py' (0.18) from
1185 # revision-control system data, or from the parent directory name of an
1186 # unpacked source archive. Distribution tarballs contain a pre-generated copy
1193 ''' # END VERSION_JSON
1197 return json.loads(version_json)
1201 def versions_from_file(filename
):
1202 """Try to determine the version from _version.py if present."""
1204 with
open(filename
) as f
:
1206 except EnvironmentError:
1207 raise NotThisMethod("unable to read _version.py")
1208 mo
= re
.search(r
"version_json = '''\n(.*)''' # END VERSION_JSON",
1209 contents
, re
.M | re
.S
)
1211 mo
= re
.search(r
"version_json = '''\r\n(.*)''' # END VERSION_JSON",
1212 contents
, re
.M | re
.S
)
1214 raise NotThisMethod("no version_json in _version.py")
1215 return json
.loads(mo
.group(1))
1218 def write_to_version_file(filename
, versions
):
1219 """Write the given version number to the given _version.py file."""
1221 contents
= json
.dumps(versions
, sort_keys
=True,
1222 indent
=1, separators
=(",", ": "))
1223 with
open(filename
, "w") as f
:
1224 f
.write(SHORT_VERSION_PY
% contents
)
1226 print("set %s to '%s'" % (filename
, versions
["version"]))
1229 def plus_or_dot(pieces
):
1230 """Return a + if we don't already have one, else return a ."""
1231 if "+" in pieces
.get("closest-tag", ""):
1236 def render_pep440(pieces
):
1237 """Build up version string, with post-release "local version identifier".
1239 Our goal: TAG[+DISTANCE.gHEX[.dirty]] . Note that if you
1240 get a tagged build and then dirty it, you'll get TAG+0.gHEX.dirty
1243 1: no tags. git_describe was just HEX. 0+untagged.DISTANCE.gHEX[.dirty]
1245 if pieces
["closest-tag"]:
1246 rendered
= pieces
["closest-tag"]
1247 if pieces
["distance"] or pieces
["dirty"]:
1248 rendered
+= plus_or_dot(pieces
)
1249 rendered
+= "%d.g%s" % (pieces
["distance"], pieces
["short"])
1251 rendered
+= ".dirty"
1254 rendered
= "0+untagged.%d.g%s" % (pieces
["distance"],
1257 rendered
+= ".dirty"
1261 def render_pep440_pre(pieces
):
1262 """TAG[.post.devDISTANCE] -- No -dirty.
1265 1: no tags. 0.post.devDISTANCE
1267 if pieces
["closest-tag"]:
1268 rendered
= pieces
["closest-tag"]
1269 if pieces
["distance"]:
1270 rendered
+= ".post.dev%d" % pieces
["distance"]
1273 rendered
= "0.post.dev%d" % pieces
["distance"]
1277 def render_pep440_post(pieces
):
1278 """TAG[.postDISTANCE[.dev0]+gHEX] .
1280 The ".dev0" means dirty. Note that .dev0 sorts backwards
1281 (a dirty tree will appear "older" than the corresponding clean one),
1282 but you shouldn't be releasing software with -dirty anyways.
1285 1: no tags. 0.postDISTANCE[.dev0]
1287 if pieces
["closest-tag"]:
1288 rendered
= pieces
["closest-tag"]
1289 if pieces
["distance"] or pieces
["dirty"]:
1290 rendered
+= ".post%d" % pieces
["distance"]
1293 rendered
+= plus_or_dot(pieces
)
1294 rendered
+= "g%s" % pieces
["short"]
1297 rendered
= "0.post%d" % pieces
["distance"]
1300 rendered
+= "+g%s" % pieces
["short"]
1304 def render_pep440_old(pieces
):
1305 """TAG[.postDISTANCE[.dev0]] .
1307 The ".dev0" means dirty.
1310 1: no tags. 0.postDISTANCE[.dev0]
1312 if pieces
["closest-tag"]:
1313 rendered
= pieces
["closest-tag"]
1314 if pieces
["distance"] or pieces
["dirty"]:
1315 rendered
+= ".post%d" % pieces
["distance"]
1320 rendered
= "0.post%d" % pieces
["distance"]
1326 def render_git_describe(pieces
):
1327 """TAG[-DISTANCE-gHEX][-dirty].
1329 Like 'git describe --tags --dirty --always'.
1332 1: no tags. HEX[-dirty] (note: no 'g' prefix)
1334 if pieces
["closest-tag"]:
1335 rendered
= pieces
["closest-tag"]
1336 if pieces
["distance"]:
1337 rendered
+= "-%d-g%s" % (pieces
["distance"], pieces
["short"])
1340 rendered
= pieces
["short"]
1342 rendered
+= "-dirty"
1346 def render_git_describe_long(pieces
):
1347 """TAG-DISTANCE-gHEX[-dirty].
1349 Like 'git describe --tags --dirty --always -long'.
1350 The distance/hash is unconditional.
1353 1: no tags. HEX[-dirty] (note: no 'g' prefix)
1355 if pieces
["closest-tag"]:
1356 rendered
= pieces
["closest-tag"]
1357 rendered
+= "-%d-g%s" % (pieces
["distance"], pieces
["short"])
1360 rendered
= pieces
["short"]
1362 rendered
+= "-dirty"
1366 def render(pieces
, style
):
1367 """Render the given version pieces into the requested style."""
1369 return {"version": "unknown",
1370 "full-revisionid": pieces
.get("long"),
1372 "error": pieces
["error"],
1375 if not style
or style
== "default":
1376 style
= "pep440" # the default
1378 if style
== "pep440":
1379 rendered
= render_pep440(pieces
)
1380 elif style
== "pep440-pre":
1381 rendered
= render_pep440_pre(pieces
)
1382 elif style
== "pep440-post":
1383 rendered
= render_pep440_post(pieces
)
1384 elif style
== "pep440-old":
1385 rendered
= render_pep440_old(pieces
)
1386 elif style
== "git-describe":
1387 rendered
= render_git_describe(pieces
)
1388 elif style
== "git-describe-long":
1389 rendered
= render_git_describe_long(pieces
)
1391 raise ValueError("unknown style '%s'" % style
)
1393 return {"version": rendered
, "full-revisionid": pieces
["long"],
1394 "dirty": pieces
["dirty"], "error": None,
1395 "date": pieces
.get("date")}
1398 class VersioneerBadRootError(Exception):
1399 """The project root directory is unknown or missing key files."""
1402 def get_versions(verbose
=False):
1403 """Get the project version from whatever source is available.
1405 Returns dict with two keys: 'version' and 'full'.
1407 if "versioneer" in sys
.modules
:
1408 # see the discussion in cmdclass.py:get_cmdclass()
1409 del sys
.modules
["versioneer"]
1412 cfg
= get_config_from_root(root
)
1414 assert cfg
.VCS
is not None, "please set [versioneer]VCS= in setup.cfg"
1415 handlers
= HANDLERS
.get(cfg
.VCS
)
1416 assert handlers
, "unrecognized VCS '%s'" % cfg
.VCS
1417 verbose
= verbose
or cfg
.verbose
1418 assert cfg
.versionfile_source
is not None, \
1419 "please set versioneer.versionfile_source"
1420 assert cfg
.tag_prefix
is not None, "please set versioneer.tag_prefix"
1422 versionfile_abs
= os
.path
.join(root
, cfg
.versionfile_source
)
1424 # extract version from first of: _version.py, VCS command (e.g. 'git
1425 # describe'), parentdir. This is meant to work for developers using a
1426 # source checkout, for users of a tarball created by 'setup.py sdist',
1427 # and for users of a tarball/zipball created by 'git archive' or github's
1428 # download-from-tag feature or the equivalent in other VCSes.
1430 get_keywords_f
= handlers
.get("get_keywords")
1431 from_keywords_f
= handlers
.get("keywords")
1432 if get_keywords_f
and from_keywords_f
:
1434 keywords
= get_keywords_f(versionfile_abs
)
1435 ver
= from_keywords_f(keywords
, cfg
.tag_prefix
, verbose
)
1437 print("got version from expanded keyword %s" % ver
)
1439 except NotThisMethod
:
1443 ver
= versions_from_file(versionfile_abs
)
1445 print("got version from file %s %s" % (versionfile_abs
, ver
))
1447 except NotThisMethod
:
1450 from_vcs_f
= handlers
.get("pieces_from_vcs")
1453 pieces
= from_vcs_f(cfg
.tag_prefix
, root
, verbose
)
1454 ver
= render(pieces
, cfg
.style
)
1456 print("got version from VCS %s" % ver
)
1458 except NotThisMethod
:
1462 if cfg
.parentdir_prefix
:
1463 ver
= versions_from_parentdir(cfg
.parentdir_prefix
, root
, verbose
)
1465 print("got version from parentdir %s" % ver
)
1467 except NotThisMethod
:
1471 print("unable to compute version")
1473 return {"version": "0+unknown", "full-revisionid": None,
1474 "dirty": None, "error": "unable to compute version",
1479 """Get the short version string for this project."""
1480 return get_versions()["version"]
1484 """Get the custom setuptools/distutils subclasses used by Versioneer."""
1485 if "versioneer" in sys
.modules
:
1486 del sys
.modules
["versioneer"]
1487 # this fixes the "python setup.py develop" case (also 'install' and
1488 # 'easy_install .'), in which subdependencies of the main project are
1489 # built (using setup.py bdist_egg) in the same python process. Assume
1490 # a main project A and a dependency B, which use different versions
1491 # of Versioneer. A's setup.py imports A's Versioneer, leaving it in
1492 # sys.modules by the time B's setup.py is executed, causing B to run
1493 # with the wrong versioneer. Setuptools wraps the sub-dep builds in a
1494 # sandbox that restores sys.modules to it's pre-build state, so the
1495 # parent is protected against the child's "import versioneer". By
1496 # removing ourselves from sys.modules here, before the child build
1497 # happens, we protect the child from the parent's versioneer too.
1498 # Also see https://github.com/warner/python-versioneer/issues/52
1502 # we add "version" to both distutils and setuptools
1503 from distutils
.core
import Command
1505 class cmd_version(Command
):
1506 description
= "report generated version string"
1508 boolean_options
= []
1510 def initialize_options(self
):
1513 def finalize_options(self
):
1517 vers
= get_versions(verbose
=True)
1518 print("Version: %s" % vers
["version"])
1519 print(" full-revisionid: %s" % vers
.get("full-revisionid"))
1520 print(" dirty: %s" % vers
.get("dirty"))
1521 print(" date: %s" % vers
.get("date"))
1523 print(" error: %s" % vers
["error"])
1524 cmds
["version"] = cmd_version
1526 # we override "build_py" in both distutils and setuptools
1528 # most invocation pathways end up running build_py:
1529 # distutils/build -> build_py
1530 # distutils/install -> distutils/build ->..
1531 # setuptools/bdist_wheel -> distutils/install ->..
1532 # setuptools/bdist_egg -> distutils/install_lib -> build_py
1533 # setuptools/install -> bdist_egg ->..
1534 # setuptools/develop -> ?
1536 # copies source tree to a tempdir before running egg_info/etc
1537 # if .git isn't copied too, 'git describe' will fail
1538 # then does setup.py bdist_wheel, or sometimes setup.py install
1539 # setup.py egg_info -> ?
1541 # we override different "build_py" commands for both environments
1542 if "setuptools" in sys
.modules
:
1543 from setuptools
.command
.build_py
import build_py
as _build_py
1545 from distutils
.command
.build_py
import build_py
as _build_py
1547 class cmd_build_py(_build_py
):
1550 cfg
= get_config_from_root(root
)
1551 versions
= get_versions()
1553 # now locate _version.py in the new build/ directory and replace
1554 # it with an updated value
1555 if cfg
.versionfile_build
:
1556 target_versionfile
= os
.path
.join(self
.build_lib
,
1557 cfg
.versionfile_build
)
1558 print("UPDATING %s" % target_versionfile
)
1559 write_to_version_file(target_versionfile
, versions
)
1560 cmds
["build_py"] = cmd_build_py
1562 if "cx_Freeze" in sys
.modules
: # cx_freeze enabled?
1563 from cx_Freeze
.dist
import build_exe
as _build_exe
1564 # nczeczulin reports that py2exe won't like the pep440-style string
1565 # as FILEVERSION, but it can be used for PRODUCTVERSION, e.g.
1567 # "version": versioneer.get_version().split("+", 1)[0], # FILEVERSION
1568 # "product_version": versioneer.get_version(),
1571 class cmd_build_exe(_build_exe
):
1574 cfg
= get_config_from_root(root
)
1575 versions
= get_versions()
1576 target_versionfile
= cfg
.versionfile_source
1577 print("UPDATING %s" % target_versionfile
)
1578 write_to_version_file(target_versionfile
, versions
)
1580 _build_exe
.run(self
)
1581 os
.unlink(target_versionfile
)
1582 with
open(cfg
.versionfile_source
, "w") as f
:
1583 LONG
= LONG_VERSION_PY
[cfg
.VCS
]
1587 "TAG_PREFIX": cfg
.tag_prefix
,
1588 "PARENTDIR_PREFIX": cfg
.parentdir_prefix
,
1589 "VERSIONFILE_SOURCE": cfg
.versionfile_source
,
1591 cmds
["build_exe"] = cmd_build_exe
1592 del cmds
["build_py"]
1594 if 'py2exe' in sys
.modules
: # py2exe enabled?
1596 from py2exe
.distutils_buildexe
import py2exe
as _py2exe
# py3
1598 from py2exe
.build_exe
import py2exe
as _py2exe
# py2
1600 class cmd_py2exe(_py2exe
):
1603 cfg
= get_config_from_root(root
)
1604 versions
= get_versions()
1605 target_versionfile
= cfg
.versionfile_source
1606 print("UPDATING %s" % target_versionfile
)
1607 write_to_version_file(target_versionfile
, versions
)
1610 os
.unlink(target_versionfile
)
1611 with
open(cfg
.versionfile_source
, "w") as f
:
1612 LONG
= LONG_VERSION_PY
[cfg
.VCS
]
1616 "TAG_PREFIX": cfg
.tag_prefix
,
1617 "PARENTDIR_PREFIX": cfg
.parentdir_prefix
,
1618 "VERSIONFILE_SOURCE": cfg
.versionfile_source
,
1620 cmds
["py2exe"] = cmd_py2exe
1622 # we override different "sdist" commands for both environments
1623 if "setuptools" in sys
.modules
:
1624 from setuptools
.command
.sdist
import sdist
as _sdist
1626 from distutils
.command
.sdist
import sdist
as _sdist
1628 class cmd_sdist(_sdist
):
1630 versions
= get_versions()
1631 self
._versioneer
_generated
_versions
= versions
1632 # unless we update this, the command will keep using the old
1634 self
.distribution
.metadata
.version
= versions
["version"]
1635 return _sdist
.run(self
)
1637 def make_release_tree(self
, base_dir
, files
):
1639 cfg
= get_config_from_root(root
)
1640 _sdist
.make_release_tree(self
, base_dir
, files
)
1641 # now locate _version.py in the new base_dir directory
1642 # (remembering that it may be a hardlink) and replace it with an
1644 target_versionfile
= os
.path
.join(base_dir
, cfg
.versionfile_source
)
1645 print("UPDATING %s" % target_versionfile
)
1646 write_to_version_file(target_versionfile
,
1647 self
._versioneer
_generated
_versions
)
1648 cmds
["sdist"] = cmd_sdist
1654 setup.cfg is missing the necessary Versioneer configuration. You need
1660 versionfile_source = src/myproject/_version.py
1661 versionfile_build = myproject/_version.py
1663 parentdir_prefix = myproject-
1665 You will also need to edit your setup.py to use the results:
1668 setup(version=versioneer.get_version(),
1669 cmdclass=versioneer.get_cmdclass(), ...)
1671 Please read the docstring in ./versioneer.py for configuration instructions,
1672 edit setup.cfg, and re-run the installer or 'python versioneer.py setup'.
1676 # See the docstring in versioneer.py for instructions. Note that you must
1677 # re-run 'versioneer.py setup' after changing this section, and commit the
1683 #versionfile_source =
1684 #versionfile_build =
1690 INIT_PY_SNIPPET
= """
1691 from ._version import get_versions
1692 __version__ = get_versions()['version']
1698 """Main VCS-independent setup function for installing Versioneer."""
1701 cfg
= get_config_from_root(root
)
1702 except (EnvironmentError, configparser
.NoSectionError
,
1703 configparser
.NoOptionError
) as e
:
1704 if isinstance(e
, (EnvironmentError, configparser
.NoSectionError
)):
1705 print("Adding sample versioneer config to setup.cfg",
1707 with
open(os
.path
.join(root
, "setup.cfg"), "a") as f
:
1708 f
.write(SAMPLE_CONFIG
)
1709 print(CONFIG_ERROR
, file=sys
.stderr
)
1712 print(" creating %s" % cfg
.versionfile_source
)
1713 with
open(cfg
.versionfile_source
, "w") as f
:
1714 LONG
= LONG_VERSION_PY
[cfg
.VCS
]
1715 f
.write(LONG
% {"DOLLAR": "$",
1717 "TAG_PREFIX": cfg
.tag_prefix
,
1718 "PARENTDIR_PREFIX": cfg
.parentdir_prefix
,
1719 "VERSIONFILE_SOURCE": cfg
.versionfile_source
,
1722 ipy
= os
.path
.join(os
.path
.dirname(cfg
.versionfile_source
),
1724 if os
.path
.exists(ipy
):
1726 with
open(ipy
, "r") as f
:
1728 except EnvironmentError:
1730 if INIT_PY_SNIPPET
not in old
:
1731 print(" appending to %s" % ipy
)
1732 with
open(ipy
, "a") as f
:
1733 f
.write(INIT_PY_SNIPPET
)
1735 print(" %s unmodified" % ipy
)
1737 print(" %s doesn't exist, ok" % ipy
)
1740 # Make sure both the top-level "versioneer.py" and versionfile_source
1741 # (PKG/_version.py, used by runtime code) are in MANIFEST.in, so
1742 # they'll be copied into source distributions. Pip won't be able to
1743 # install the package without this.
1744 manifest_in
= os
.path
.join(root
, "MANIFEST.in")
1745 simple_includes
= set()
1747 with
open(manifest_in
, "r") as f
:
1749 if line
.startswith("include "):
1750 for include
in line
.split()[1:]:
1751 simple_includes
.add(include
)
1752 except EnvironmentError:
1754 # That doesn't cover everything MANIFEST.in can do
1755 # (http://docs.python.org/2/distutils/sourcedist.html#commands), so
1756 # it might give some false negatives. Appending redundant 'include'
1757 # lines is safe, though.
1758 if "versioneer.py" not in simple_includes
:
1759 print(" appending 'versioneer.py' to MANIFEST.in")
1760 with
open(manifest_in
, "a") as f
:
1761 f
.write("include versioneer.py\n")
1763 print(" 'versioneer.py' already in MANIFEST.in")
1764 if cfg
.versionfile_source
not in simple_includes
:
1765 print(" appending versionfile_source ('%s') to MANIFEST.in" %
1766 cfg
.versionfile_source
)
1767 with
open(manifest_in
, "a") as f
:
1768 f
.write("include %s\n" % cfg
.versionfile_source
)
1770 print(" versionfile_source already in MANIFEST.in")
1772 # Make VCS-specific changes. For git, this means creating/changing
1773 # .gitattributes to mark _version.py for export-subst keyword
1775 do_vcs_install(manifest_in
, cfg
.versionfile_source
, ipy
)
1779 def scan_setup_py():
1780 """Validate the contents of setup.py against Versioneer's expectations."""
1784 with
open("setup.py", "r") as f
:
1785 for line
in f
.readlines():
1786 if "import versioneer" in line
:
1788 if "versioneer.get_cmdclass()" in line
:
1789 found
.add("cmdclass")
1790 if "versioneer.get_version()" in line
:
1791 found
.add("get_version")
1792 if "versioneer.VCS" in line
:
1794 if "versioneer.versionfile_source" in line
:
1798 print("Your setup.py appears to be missing some important items")
1799 print("(but I might be wrong). Please make sure it has something")
1800 print("roughly like the following:")
1802 print(" import versioneer")
1803 print(" setup( version=versioneer.get_version(),")
1804 print(" cmdclass=versioneer.get_cmdclass(), ...)")
1808 print("You should remove lines like 'versioneer.VCS = ' and")
1809 print("'versioneer.versionfile_source = ' . This configuration")
1810 print("now lives in setup.cfg, and should be removed from setup.py")
1816 if __name__
== "__main__":
1820 errors
+= scan_setup_py()