You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 

1823 lines
67 KiB

  1. # Version: 0.18
  2. """The Versioneer - like a rocketeer, but for versions.
  3. The Versioneer
  4. ==============
  5. * like a rocketeer, but for versions!
  6. * https://github.com/warner/python-versioneer
  7. * Brian Warner
  8. * License: Public Domain
  9. * Compatible With: python2.6, 2.7, 3.2, 3.3, 3.4, 3.5, 3.6, and pypy
  10. * [![Latest Version]
  11. (https://pypip.in/version/versioneer/badge.svg?style=flat)
  12. ](https://pypi.python.org/pypi/versioneer/)
  13. * [![Build Status]
  14. (https://travis-ci.org/warner/python-versioneer.png?branch=master)
  15. ](https://travis-ci.org/warner/python-versioneer)
  16. This is a tool for managing a recorded version number in distutils-based
  17. python projects. The goal is to remove the tedious and error-prone "update
  18. the embedded version string" step from your release process. Making a new
  19. release should be as easy as recording a new tag in your version-control
  20. system, and maybe making new tarballs.
  21. ## Quick Install
  22. * `pip install versioneer` to somewhere to your $PATH
  23. * add a `[versioneer]` section to your setup.cfg (see below)
  24. * run `versioneer install` in your source tree, commit the results
  25. ## Version Identifiers
  26. Source trees come from a variety of places:
  27. * a version-control system checkout (mostly used by developers)
  28. * a nightly tarball, produced by build automation
  29. * a snapshot tarball, produced by a web-based VCS browser, like github's
  30. "tarball from tag" feature
  31. * a release tarball, produced by "setup.py sdist", distributed through PyPI
  32. Within each source tree, the version identifier (either a string or a number,
  33. this tool is format-agnostic) can come from a variety of places:
  34. * ask the VCS tool itself, e.g. "git describe" (for checkouts), which knows
  35. about recent "tags" and an absolute revision-id
  36. * the name of the directory into which the tarball was unpacked
  37. * an expanded VCS keyword ($Id$, etc)
  38. * a `_version.py` created by some earlier build step
  39. For released software, the version identifier is closely related to a VCS
  40. tag. Some projects use tag names that include more than just the version
  41. string (e.g. "myproject-1.2" instead of just "1.2"), in which case the tool
  42. needs to strip the tag prefix to extract the version identifier. For
  43. unreleased software (between tags), the version identifier should provide
  44. enough information to help developers recreate the same tree, while also
  45. giving them an idea of roughly how old the tree is (after version 1.2, before
  46. version 1.3). Many VCS systems can report a description that captures this,
  47. for example `git describe --tags --dirty --always` reports things like
  48. "0.7-1-g574ab98-dirty" to indicate that the checkout is one revision past the
  49. 0.7 tag, has a unique revision id of "574ab98", and is "dirty" (it has
  50. uncommitted changes.
  51. The version identifier is used for multiple purposes:
  52. * to allow the module to self-identify its version: `myproject.__version__`
  53. * to choose a name and prefix for a 'setup.py sdist' tarball
  54. ## Theory of Operation
  55. Versioneer works by adding a special `_version.py` file into your source
  56. tree, where your `__init__.py` can import it. This `_version.py` knows how to
  57. dynamically ask the VCS tool for version information at import time.
  58. `_version.py` also contains `$Revision$` markers, and the installation
  59. process marks `_version.py` to have this marker rewritten with a tag name
  60. during the `git archive` command. As a result, generated tarballs will
  61. contain enough information to get the proper version.
  62. To allow `setup.py` to compute a version too, a `versioneer.py` is added to
  63. the top level of your source tree, next to `setup.py` and the `setup.cfg`
  64. that configures it. This overrides several distutils/setuptools commands to
  65. compute the version when invoked, and changes `setup.py build` and `setup.py
  66. sdist` to replace `_version.py` with a small static file that contains just
  67. the generated version data.
  68. ## Installation
  69. See [INSTALL.md](./INSTALL.md) for detailed installation instructions.
  70. ## Version-String Flavors
  71. Code which uses Versioneer can learn about its version string at runtime by
  72. importing `_version` from your main `__init__.py` file and running the
  73. `get_versions()` function. From the "outside" (e.g. in `setup.py`), you can
  74. import the top-level `versioneer.py` and run `get_versions()`.
  75. Both functions return a dictionary with different flavors of version
  76. information:
  77. * `['version']`: A condensed version string, rendered using the selected
  78. style. This is the most commonly used value for the project's version
  79. string. The default "pep440" style yields strings like `0.11`,
  80. `0.11+2.g1076c97`, or `0.11+2.g1076c97.dirty`. See the "Styles" section
  81. below for alternative styles.
  82. * `['full-revisionid']`: detailed revision identifier. For Git, this is the
  83. full SHA1 commit id, e.g. "1076c978a8d3cfc70f408fe5974aa6c092c949ac".
  84. * `['date']`: Date and time of the latest `HEAD` commit. For Git, it is the
  85. commit date in ISO 8601 format. This will be None if the date is not
  86. available.
  87. * `['dirty']`: a boolean, True if the tree has uncommitted changes. Note that
  88. this is only accurate if run in a VCS checkout, otherwise it is likely to
  89. be False or None
  90. * `['error']`: if the version string could not be computed, this will be set
  91. to a string describing the problem, otherwise it will be None. It may be
  92. useful to throw an exception in setup.py if this is set, to avoid e.g.
  93. creating tarballs with a version string of "unknown".
  94. Some variants are more useful than others. Including `full-revisionid` in a
  95. bug report should allow developers to reconstruct the exact code being tested
  96. (or indicate the presence of local changes that should be shared with the
  97. developers). `version` is suitable for display in an "about" box or a CLI
  98. `--version` output: it can be easily compared against release notes and lists
  99. of bugs fixed in various releases.
  100. The installer adds the following text to your `__init__.py` to place a basic
  101. version in `YOURPROJECT.__version__`:
  102. from ._version import get_versions
  103. __version__ = get_versions()['version']
  104. del get_versions
  105. ## Styles
  106. The setup.cfg `style=` configuration controls how the VCS information is
  107. rendered into a version string.
  108. The default style, "pep440", produces a PEP440-compliant string, equal to the
  109. un-prefixed tag name for actual releases, and containing an additional "local
  110. version" section with more detail for in-between builds. For Git, this is
  111. TAG[+DISTANCE.gHEX[.dirty]] , using information from `git describe --tags
  112. --dirty --always`. For example "0.11+2.g1076c97.dirty" indicates that the
  113. tree is like the "1076c97" commit but has uncommitted changes (".dirty"), and
  114. that this commit is two revisions ("+2") beyond the "0.11" tag. For released
  115. software (exactly equal to a known tag), the identifier will only contain the
  116. stripped tag, e.g. "0.11".
  117. Other styles are available. See [details.md](details.md) in the Versioneer
  118. source tree for descriptions.
  119. ## Debugging
  120. Versioneer tries to avoid fatal errors: if something goes wrong, it will tend
  121. to return a version of "0+unknown". To investigate the problem, run `setup.py
  122. version`, which will run the version-lookup code in a verbose mode, and will
  123. display the full contents of `get_versions()` (including the `error` string,
  124. which may help identify what went wrong).
  125. ## Known Limitations
  126. Some situations are known to cause problems for Versioneer. This details the
  127. most significant ones. More can be found on Github
  128. [issues page](https://github.com/warner/python-versioneer/issues).
  129. ### Subprojects
  130. Versioneer has limited support for source trees in which `setup.py` is not in
  131. the root directory (e.g. `setup.py` and `.git/` are *not* siblings). The are
  132. two common reasons why `setup.py` might not be in the root:
  133. * Source trees which contain multiple subprojects, such as
  134. [Buildbot](https://github.com/buildbot/buildbot), which contains both
  135. "master" and "slave" subprojects, each with their own `setup.py`,
  136. `setup.cfg`, and `tox.ini`. Projects like these produce multiple PyPI
  137. distributions (and upload multiple independently-installable tarballs).
  138. * Source trees whose main purpose is to contain a C library, but which also
  139. provide bindings to Python (and perhaps other langauges) in subdirectories.
  140. Versioneer will look for `.git` in parent directories, and most operations
  141. should get the right version string. However `pip` and `setuptools` have bugs
  142. and implementation details which frequently cause `pip install .` from a
  143. subproject directory to fail to find a correct version string (so it usually
  144. defaults to `0+unknown`).
  145. `pip install --editable .` should work correctly. `setup.py install` might
  146. work too.
  147. Pip-8.1.1 is known to have this problem, but hopefully it will get fixed in
  148. some later version.
  149. [Bug #38](https://github.com/warner/python-versioneer/issues/38) is tracking
  150. this issue. The discussion in
  151. [PR #61](https://github.com/warner/python-versioneer/pull/61) describes the
  152. issue from the Versioneer side in more detail.
  153. [pip PR#3176](https://github.com/pypa/pip/pull/3176) and
  154. [pip PR#3615](https://github.com/pypa/pip/pull/3615) contain work to improve
  155. pip to let Versioneer work correctly.
  156. Versioneer-0.16 and earlier only looked for a `.git` directory next to the
  157. `setup.cfg`, so subprojects were completely unsupported with those releases.
  158. ### Editable installs with setuptools <= 18.5
  159. `setup.py develop` and `pip install --editable .` allow you to install a
  160. project into a virtualenv once, then continue editing the source code (and
  161. test) without re-installing after every change.
  162. "Entry-point scripts" (`setup(entry_points={"console_scripts": ..})`) are a
  163. convenient way to specify executable scripts that should be installed along
  164. with the python package.
  165. These both work as expected when using modern setuptools. When using
  166. setuptools-18.5 or earlier, however, certain operations will cause
  167. `pkg_resources.DistributionNotFound` errors when running the entrypoint
  168. script, which must be resolved by re-installing the package. This happens
  169. when the install happens with one version, then the egg_info data is
  170. regenerated while a different version is checked out. Many setup.py commands
  171. cause egg_info to be rebuilt (including `sdist`, `wheel`, and installing into
  172. a different virtualenv), so this can be surprising.
  173. [Bug #83](https://github.com/warner/python-versioneer/issues/83) describes
  174. this one, but upgrading to a newer version of setuptools should probably
  175. resolve it.
  176. ### Unicode version strings
  177. While Versioneer works (and is continually tested) with both Python 2 and
  178. Python 3, it is not entirely consistent with bytes-vs-unicode distinctions.
  179. Newer releases probably generate unicode version strings on py2. It's not
  180. clear that this is wrong, but it may be surprising for applications when then
  181. write these strings to a network connection or include them in bytes-oriented
  182. APIs like cryptographic checksums.
  183. [Bug #71](https://github.com/warner/python-versioneer/issues/71) investigates
  184. this question.
  185. ## Updating Versioneer
  186. To upgrade your project to a new release of Versioneer, do the following:
  187. * install the new Versioneer (`pip install -U versioneer` or equivalent)
  188. * edit `setup.cfg`, if necessary, to include any new configuration settings
  189. indicated by the release notes. See [UPGRADING](./UPGRADING.md) for details.
  190. * re-run `versioneer install` in your source tree, to replace
  191. `SRC/_version.py`
  192. * commit any changed files
  193. ## Future Directions
  194. This tool is designed to make it easily extended to other version-control
  195. systems: all VCS-specific components are in separate directories like
  196. src/git/ . The top-level `versioneer.py` script is assembled from these
  197. components by running make-versioneer.py . In the future, make-versioneer.py
  198. will take a VCS name as an argument, and will construct a version of
  199. `versioneer.py` that is specific to the given VCS. It might also take the
  200. configuration arguments that are currently provided manually during
  201. installation by editing setup.py . Alternatively, it might go the other
  202. direction and include code from all supported VCS systems, reducing the
  203. number of intermediate scripts.
  204. ## License
  205. To make Versioneer easier to embed, all its code is dedicated to the public
  206. domain. The `_version.py` that it creates is also in the public domain.
  207. Specifically, both are released under the Creative Commons "Public Domain
  208. Dedication" license (CC0-1.0), as described in
  209. https://creativecommons.org/publicdomain/zero/1.0/ .
  210. """
  211. from __future__ import print_function
  212. try:
  213. import configparser
  214. except ImportError:
  215. import ConfigParser as configparser
  216. import errno
  217. import json
  218. import os
  219. import re
  220. import subprocess
  221. import sys
  222. class VersioneerConfig:
  223. """Container for Versioneer configuration parameters."""
  224. def get_root():
  225. """Get the project root directory.
  226. We require that all commands are run from the project root, i.e. the
  227. directory that contains setup.py, setup.cfg, and versioneer.py .
  228. """
  229. root = os.path.realpath(os.path.abspath(os.getcwd()))
  230. setup_py = os.path.join(root, "setup.py")
  231. versioneer_py = os.path.join(root, "versioneer.py")
  232. if not (os.path.exists(setup_py) or os.path.exists(versioneer_py)):
  233. # allow 'python path/to/setup.py COMMAND'
  234. root = os.path.dirname(os.path.realpath(os.path.abspath(sys.argv[0])))
  235. setup_py = os.path.join(root, "setup.py")
  236. versioneer_py = os.path.join(root, "versioneer.py")
  237. if not (os.path.exists(setup_py) or os.path.exists(versioneer_py)):
  238. err = ("Versioneer was unable to run the project root directory. "
  239. "Versioneer requires setup.py to be executed from "
  240. "its immediate directory (like 'python setup.py COMMAND'), "
  241. "or in a way that lets it use sys.argv[0] to find the root "
  242. "(like 'python path/to/setup.py COMMAND').")
  243. raise VersioneerBadRootError(err)
  244. try:
  245. # Certain runtime workflows (setup.py install/develop in a setuptools
  246. # tree) execute all dependencies in a single python process, so
  247. # "versioneer" may be imported multiple times, and python's shared
  248. # module-import table will cache the first one. So we can't use
  249. # os.path.dirname(__file__), as that will find whichever
  250. # versioneer.py was first imported, even in later projects.
  251. me = os.path.realpath(os.path.abspath(__file__))
  252. me_dir = os.path.normcase(os.path.splitext(me)[0])
  253. vsr_dir = os.path.normcase(os.path.splitext(versioneer_py)[0])
  254. if me_dir != vsr_dir:
  255. print("Warning: build in %s is using versioneer.py from %s"
  256. % (os.path.dirname(me), versioneer_py))
  257. except NameError:
  258. pass
  259. return root
  260. def get_config_from_root(root):
  261. """Read the project setup.cfg file to determine Versioneer config."""
  262. # This might raise EnvironmentError (if setup.cfg is missing), or
  263. # configparser.NoSectionError (if it lacks a [versioneer] section), or
  264. # configparser.NoOptionError (if it lacks "VCS="). See the docstring at
  265. # the top of versioneer.py for instructions on writing your setup.cfg .
  266. setup_cfg = os.path.join(root, "setup.cfg")
  267. parser = configparser.SafeConfigParser()
  268. with open(setup_cfg, "r") as f:
  269. parser.readfp(f)
  270. VCS = parser.get("versioneer", "VCS") # mandatory
  271. def get(parser, name):
  272. if parser.has_option("versioneer", name):
  273. return parser.get("versioneer", name)
  274. return None
  275. cfg = VersioneerConfig()
  276. cfg.VCS = VCS
  277. cfg.style = get(parser, "style") or ""
  278. cfg.versionfile_source = get(parser, "versionfile_source")
  279. cfg.versionfile_build = get(parser, "versionfile_build")
  280. cfg.tag_prefix = get(parser, "tag_prefix")
  281. if cfg.tag_prefix in ("''", '""'):
  282. cfg.tag_prefix = ""
  283. cfg.parentdir_prefix = get(parser, "parentdir_prefix")
  284. cfg.verbose = get(parser, "verbose")
  285. return cfg
  286. class NotThisMethod(Exception):
  287. """Exception raised if a method is not valid for the current scenario."""
  288. # these dictionaries contain VCS-specific tools
  289. LONG_VERSION_PY = {}
  290. HANDLERS = {}
  291. def register_vcs_handler(vcs, method): # decorator
  292. """Decorator to mark a method as the handler for a particular VCS."""
  293. def decorate(f):
  294. """Store f in HANDLERS[vcs][method]."""
  295. if vcs not in HANDLERS:
  296. HANDLERS[vcs] = {}
  297. HANDLERS[vcs][method] = f
  298. return f
  299. return decorate
  300. def run_command(commands, args, cwd=None, verbose=False, hide_stderr=False,
  301. env=None):
  302. """Call the given command(s)."""
  303. assert isinstance(commands, list)
  304. p = None
  305. for c in commands:
  306. try:
  307. dispcmd = str([c] + args)
  308. # remember shell=False, so use git.cmd on windows, not just git
  309. p = subprocess.Popen([c] + args, cwd=cwd, env=env,
  310. stdout=subprocess.PIPE,
  311. stderr=(subprocess.PIPE if hide_stderr
  312. else None))
  313. break
  314. except EnvironmentError:
  315. e = sys.exc_info()[1]
  316. if e.errno == errno.ENOENT:
  317. continue
  318. if verbose:
  319. print("unable to run %s" % dispcmd)
  320. print(e)
  321. return None, None
  322. else:
  323. if verbose:
  324. print("unable to find command, tried %s" % (commands,))
  325. return None, None
  326. stdout = p.communicate()[0].strip()
  327. if sys.version_info[0] >= 3:
  328. stdout = stdout.decode()
  329. if p.returncode != 0:
  330. if verbose:
  331. print("unable to run %s (error)" % dispcmd)
  332. print("stdout was %s" % stdout)
  333. return None, p.returncode
  334. return stdout, p.returncode
  335. LONG_VERSION_PY['git'] = '''
  336. # This file helps to compute a version number in source trees obtained from
  337. # git-archive tarball (such as those provided by githubs download-from-tag
  338. # feature). Distribution tarballs (built by setup.py sdist) and build
  339. # directories (produced by setup.py build) will contain a much shorter file
  340. # that just contains the computed version number.
  341. # This file is released into the public domain. Generated by
  342. # versioneer-0.18 (https://github.com/warner/python-versioneer)
  343. """Git implementation of _version.py."""
  344. import errno
  345. import os
  346. import re
  347. import subprocess
  348. import sys
  349. def get_keywords():
  350. """Get the keywords needed to look up the version information."""
  351. # these strings will be replaced by git during git-archive.
  352. # setup.py/versioneer.py will grep for the variable names, so they must
  353. # each be defined on a line of their own. _version.py will just call
  354. # get_keywords().
  355. git_refnames = "%(DOLLAR)sFormat:%%d%(DOLLAR)s"
  356. git_full = "%(DOLLAR)sFormat:%%H%(DOLLAR)s"
  357. git_date = "%(DOLLAR)sFormat:%%ci%(DOLLAR)s"
  358. keywords = {"refnames": git_refnames, "full": git_full, "date": git_date}
  359. return keywords
  360. class VersioneerConfig:
  361. """Container for Versioneer configuration parameters."""
  362. def get_config():
  363. """Create, populate and return the VersioneerConfig() object."""
  364. # these strings are filled in when 'setup.py versioneer' creates
  365. # _version.py
  366. cfg = VersioneerConfig()
  367. cfg.VCS = "git"
  368. cfg.style = "%(STYLE)s"
  369. cfg.tag_prefix = "%(TAG_PREFIX)s"
  370. cfg.parentdir_prefix = "%(PARENTDIR_PREFIX)s"
  371. cfg.versionfile_source = "%(VERSIONFILE_SOURCE)s"
  372. cfg.verbose = False
  373. return cfg
  374. class NotThisMethod(Exception):
  375. """Exception raised if a method is not valid for the current scenario."""
  376. LONG_VERSION_PY = {}
  377. HANDLERS = {}
  378. def register_vcs_handler(vcs, method): # decorator
  379. """Decorator to mark a method as the handler for a particular VCS."""
  380. def decorate(f):
  381. """Store f in HANDLERS[vcs][method]."""
  382. if vcs not in HANDLERS:
  383. HANDLERS[vcs] = {}
  384. HANDLERS[vcs][method] = f
  385. return f
  386. return decorate
  387. def run_command(commands, args, cwd=None, verbose=False, hide_stderr=False,
  388. env=None):
  389. """Call the given command(s)."""
  390. assert isinstance(commands, list)
  391. p = None
  392. for c in commands:
  393. try:
  394. dispcmd = str([c] + args)
  395. # remember shell=False, so use git.cmd on windows, not just git
  396. p = subprocess.Popen([c] + args, cwd=cwd, env=env,
  397. stdout=subprocess.PIPE,
  398. stderr=(subprocess.PIPE if hide_stderr
  399. else None))
  400. break
  401. except EnvironmentError:
  402. e = sys.exc_info()[1]
  403. if e.errno == errno.ENOENT:
  404. continue
  405. if verbose:
  406. print("unable to run %%s" %% dispcmd)
  407. print(e)
  408. return None, None
  409. else:
  410. if verbose:
  411. print("unable to find command, tried %%s" %% (commands,))
  412. return None, None
  413. stdout = p.communicate()[0].strip()
  414. if sys.version_info[0] >= 3:
  415. stdout = stdout.decode()
  416. if p.returncode != 0:
  417. if verbose:
  418. print("unable to run %%s (error)" %% dispcmd)
  419. print("stdout was %%s" %% stdout)
  420. return None, p.returncode
  421. return stdout, p.returncode
  422. def versions_from_parentdir(parentdir_prefix, root, verbose):
  423. """Try to determine the version from the parent directory name.
  424. Source tarballs conventionally unpack into a directory that includes both
  425. the project name and a version string. We will also support searching up
  426. two directory levels for an appropriately named parent directory
  427. """
  428. rootdirs = []
  429. for i in range(3):
  430. dirname = os.path.basename(root)
  431. if dirname.startswith(parentdir_prefix):
  432. return {"version": dirname[len(parentdir_prefix):],
  433. "full-revisionid": None,
  434. "dirty": False, "error": None, "date": None}
  435. else:
  436. rootdirs.append(root)
  437. root = os.path.dirname(root) # up a level
  438. if verbose:
  439. print("Tried directories %%s but none started with prefix %%s" %%
  440. (str(rootdirs), parentdir_prefix))
  441. raise NotThisMethod("rootdir doesn't start with parentdir_prefix")
  442. @register_vcs_handler("git", "get_keywords")
  443. def git_get_keywords(versionfile_abs):
  444. """Extract version information from the given file."""
  445. # the code embedded in _version.py can just fetch the value of these
  446. # keywords. When used from setup.py, we don't want to import _version.py,
  447. # so we do it with a regexp instead. This function is not used from
  448. # _version.py.
  449. keywords = {}
  450. try:
  451. f = open(versionfile_abs, "r")
  452. for line in f.readlines():
  453. if line.strip().startswith("git_refnames ="):
  454. mo = re.search(r'=\s*"(.*)"', line)
  455. if mo:
  456. keywords["refnames"] = mo.group(1)
  457. if line.strip().startswith("git_full ="):
  458. mo = re.search(r'=\s*"(.*)"', line)
  459. if mo:
  460. keywords["full"] = mo.group(1)
  461. if line.strip().startswith("git_date ="):
  462. mo = re.search(r'=\s*"(.*)"', line)
  463. if mo:
  464. keywords["date"] = mo.group(1)
  465. f.close()
  466. except EnvironmentError:
  467. pass
  468. return keywords
  469. @register_vcs_handler("git", "keywords")
  470. def git_versions_from_keywords(keywords, tag_prefix, verbose):
  471. """Get version information from git keywords."""
  472. if not keywords:
  473. raise NotThisMethod("no keywords at all, weird")
  474. date = keywords.get("date")
  475. if date is not None:
  476. # git-2.2.0 added "%%cI", which expands to an ISO-8601 -compliant
  477. # datestamp. However we prefer "%%ci" (which expands to an "ISO-8601
  478. # -like" string, which we must then edit to make compliant), because
  479. # it's been around since git-1.5.3, and it's too difficult to
  480. # discover which version we're using, or to work around using an
  481. # older one.
  482. date = date.strip().replace(" ", "T", 1).replace(" ", "", 1)
  483. refnames = keywords["refnames"].strip()
  484. if refnames.startswith("$Format"):
  485. if verbose:
  486. print("keywords are unexpanded, not using")
  487. raise NotThisMethod("unexpanded keywords, not a git-archive tarball")
  488. refs = set([r.strip() for r in refnames.strip("()").split(",")])
  489. # starting in git-1.8.3, tags are listed as "tag: foo-1.0" instead of
  490. # just "foo-1.0". If we see a "tag: " prefix, prefer those.
  491. TAG = "tag: "
  492. tags = set([r[len(TAG):] for r in refs if r.startswith(TAG)])
  493. if not tags:
  494. # Either we're using git < 1.8.3, or there really are no tags. We use
  495. # a heuristic: assume all version tags have a digit. The old git %%d
  496. # expansion behaves like git log --decorate=short and strips out the
  497. # refs/heads/ and refs/tags/ prefixes that would let us distinguish
  498. # between branches and tags. By ignoring refnames without digits, we
  499. # filter out many common branch names like "release" and
  500. # "stabilization", as well as "HEAD" and "master".
  501. tags = set([r for r in refs if re.search(r'\d', r)])
  502. if verbose:
  503. print("discarding '%%s', no digits" %% ",".join(refs - tags))
  504. if verbose:
  505. print("likely tags: %%s" %% ",".join(sorted(tags)))
  506. for ref in sorted(tags):
  507. # sorting will prefer e.g. "2.0" over "2.0rc1"
  508. if ref.startswith(tag_prefix):
  509. r = ref[len(tag_prefix):]
  510. if verbose:
  511. print("picking %%s" %% r)
  512. return {"version": r,
  513. "full-revisionid": keywords["full"].strip(),
  514. "dirty": False, "error": None,
  515. "date": date}
  516. # no suitable tags, so version is "0+unknown", but full hex is still there
  517. if verbose:
  518. print("no suitable tags, using unknown + full revision id")
  519. return {"version": "0+unknown",
  520. "full-revisionid": keywords["full"].strip(),
  521. "dirty": False, "error": "no suitable tags", "date": None}
  522. @register_vcs_handler("git", "pieces_from_vcs")
  523. def git_pieces_from_vcs(tag_prefix, root, verbose, run_command=run_command):
  524. """Get version from 'git describe' in the root of the source tree.
  525. This only gets called if the git-archive 'subst' keywords were *not*
  526. expanded, and _version.py hasn't already been rewritten with a short
  527. version string, meaning we're inside a checked out source tree.
  528. """
  529. GITS = ["git"]
  530. if sys.platform == "win32":
  531. GITS = ["git.cmd", "git.exe"]
  532. out, rc = run_command(GITS, ["rev-parse", "--git-dir"], cwd=root,
  533. hide_stderr=True)
  534. if rc != 0:
  535. if verbose:
  536. print("Directory %%s not under git control" %% root)
  537. raise NotThisMethod("'git rev-parse --git-dir' returned error")
  538. # if there is a tag matching tag_prefix, this yields TAG-NUM-gHEX[-dirty]
  539. # if there isn't one, this yields HEX[-dirty] (no NUM)
  540. describe_out, rc = run_command(GITS, ["describe", "--tags", "--dirty",
  541. "--always", "--long",
  542. "--match", "%%s*" %% tag_prefix],
  543. cwd=root)
  544. # --long was added in git-1.5.5
  545. if describe_out is None:
  546. raise NotThisMethod("'git describe' failed")
  547. describe_out = describe_out.strip()
  548. full_out, rc = run_command(GITS, ["rev-parse", "HEAD"], cwd=root)
  549. if full_out is None:
  550. raise NotThisMethod("'git rev-parse' failed")
  551. full_out = full_out.strip()
  552. pieces = {}
  553. pieces["long"] = full_out
  554. pieces["short"] = full_out[:7] # maybe improved later
  555. pieces["error"] = None
  556. # parse describe_out. It will be like TAG-NUM-gHEX[-dirty] or HEX[-dirty]
  557. # TAG might have hyphens.
  558. git_describe = describe_out
  559. # look for -dirty suffix
  560. dirty = git_describe.endswith("-dirty")
  561. pieces["dirty"] = dirty
  562. if dirty:
  563. git_describe = git_describe[:git_describe.rindex("-dirty")]
  564. # now we have TAG-NUM-gHEX or HEX
  565. if "-" in git_describe:
  566. # TAG-NUM-gHEX
  567. mo = re.search(r'^(.+)-(\d+)-g([0-9a-f]+)$', git_describe)
  568. if not mo:
  569. # unparseable. Maybe git-describe is misbehaving?
  570. pieces["error"] = ("unable to parse git-describe output: '%%s'"
  571. %% describe_out)
  572. return pieces
  573. # tag
  574. full_tag = mo.group(1)
  575. if not full_tag.startswith(tag_prefix):
  576. if verbose:
  577. fmt = "tag '%%s' doesn't start with prefix '%%s'"
  578. print(fmt %% (full_tag, tag_prefix))
  579. pieces["error"] = ("tag '%%s' doesn't start with prefix '%%s'"
  580. %% (full_tag, tag_prefix))
  581. return pieces
  582. pieces["closest-tag"] = full_tag[len(tag_prefix):]
  583. # distance: number of commits since tag
  584. pieces["distance"] = int(mo.group(2))
  585. # commit: short hex revision ID
  586. pieces["short"] = mo.group(3)
  587. else:
  588. # HEX: no tags
  589. pieces["closest-tag"] = None
  590. count_out, rc = run_command(GITS, ["rev-list", "HEAD", "--count"],
  591. cwd=root)
  592. pieces["distance"] = int(count_out) # total number of commits
  593. # commit date: see ISO-8601 comment in git_versions_from_keywords()
  594. date = run_command(GITS, ["show", "-s", "--format=%%ci", "HEAD"],
  595. cwd=root)[0].strip()
  596. pieces["date"] = date.strip().replace(" ", "T", 1).replace(" ", "", 1)
  597. return pieces
  598. def plus_or_dot(pieces):
  599. """Return a + if we don't already have one, else return a ."""
  600. if "+" in pieces.get("closest-tag", ""):
  601. return "."
  602. return "+"
  603. def render_pep440(pieces):
  604. """Build up version string, with post-release "local version identifier".
  605. Our goal: TAG[+DISTANCE.gHEX[.dirty]] . Note that if you
  606. get a tagged build and then dirty it, you'll get TAG+0.gHEX.dirty
  607. Exceptions:
  608. 1: no tags. git_describe was just HEX. 0+untagged.DISTANCE.gHEX[.dirty]
  609. """
  610. if pieces["closest-tag"]:
  611. rendered = pieces["closest-tag"]
  612. if pieces["distance"] or pieces["dirty"]:
  613. rendered += plus_or_dot(pieces)
  614. rendered += "%%d.g%%s" %% (pieces["distance"], pieces["short"])
  615. if pieces["dirty"]:
  616. rendered += ".dirty"
  617. else:
  618. # exception #1
  619. rendered = "0+untagged.%%d.g%%s" %% (pieces["distance"],
  620. pieces["short"])
  621. if pieces["dirty"]:
  622. rendered += ".dirty"
  623. return rendered
  624. def render_pep440_pre(pieces):
  625. """TAG[.post.devDISTANCE] -- No -dirty.
  626. Exceptions:
  627. 1: no tags. 0.post.devDISTANCE
  628. """
  629. if pieces["closest-tag"]:
  630. rendered = pieces["closest-tag"]
  631. if pieces["distance"]:
  632. rendered += ".post.dev%%d" %% pieces["distance"]
  633. else:
  634. # exception #1
  635. rendered = "0.post.dev%%d" %% pieces["distance"]
  636. return rendered
  637. def render_pep440_post(pieces):
  638. """TAG[.postDISTANCE[.dev0]+gHEX] .
  639. The ".dev0" means dirty. Note that .dev0 sorts backwards
  640. (a dirty tree will appear "older" than the corresponding clean one),
  641. but you shouldn't be releasing software with -dirty anyways.
  642. Exceptions:
  643. 1: no tags. 0.postDISTANCE[.dev0]
  644. """
  645. if pieces["closest-tag"]:
  646. rendered = pieces["closest-tag"]
  647. if pieces["distance"] or pieces["dirty"]:
  648. rendered += ".post%%d" %% pieces["distance"]
  649. if pieces["dirty"]:
  650. rendered += ".dev0"
  651. rendered += plus_or_dot(pieces)
  652. rendered += "g%%s" %% pieces["short"]
  653. else:
  654. # exception #1
  655. rendered = "0.post%%d" %% pieces["distance"]
  656. if pieces["dirty"]:
  657. rendered += ".dev0"
  658. rendered += "+g%%s" %% pieces["short"]
  659. return rendered
  660. def render_pep440_old(pieces):
  661. """TAG[.postDISTANCE[.dev0]] .
  662. The ".dev0" means dirty.
  663. Eexceptions:
  664. 1: no tags. 0.postDISTANCE[.dev0]
  665. """
  666. if pieces["closest-tag"]:
  667. rendered = pieces["closest-tag"]
  668. if pieces["distance"] or pieces["dirty"]:
  669. rendered += ".post%%d" %% pieces["distance"]
  670. if pieces["dirty"]:
  671. rendered += ".dev0"
  672. else:
  673. # exception #1
  674. rendered = "0.post%%d" %% pieces["distance"]
  675. if pieces["dirty"]:
  676. rendered += ".dev0"
  677. return rendered
  678. def render_git_describe(pieces):
  679. """TAG[-DISTANCE-gHEX][-dirty].
  680. Like 'git describe --tags --dirty --always'.
  681. Exceptions:
  682. 1: no tags. HEX[-dirty] (note: no 'g' prefix)
  683. """
  684. if pieces["closest-tag"]:
  685. rendered = pieces["closest-tag"]
  686. if pieces["distance"]:
  687. rendered += "-%%d-g%%s" %% (pieces["distance"], pieces["short"])
  688. else:
  689. # exception #1
  690. rendered = pieces["short"]
  691. if pieces["dirty"]:
  692. rendered += "-dirty"
  693. return rendered
  694. def render_git_describe_long(pieces):
  695. """TAG-DISTANCE-gHEX[-dirty].
  696. Like 'git describe --tags --dirty --always -long'.
  697. The distance/hash is unconditional.
  698. Exceptions:
  699. 1: no tags. HEX[-dirty] (note: no 'g' prefix)
  700. """
  701. if pieces["closest-tag"]:
  702. rendered = pieces["closest-tag"]
  703. rendered += "-%%d-g%%s" %% (pieces["distance"], pieces["short"])
  704. else:
  705. # exception #1
  706. rendered = pieces["short"]
  707. if pieces["dirty"]:
  708. rendered += "-dirty"
  709. return rendered
  710. def render(pieces, style):
  711. """Render the given version pieces into the requested style."""
  712. if pieces["error"]:
  713. return {"version": "unknown",
  714. "full-revisionid": pieces.get("long"),
  715. "dirty": None,
  716. "error": pieces["error"],
  717. "date": None}
  718. if not style or style == "default":
  719. style = "pep440" # the default
  720. if style == "pep440":
  721. rendered = render_pep440(pieces)
  722. elif style == "pep440-pre":
  723. rendered = render_pep440_pre(pieces)
  724. elif style == "pep440-post":
  725. rendered = render_pep440_post(pieces)
  726. elif style == "pep440-old":
  727. rendered = render_pep440_old(pieces)
  728. elif style == "git-describe":
  729. rendered = render_git_describe(pieces)
  730. elif style == "git-describe-long":
  731. rendered = render_git_describe_long(pieces)
  732. else:
  733. raise ValueError("unknown style '%%s'" %% style)
  734. return {"version": rendered, "full-revisionid": pieces["long"],
  735. "dirty": pieces["dirty"], "error": None,
  736. "date": pieces.get("date")}
  737. def get_versions():
  738. """Get version information or return default if unable to do so."""
  739. # I am in _version.py, which lives at ROOT/VERSIONFILE_SOURCE. If we have
  740. # __file__, we can work backwards from there to the root. Some
  741. # py2exe/bbfreeze/non-CPython implementations don't do __file__, in which
  742. # case we can only use expanded keywords.
  743. cfg = get_config()
  744. verbose = cfg.verbose
  745. try:
  746. return git_versions_from_keywords(get_keywords(), cfg.tag_prefix,
  747. verbose)
  748. except NotThisMethod:
  749. pass
  750. try:
  751. root = os.path.realpath(__file__)
  752. # versionfile_source is the relative path from the top of the source
  753. # tree (where the .git directory might live) to this file. Invert
  754. # this to find the root from __file__.
  755. for i in cfg.versionfile_source.split('/'):
  756. root = os.path.dirname(root)
  757. except NameError:
  758. return {"version": "0+unknown", "full-revisionid": None,
  759. "dirty": None,
  760. "error": "unable to find root of source tree",
  761. "date": None}
  762. try:
  763. pieces = git_pieces_from_vcs(cfg.tag_prefix, root, verbose)
  764. return render(pieces, cfg.style)
  765. except NotThisMethod:
  766. pass
  767. try:
  768. if cfg.parentdir_prefix:
  769. return versions_from_parentdir(cfg.parentdir_prefix, root, verbose)
  770. except NotThisMethod:
  771. pass
  772. return {"version": "0+unknown", "full-revisionid": None,
  773. "dirty": None,
  774. "error": "unable to compute version", "date": None}
  775. '''
  776. @register_vcs_handler("git", "get_keywords")
  777. def git_get_keywords(versionfile_abs):
  778. """Extract version information from the given file."""
  779. # the code embedded in _version.py can just fetch the value of these
  780. # keywords. When used from setup.py, we don't want to import _version.py,
  781. # so we do it with a regexp instead. This function is not used from
  782. # _version.py.
  783. keywords = {}
  784. try:
  785. f = open(versionfile_abs, "r")
  786. for line in f.readlines():
  787. if line.strip().startswith("git_refnames ="):
  788. mo = re.search(r'=\s*"(.*)"', line)
  789. if mo:
  790. keywords["refnames"] = mo.group(1)
  791. if line.strip().startswith("git_full ="):
  792. mo = re.search(r'=\s*"(.*)"', line)
  793. if mo:
  794. keywords["full"] = mo.group(1)
  795. if line.strip().startswith("git_date ="):
  796. mo = re.search(r'=\s*"(.*)"', line)
  797. if mo:
  798. keywords["date"] = mo.group(1)
  799. f.close()
  800. except EnvironmentError:
  801. pass
  802. return keywords
  803. @register_vcs_handler("git", "keywords")
  804. def git_versions_from_keywords(keywords, tag_prefix, verbose):
  805. """Get version information from git keywords."""
  806. if not keywords:
  807. raise NotThisMethod("no keywords at all, weird")
  808. date = keywords.get("date")
  809. if date is not None:
  810. # git-2.2.0 added "%cI", which expands to an ISO-8601 -compliant
  811. # datestamp. However we prefer "%ci" (which expands to an "ISO-8601
  812. # -like" string, which we must then edit to make compliant), because
  813. # it's been around since git-1.5.3, and it's too difficult to
  814. # discover which version we're using, or to work around using an
  815. # older one.
  816. date = date.strip().replace(" ", "T", 1).replace(" ", "", 1)
  817. refnames = keywords["refnames"].strip()
  818. if refnames.startswith("$Format"):
  819. if verbose:
  820. print("keywords are unexpanded, not using")
  821. raise NotThisMethod("unexpanded keywords, not a git-archive tarball")
  822. refs = set([r.strip() for r in refnames.strip("()").split(",")])
  823. # starting in git-1.8.3, tags are listed as "tag: foo-1.0" instead of
  824. # just "foo-1.0". If we see a "tag: " prefix, prefer those.
  825. TAG = "tag: "
  826. tags = set([r[len(TAG):] for r in refs if r.startswith(TAG)])
  827. if not tags:
  828. # Either we're using git < 1.8.3, or there really are no tags. We use
  829. # a heuristic: assume all version tags have a digit. The old git %d
  830. # expansion behaves like git log --decorate=short and strips out the
  831. # refs/heads/ and refs/tags/ prefixes that would let us distinguish
  832. # between branches and tags. By ignoring refnames without digits, we
  833. # filter out many common branch names like "release" and
  834. # "stabilization", as well as "HEAD" and "master".
  835. tags = set([r for r in refs if re.search(r'\d', r)])
  836. if verbose:
  837. print("discarding '%s', no digits" % ",".join(refs - tags))
  838. if verbose:
  839. print("likely tags: %s" % ",".join(sorted(tags)))
  840. for ref in sorted(tags):
  841. # sorting will prefer e.g. "2.0" over "2.0rc1"
  842. if ref.startswith(tag_prefix):
  843. r = ref[len(tag_prefix):]
  844. if verbose:
  845. print("picking %s" % r)
  846. return {"version": r,
  847. "full-revisionid": keywords["full"].strip(),
  848. "dirty": False, "error": None,
  849. "date": date}
  850. # no suitable tags, so version is "0+unknown", but full hex is still there
  851. if verbose:
  852. print("no suitable tags, using unknown + full revision id")
  853. return {"version": "0+unknown",
  854. "full-revisionid": keywords["full"].strip(),
  855. "dirty": False, "error": "no suitable tags", "date": None}
  856. @register_vcs_handler("git", "pieces_from_vcs")
  857. def git_pieces_from_vcs(tag_prefix, root, verbose, run_command=run_command):
  858. """Get version from 'git describe' in the root of the source tree.
  859. This only gets called if the git-archive 'subst' keywords were *not*
  860. expanded, and _version.py hasn't already been rewritten with a short
  861. version string, meaning we're inside a checked out source tree.
  862. """
  863. GITS = ["git"]
  864. if sys.platform == "win32":
  865. GITS = ["git.cmd", "git.exe"]
  866. out, rc = run_command(GITS, ["rev-parse", "--git-dir"], cwd=root,
  867. hide_stderr=True)
  868. if rc != 0:
  869. if verbose:
  870. print("Directory %s not under git control" % root)
  871. raise NotThisMethod("'git rev-parse --git-dir' returned error")
  872. # if there is a tag matching tag_prefix, this yields TAG-NUM-gHEX[-dirty]
  873. # if there isn't one, this yields HEX[-dirty] (no NUM)
  874. describe_out, rc = run_command(GITS, ["describe", "--tags", "--dirty",
  875. "--always", "--long",
  876. "--match", "%s*" % tag_prefix],
  877. cwd=root)
  878. # --long was added in git-1.5.5
  879. if describe_out is None:
  880. raise NotThisMethod("'git describe' failed")
  881. describe_out = describe_out.strip()
  882. full_out, rc = run_command(GITS, ["rev-parse", "HEAD"], cwd=root)
  883. if full_out is None:
  884. raise NotThisMethod("'git rev-parse' failed")
  885. full_out = full_out.strip()
  886. pieces = {}
  887. pieces["long"] = full_out
  888. pieces["short"] = full_out[:7] # maybe improved later
  889. pieces["error"] = None
  890. # parse describe_out. It will be like TAG-NUM-gHEX[-dirty] or HEX[-dirty]
  891. # TAG might have hyphens.
  892. git_describe = describe_out
  893. # look for -dirty suffix
  894. dirty = git_describe.endswith("-dirty")
  895. pieces["dirty"] = dirty
  896. if dirty:
  897. git_describe = git_describe[:git_describe.rindex("-dirty")]
  898. # now we have TAG-NUM-gHEX or HEX
  899. if "-" in git_describe:
  900. # TAG-NUM-gHEX
  901. mo = re.search(r'^(.+)-(\d+)-g([0-9a-f]+)$', git_describe)
  902. if not mo:
  903. # unparseable. Maybe git-describe is misbehaving?
  904. pieces["error"] = ("unable to parse git-describe output: '%s'"
  905. % describe_out)
  906. return pieces
  907. # tag
  908. full_tag = mo.group(1)
  909. if not full_tag.startswith(tag_prefix):
  910. if verbose:
  911. fmt = "tag '%s' doesn't start with prefix '%s'"
  912. print(fmt % (full_tag, tag_prefix))
  913. pieces["error"] = ("tag '%s' doesn't start with prefix '%s'"
  914. % (full_tag, tag_prefix))
  915. return pieces
  916. pieces["closest-tag"] = full_tag[len(tag_prefix):]
  917. # distance: number of commits since tag
  918. pieces["distance"] = int(mo.group(2))
  919. # commit: short hex revision ID
  920. pieces["short"] = mo.group(3)
  921. else:
  922. # HEX: no tags
  923. pieces["closest-tag"] = None
  924. count_out, rc = run_command(GITS, ["rev-list", "HEAD", "--count"],
  925. cwd=root)
  926. pieces["distance"] = int(count_out) # total number of commits
  927. # commit date: see ISO-8601 comment in git_versions_from_keywords()
  928. date = run_command(GITS, ["show", "-s", "--format=%ci", "HEAD"],
  929. cwd=root)[0].strip()
  930. pieces["date"] = date.strip().replace(" ", "T", 1).replace(" ", "", 1)
  931. return pieces
  932. def do_vcs_install(manifest_in, versionfile_source, ipy):
  933. """Git-specific installation logic for Versioneer.
  934. For Git, this means creating/changing .gitattributes to mark _version.py
  935. for export-subst keyword substitution.
  936. """
  937. GITS = ["git"]
  938. if sys.platform == "win32":
  939. GITS = ["git.cmd", "git.exe"]
  940. files = [manifest_in, versionfile_source]
  941. if ipy:
  942. files.append(ipy)
  943. try:
  944. me = __file__
  945. if me.endswith(".pyc") or me.endswith(".pyo"):
  946. me = os.path.splitext(me)[0] + ".py"
  947. versioneer_file = os.path.relpath(me)
  948. except NameError:
  949. versioneer_file = "versioneer.py"
  950. files.append(versioneer_file)
  951. present = False
  952. try:
  953. f = open(".gitattributes", "r")
  954. for line in f.readlines():
  955. if line.strip().startswith(versionfile_source):
  956. if "export-subst" in line.strip().split()[1:]:
  957. present = True
  958. f.close()
  959. except EnvironmentError:
  960. pass
  961. if not present:
  962. f = open(".gitattributes", "a+")
  963. f.write("%s export-subst\n" % versionfile_source)
  964. f.close()
  965. files.append(".gitattributes")
  966. run_command(GITS, ["add", "--"] + files)
  967. def versions_from_parentdir(parentdir_prefix, root, verbose):
  968. """Try to determine the version from the parent directory name.
  969. Source tarballs conventionally unpack into a directory that includes both
  970. the project name and a version string. We will also support searching up
  971. two directory levels for an appropriately named parent directory
  972. """
  973. rootdirs = []
  974. for i in range(3):
  975. dirname = os.path.basename(root)
  976. if dirname.startswith(parentdir_prefix):
  977. return {"version": dirname[len(parentdir_prefix):],
  978. "full-revisionid": None,
  979. "dirty": False, "error": None, "date": None}
  980. else:
  981. rootdirs.append(root)
  982. root = os.path.dirname(root) # up a level
  983. if verbose:
  984. print("Tried directories %s but none started with prefix %s" %
  985. (str(rootdirs), parentdir_prefix))
  986. raise NotThisMethod("rootdir doesn't start with parentdir_prefix")
  987. SHORT_VERSION_PY = """
  988. # This file was generated by 'versioneer.py' (0.18) from
  989. # revision-control system data, or from the parent directory name of an
  990. # unpacked source archive. Distribution tarballs contain a pre-generated copy
  991. # of this file.
  992. import json
  993. version_json = '''
  994. %s
  995. ''' # END VERSION_JSON
  996. def get_versions():
  997. return json.loads(version_json)
  998. """
  999. def versions_from_file(filename):
  1000. """Try to determine the version from _version.py if present."""
  1001. try:
  1002. with open(filename) as f:
  1003. contents = f.read()
  1004. except EnvironmentError:
  1005. raise NotThisMethod("unable to read _version.py")
  1006. mo = re.search(r"version_json = '''\n(.*)''' # END VERSION_JSON",
  1007. contents, re.M | re.S)
  1008. if not mo:
  1009. mo = re.search(r"version_json = '''\r\n(.*)''' # END VERSION_JSON",
  1010. contents, re.M | re.S)
  1011. if not mo:
  1012. raise NotThisMethod("no version_json in _version.py")
  1013. return json.loads(mo.group(1))
  1014. def write_to_version_file(filename, versions):
  1015. """Write the given version number to the given _version.py file."""
  1016. os.unlink(filename)
  1017. contents = json.dumps(versions, sort_keys=True,
  1018. indent=1, separators=(",", ": "))
  1019. with open(filename, "w") as f:
  1020. f.write(SHORT_VERSION_PY % contents)
  1021. print("set %s to '%s'" % (filename, versions["version"]))
  1022. def plus_or_dot(pieces):
  1023. """Return a + if we don't already have one, else return a ."""
  1024. if "+" in pieces.get("closest-tag", ""):
  1025. return "."
  1026. return "+"
  1027. def render_pep440(pieces):
  1028. """Build up version string, with post-release "local version identifier".
  1029. Our goal: TAG[+DISTANCE.gHEX[.dirty]] . Note that if you
  1030. get a tagged build and then dirty it, you'll get TAG+0.gHEX.dirty
  1031. Exceptions:
  1032. 1: no tags. git_describe was just HEX. 0+untagged.DISTANCE.gHEX[.dirty]
  1033. """
  1034. if pieces["closest-tag"]:
  1035. rendered = pieces["closest-tag"]
  1036. if pieces["distance"] or pieces["dirty"]:
  1037. rendered += plus_or_dot(pieces)
  1038. rendered += "%d.g%s" % (pieces["distance"], pieces["short"])
  1039. if pieces["dirty"]:
  1040. rendered += ".dirty"
  1041. else:
  1042. # exception #1
  1043. rendered = "0+untagged.%d.g%s" % (pieces["distance"],
  1044. pieces["short"])
  1045. if pieces["dirty"]:
  1046. rendered += ".dirty"
  1047. return rendered
  1048. def render_pep440_pre(pieces):
  1049. """TAG[.post.devDISTANCE] -- No -dirty.
  1050. Exceptions:
  1051. 1: no tags. 0.post.devDISTANCE
  1052. """
  1053. if pieces["closest-tag"]:
  1054. rendered = pieces["closest-tag"]
  1055. if pieces["distance"]:
  1056. rendered += ".post.dev%d" % pieces["distance"]
  1057. else:
  1058. # exception #1
  1059. rendered = "0.post.dev%d" % pieces["distance"]
  1060. return rendered
  1061. def render_pep440_post(pieces):
  1062. """TAG[.postDISTANCE[.dev0]+gHEX] .
  1063. The ".dev0" means dirty. Note that .dev0 sorts backwards
  1064. (a dirty tree will appear "older" than the corresponding clean one),
  1065. but you shouldn't be releasing software with -dirty anyways.
  1066. Exceptions:
  1067. 1: no tags. 0.postDISTANCE[.dev0]
  1068. """
  1069. if pieces["closest-tag"]:
  1070. rendered = pieces["closest-tag"]
  1071. if pieces["distance"] or pieces["dirty"]:
  1072. rendered += ".post%d" % pieces["distance"]
  1073. if pieces["dirty"]:
  1074. rendered += ".dev0"
  1075. rendered += plus_or_dot(pieces)
  1076. rendered += "g%s" % pieces["short"]
  1077. else:
  1078. # exception #1
  1079. rendered = "0.post%d" % pieces["distance"]
  1080. if pieces["dirty"]:
  1081. rendered += ".dev0"
  1082. rendered += "+g%s" % pieces["short"]
  1083. return rendered
  1084. def render_pep440_old(pieces):
  1085. """TAG[.postDISTANCE[.dev0]] .
  1086. The ".dev0" means dirty.
  1087. Eexceptions:
  1088. 1: no tags. 0.postDISTANCE[.dev0]
  1089. """
  1090. if pieces["closest-tag"]:
  1091. rendered = pieces["closest-tag"]
  1092. if pieces["distance"] or pieces["dirty"]:
  1093. rendered += ".post%d" % pieces["distance"]
  1094. if pieces["dirty"]:
  1095. rendered += ".dev0"
  1096. else:
  1097. # exception #1
  1098. rendered = "0.post%d" % pieces["distance"]
  1099. if pieces["dirty"]:
  1100. rendered += ".dev0"
  1101. return rendered
  1102. def render_git_describe(pieces):
  1103. """TAG[-DISTANCE-gHEX][-dirty].
  1104. Like 'git describe --tags --dirty --always'.
  1105. Exceptions:
  1106. 1: no tags. HEX[-dirty] (note: no 'g' prefix)
  1107. """
  1108. if pieces["closest-tag"]:
  1109. rendered = pieces["closest-tag"]
  1110. if pieces["distance"]:
  1111. rendered += "-%d-g%s" % (pieces["distance"], pieces["short"])
  1112. else:
  1113. # exception #1
  1114. rendered = pieces["short"]
  1115. if pieces["dirty"]:
  1116. rendered += "-dirty"
  1117. return rendered
  1118. def render_git_describe_long(pieces):
  1119. """TAG-DISTANCE-gHEX[-dirty].
  1120. Like 'git describe --tags --dirty --always -long'.
  1121. The distance/hash is unconditional.
  1122. Exceptions:
  1123. 1: no tags. HEX[-dirty] (note: no 'g' prefix)
  1124. """
  1125. if pieces["closest-tag"]:
  1126. rendered = pieces["closest-tag"]
  1127. rendered += "-%d-g%s" % (pieces["distance"], pieces["short"])
  1128. else:
  1129. # exception #1
  1130. rendered = pieces["short"]
  1131. if pieces["dirty"]:
  1132. rendered += "-dirty"
  1133. return rendered
  1134. def render(pieces, style):
  1135. """Render the given version pieces into the requested style."""
  1136. if pieces["error"]:
  1137. return {"version": "unknown",
  1138. "full-revisionid": pieces.get("long"),
  1139. "dirty": None,
  1140. "error": pieces["error"],
  1141. "date": None}
  1142. if not style or style == "default":
  1143. style = "pep440" # the default
  1144. if style == "pep440":
  1145. rendered = render_pep440(pieces)
  1146. elif style == "pep440-pre":
  1147. rendered = render_pep440_pre(pieces)
  1148. elif style == "pep440-post":
  1149. rendered = render_pep440_post(pieces)
  1150. elif style == "pep440-old":
  1151. rendered = render_pep440_old(pieces)
  1152. elif style == "git-describe":
  1153. rendered = render_git_describe(pieces)
  1154. elif style == "git-describe-long":
  1155. rendered = render_git_describe_long(pieces)
  1156. else:
  1157. raise ValueError("unknown style '%s'" % style)
  1158. return {"version": rendered, "full-revisionid": pieces["long"],
  1159. "dirty": pieces["dirty"], "error": None,
  1160. "date": pieces.get("date")}
  1161. class VersioneerBadRootError(Exception):
  1162. """The project root directory is unknown or missing key files."""
  1163. def get_versions(verbose=False):
  1164. """Get the project version from whatever source is available.
  1165. Returns dict with two keys: 'version' and 'full'.
  1166. """
  1167. if "versioneer" in sys.modules:
  1168. # see the discussion in cmdclass.py:get_cmdclass()
  1169. del sys.modules["versioneer"]
  1170. root = get_root()
  1171. cfg = get_config_from_root(root)
  1172. assert cfg.VCS is not None, "please set [versioneer]VCS= in setup.cfg"
  1173. handlers = HANDLERS.get(cfg.VCS)
  1174. assert handlers, "unrecognized VCS '%s'" % cfg.VCS
  1175. verbose = verbose or cfg.verbose
  1176. assert cfg.versionfile_source is not None, \
  1177. "please set versioneer.versionfile_source"
  1178. assert cfg.tag_prefix is not None, "please set versioneer.tag_prefix"
  1179. versionfile_abs = os.path.join(root, cfg.versionfile_source)
  1180. # extract version from first of: _version.py, VCS command (e.g. 'git
  1181. # describe'), parentdir. This is meant to work for developers using a
  1182. # source checkout, for users of a tarball created by 'setup.py sdist',
  1183. # and for users of a tarball/zipball created by 'git archive' or github's
  1184. # download-from-tag feature or the equivalent in other VCSes.
  1185. get_keywords_f = handlers.get("get_keywords")
  1186. from_keywords_f = handlers.get("keywords")
  1187. if get_keywords_f and from_keywords_f:
  1188. try:
  1189. keywords = get_keywords_f(versionfile_abs)
  1190. ver = from_keywords_f(keywords, cfg.tag_prefix, verbose)
  1191. if verbose:
  1192. print("got version from expanded keyword %s" % ver)
  1193. return ver
  1194. except NotThisMethod:
  1195. pass
  1196. try:
  1197. ver = versions_from_file(versionfile_abs)
  1198. if verbose:
  1199. print("got version from file %s %s" % (versionfile_abs, ver))
  1200. return ver
  1201. except NotThisMethod:
  1202. pass
  1203. from_vcs_f = handlers.get("pieces_from_vcs")
  1204. if from_vcs_f:
  1205. try:
  1206. pieces = from_vcs_f(cfg.tag_prefix, root, verbose)
  1207. ver = render(pieces, cfg.style)
  1208. if verbose:
  1209. print("got version from VCS %s" % ver)
  1210. return ver
  1211. except NotThisMethod:
  1212. pass
  1213. try:
  1214. if cfg.parentdir_prefix:
  1215. ver = versions_from_parentdir(cfg.parentdir_prefix, root, verbose)
  1216. if verbose:
  1217. print("got version from parentdir %s" % ver)
  1218. return ver
  1219. except NotThisMethod:
  1220. pass
  1221. if verbose:
  1222. print("unable to compute version")
  1223. return {"version": "0+unknown", "full-revisionid": None,
  1224. "dirty": None, "error": "unable to compute version",
  1225. "date": None}
  1226. def get_version():
  1227. """Get the short version string for this project."""
  1228. return get_versions()["version"]
  1229. def get_cmdclass():
  1230. """Get the custom setuptools/distutils subclasses used by Versioneer."""
  1231. if "versioneer" in sys.modules:
  1232. del sys.modules["versioneer"]
  1233. # this fixes the "python setup.py develop" case (also 'install' and
  1234. # 'easy_install .'), in which subdependencies of the main project are
  1235. # built (using setup.py bdist_egg) in the same python process. Assume
  1236. # a main project A and a dependency B, which use different versions
  1237. # of Versioneer. A's setup.py imports A's Versioneer, leaving it in
  1238. # sys.modules by the time B's setup.py is executed, causing B to run
  1239. # with the wrong versioneer. Setuptools wraps the sub-dep builds in a
  1240. # sandbox that restores sys.modules to it's pre-build state, so the
  1241. # parent is protected against the child's "import versioneer". By
  1242. # removing ourselves from sys.modules here, before the child build
  1243. # happens, we protect the child from the parent's versioneer too.
  1244. # Also see https://github.com/warner/python-versioneer/issues/52
  1245. cmds = {}
  1246. # we add "version" to both distutils and setuptools
  1247. from distutils.core import Command
  1248. class cmd_version(Command):
  1249. description = "report generated version string"
  1250. user_options = []
  1251. boolean_options = []
  1252. def initialize_options(self):
  1253. pass
  1254. def finalize_options(self):
  1255. pass
  1256. def run(self):
  1257. vers = get_versions(verbose=True)
  1258. print("Version: %s" % vers["version"])
  1259. print(" full-revisionid: %s" % vers.get("full-revisionid"))
  1260. print(" dirty: %s" % vers.get("dirty"))
  1261. print(" date: %s" % vers.get("date"))
  1262. if vers["error"]:
  1263. print(" error: %s" % vers["error"])
  1264. cmds["version"] = cmd_version
  1265. # we override "build_py" in both distutils and setuptools
  1266. #
  1267. # most invocation pathways end up running build_py:
  1268. # distutils/build -> build_py
  1269. # distutils/install -> distutils/build ->..
  1270. # setuptools/bdist_wheel -> distutils/install ->..
  1271. # setuptools/bdist_egg -> distutils/install_lib -> build_py
  1272. # setuptools/install -> bdist_egg ->..
  1273. # setuptools/develop -> ?
  1274. # pip install:
  1275. # copies source tree to a tempdir before running egg_info/etc
  1276. # if .git isn't copied too, 'git describe' will fail
  1277. # then does setup.py bdist_wheel, or sometimes setup.py install
  1278. # setup.py egg_info -> ?
  1279. # we override different "build_py" commands for both environments
  1280. if "setuptools" in sys.modules:
  1281. from setuptools.command.build_py import build_py as _build_py
  1282. else:
  1283. from distutils.command.build_py import build_py as _build_py
  1284. class cmd_build_py(_build_py):
  1285. def run(self):
  1286. root = get_root()
  1287. cfg = get_config_from_root(root)
  1288. versions = get_versions()
  1289. _build_py.run(self)
  1290. # now locate _version.py in the new build/ directory and replace
  1291. # it with an updated value
  1292. if cfg.versionfile_build:
  1293. target_versionfile = os.path.join(self.build_lib,
  1294. cfg.versionfile_build)
  1295. print("UPDATING %s" % target_versionfile)
  1296. write_to_version_file(target_versionfile, versions)
  1297. cmds["build_py"] = cmd_build_py
  1298. if "cx_Freeze" in sys.modules: # cx_freeze enabled?
  1299. from cx_Freeze.dist import build_exe as _build_exe
  1300. # nczeczulin reports that py2exe won't like the pep440-style string
  1301. # as FILEVERSION, but it can be used for PRODUCTVERSION, e.g.
  1302. # setup(console=[{
  1303. # "version": versioneer.get_version().split("+", 1)[0], # FILEVERSION
  1304. # "product_version": versioneer.get_version(),
  1305. # ...
  1306. class cmd_build_exe(_build_exe):
  1307. def run(self):
  1308. root = get_root()
  1309. cfg = get_config_from_root(root)
  1310. versions = get_versions()
  1311. target_versionfile = cfg.versionfile_source
  1312. print("UPDATING %s" % target_versionfile)
  1313. write_to_version_file(target_versionfile, versions)
  1314. _build_exe.run(self)
  1315. os.unlink(target_versionfile)
  1316. with open(cfg.versionfile_source, "w") as f:
  1317. LONG = LONG_VERSION_PY[cfg.VCS]
  1318. f.write(LONG %
  1319. {"DOLLAR": "$",
  1320. "STYLE": cfg.style,
  1321. "TAG_PREFIX": cfg.tag_prefix,
  1322. "PARENTDIR_PREFIX": cfg.parentdir_prefix,
  1323. "VERSIONFILE_SOURCE": cfg.versionfile_source,
  1324. })
  1325. cmds["build_exe"] = cmd_build_exe
  1326. del cmds["build_py"]
  1327. if 'py2exe' in sys.modules: # py2exe enabled?
  1328. try:
  1329. from py2exe.distutils_buildexe import py2exe as _py2exe # py3
  1330. except ImportError:
  1331. from py2exe.build_exe import py2exe as _py2exe # py2
  1332. class cmd_py2exe(_py2exe):
  1333. def run(self):
  1334. root = get_root()
  1335. cfg = get_config_from_root(root)
  1336. versions = get_versions()
  1337. target_versionfile = cfg.versionfile_source
  1338. print("UPDATING %s" % target_versionfile)
  1339. write_to_version_file(target_versionfile, versions)
  1340. _py2exe.run(self)
  1341. os.unlink(target_versionfile)
  1342. with open(cfg.versionfile_source, "w") as f:
  1343. LONG = LONG_VERSION_PY[cfg.VCS]
  1344. f.write(LONG %
  1345. {"DOLLAR": "$",
  1346. "STYLE": cfg.style,
  1347. "TAG_PREFIX": cfg.tag_prefix,
  1348. "PARENTDIR_PREFIX": cfg.parentdir_prefix,
  1349. "VERSIONFILE_SOURCE": cfg.versionfile_source,
  1350. })
  1351. cmds["py2exe"] = cmd_py2exe
  1352. # we override different "sdist" commands for both environments
  1353. if "setuptools" in sys.modules:
  1354. from setuptools.command.sdist import sdist as _sdist
  1355. else:
  1356. from distutils.command.sdist import sdist as _sdist
  1357. class cmd_sdist(_sdist):
  1358. def run(self):
  1359. versions = get_versions()
  1360. self._versioneer_generated_versions = versions
  1361. # unless we update this, the command will keep using the old
  1362. # version
  1363. self.distribution.metadata.version = versions["version"]
  1364. return _sdist.run(self)
  1365. def make_release_tree(self, base_dir, files):
  1366. root = get_root()
  1367. cfg = get_config_from_root(root)
  1368. _sdist.make_release_tree(self, base_dir, files)
  1369. # now locate _version.py in the new base_dir directory
  1370. # (remembering that it may be a hardlink) and replace it with an
  1371. # updated value
  1372. target_versionfile = os.path.join(base_dir, cfg.versionfile_source)
  1373. print("UPDATING %s" % target_versionfile)
  1374. write_to_version_file(target_versionfile,
  1375. self._versioneer_generated_versions)
  1376. cmds["sdist"] = cmd_sdist
  1377. return cmds
  1378. CONFIG_ERROR = """
  1379. setup.cfg is missing the necessary Versioneer configuration. You need
  1380. a section like:
  1381. [versioneer]
  1382. VCS = git
  1383. style = pep440
  1384. versionfile_source = src/myproject/_version.py
  1385. versionfile_build = myproject/_version.py
  1386. tag_prefix =
  1387. parentdir_prefix = myproject-
  1388. You will also need to edit your setup.py to use the results:
  1389. import versioneer
  1390. setup(version=versioneer.get_version(),
  1391. cmdclass=versioneer.get_cmdclass(), ...)
  1392. Please read the docstring in ./versioneer.py for configuration instructions,
  1393. edit setup.cfg, and re-run the installer or 'python versioneer.py setup'.
  1394. """
  1395. SAMPLE_CONFIG = """
  1396. # See the docstring in versioneer.py for instructions. Note that you must
  1397. # re-run 'versioneer.py setup' after changing this section, and commit the
  1398. # resulting files.
  1399. [versioneer]
  1400. #VCS = git
  1401. #style = pep440
  1402. #versionfile_source =
  1403. #versionfile_build =
  1404. #tag_prefix =
  1405. #parentdir_prefix =
  1406. """
  1407. INIT_PY_SNIPPET = """
  1408. from ._version import get_versions
  1409. __version__ = get_versions()['version']
  1410. del get_versions
  1411. """
  1412. def do_setup():
  1413. """Main VCS-independent setup function for installing Versioneer."""
  1414. root = get_root()
  1415. try:
  1416. cfg = get_config_from_root(root)
  1417. except (EnvironmentError, configparser.NoSectionError,
  1418. configparser.NoOptionError) as e:
  1419. if isinstance(e, (EnvironmentError, configparser.NoSectionError)):
  1420. print("Adding sample versioneer config to setup.cfg",
  1421. file=sys.stderr)
  1422. with open(os.path.join(root, "setup.cfg"), "a") as f:
  1423. f.write(SAMPLE_CONFIG)
  1424. print(CONFIG_ERROR, file=sys.stderr)
  1425. return 1
  1426. print(" creating %s" % cfg.versionfile_source)
  1427. with open(cfg.versionfile_source, "w") as f:
  1428. LONG = LONG_VERSION_PY[cfg.VCS]
  1429. f.write(LONG % {"DOLLAR": "$",
  1430. "STYLE": cfg.style,
  1431. "TAG_PREFIX": cfg.tag_prefix,
  1432. "PARENTDIR_PREFIX": cfg.parentdir_prefix,
  1433. "VERSIONFILE_SOURCE": cfg.versionfile_source,
  1434. })
  1435. ipy = os.path.join(os.path.dirname(cfg.versionfile_source),
  1436. "__init__.py")
  1437. if os.path.exists(ipy):
  1438. try:
  1439. with open(ipy, "r") as f:
  1440. old = f.read()
  1441. except EnvironmentError:
  1442. old = ""
  1443. if INIT_PY_SNIPPET not in old:
  1444. print(" appending to %s" % ipy)
  1445. with open(ipy, "a") as f:
  1446. f.write(INIT_PY_SNIPPET)
  1447. else:
  1448. print(" %s unmodified" % ipy)
  1449. else:
  1450. print(" %s doesn't exist, ok" % ipy)
  1451. ipy = None
  1452. # Make sure both the top-level "versioneer.py" and versionfile_source
  1453. # (PKG/_version.py, used by runtime code) are in MANIFEST.in, so
  1454. # they'll be copied into source distributions. Pip won't be able to
  1455. # install the package without this.
  1456. manifest_in = os.path.join(root, "MANIFEST.in")
  1457. simple_includes = set()
  1458. try:
  1459. with open(manifest_in, "r") as f:
  1460. for line in f:
  1461. if line.startswith("include "):
  1462. for include in line.split()[1:]:
  1463. simple_includes.add(include)
  1464. except EnvironmentError:
  1465. pass
  1466. # That doesn't cover everything MANIFEST.in can do
  1467. # (http://docs.python.org/2/distutils/sourcedist.html#commands), so
  1468. # it might give some false negatives. Appending redundant 'include'
  1469. # lines is safe, though.
  1470. if "versioneer.py" not in simple_includes:
  1471. print(" appending 'versioneer.py' to MANIFEST.in")
  1472. with open(manifest_in, "a") as f:
  1473. f.write("include versioneer.py\n")
  1474. else:
  1475. print(" 'versioneer.py' already in MANIFEST.in")
  1476. if cfg.versionfile_source not in simple_includes:
  1477. print(" appending versionfile_source ('%s') to MANIFEST.in" %
  1478. cfg.versionfile_source)
  1479. with open(manifest_in, "a") as f:
  1480. f.write("include %s\n" % cfg.versionfile_source)
  1481. else:
  1482. print(" versionfile_source already in MANIFEST.in")
  1483. # Make VCS-specific changes. For git, this means creating/changing
  1484. # .gitattributes to mark _version.py for export-subst keyword
  1485. # substitution.
  1486. do_vcs_install(manifest_in, cfg.versionfile_source, ipy)
  1487. return 0
  1488. def scan_setup_py():
  1489. """Validate the contents of setup.py against Versioneer's expectations."""
  1490. found = set()
  1491. setters = False
  1492. errors = 0
  1493. with open("setup.py", "r") as f:
  1494. for line in f.readlines():
  1495. if "import versioneer" in line:
  1496. found.add("import")
  1497. if "versioneer.get_cmdclass()" in line:
  1498. found.add("cmdclass")
  1499. if "versioneer.get_version()" in line:
  1500. found.add("get_version")
  1501. if "versioneer.VCS" in line:
  1502. setters = True
  1503. if "versioneer.versionfile_source" in line:
  1504. setters = True
  1505. if len(found) != 3:
  1506. print("")
  1507. print("Your setup.py appears to be missing some important items")
  1508. print("(but I might be wrong). Please make sure it has something")
  1509. print("roughly like the following:")
  1510. print("")
  1511. print(" import versioneer")
  1512. print(" setup( version=versioneer.get_version(),")
  1513. print(" cmdclass=versioneer.get_cmdclass(), ...)")
  1514. print("")
  1515. errors += 1
  1516. if setters:
  1517. print("You should remove lines like 'versioneer.VCS = ' and")
  1518. print("'versioneer.versionfile_source = ' . This configuration")
  1519. print("now lives in setup.cfg, and should be removed from setup.py")
  1520. print("")
  1521. errors += 1
  1522. return errors
  1523. if __name__ == "__main__":
  1524. cmd = sys.argv[1]
  1525. if cmd == "setup":
  1526. errors = do_setup()
  1527. errors += scan_setup_py()
  1528. if errors:
  1529. sys.exit(1)