upgrade to versioneer-0.9

Author: warner

ecdsa/_version.py

@@ -6,7 +6,7 @@
 # that just contains the computed version number.
 
 # This file is released into the public domain. Generated by
-# versioneer-0.8+ (https://github.com/warner/python-versioneer)
+# versioneer-0.9 (https://github.com/warner/python-versioneer)
 
 # these strings will be replaced by git during git-archive
 git_refnames = "$Format:%d$"

versioneer.py

@@ -1,5 +1,5 @@
 
-# Version: 0.8+
+# Version: 0.9
 
 """
 The Versioneer
@@ -22,21 +22,19 @@
 
 ## Quick Install
 
-* `pip install versioneer` somewhere to your $PATH
-* run `versioneerer` in your source tree: installs `versioneer.py`
-* follow the instructions below
+* `pip install versioneer` to somewhere to your $PATH
+* run `versioneer-installer` in your source tree: this installs `versioneer.py`
+* follow the instructions below (also in the `versioneer.py` docstring)
 
 ## Version Identifiers
 
 Source trees come from a variety of places:
 
-* a version-control system checkout (mostly used by developers or eager
-  followers)
+* a version-control system checkout (mostly used by developers)
 * a nightly tarball, produced by build automation
-* a snapshot tarball, produced by a web-based VCS browser, like hgweb or
-  github's "tarball from tag" feature
-* a release tarball, produced by "setup.py sdist", and perhaps distributed
-  through PyPI
+* a snapshot tarball, produced by a web-based VCS browser, like github's
+  "tarball from tag" feature
+* a release tarball, produced by "setup.py sdist", distributed through PyPI
 
 Within each source tree, the version identifier (either a string or a number,
 this tool is format-agnostic) can come from a variety of places:
@@ -68,26 +66,26 @@
 ## Theory of Operation
 
 Versioneer works by adding a special `_version.py` file into your source
-tree, where your `__init__.py` can import it. This _version.py knows how to
+tree, where your `__init__.py` can import it. This `_version.py` knows how to
 dynamically ask the VCS tool for version information at import time. However,
 when you use "setup.py build" or "setup.py sdist", `_version.py` in the new
 copy is replaced by a small static file that contains just the generated
 version data.
 
 `_version.py` also contains `$Revision$` markers, and the installation
-process marks _version.py to have this marker rewritten with a tag name
+process marks `_version.py` to have this marker rewritten with a tag name
 during the "git archive" command. As a result, generated tarballs will
 contain enough information to get the proper version.
 
 
 ## Installation
 
-You will need to provide versioneer with a few configuration variables:
+First, decide on values for the following configuration variables:
 
 * `versionfile_source`:
 
   A project-relative pathname into which the generated version strings should
-  be written. This is usually a _version.py next to your project's main
+  be written. This is usually a `_version.py` next to your project's main
   `__init__.py` file. If your project uses `src/myproject/__init__.py`, this
   should be `src/myproject/_version.py`. This file should be checked in to
   your VCS as usual: the copy created below by 'setup.py update_files' will
@@ -116,34 +114,36 @@
   all unpacked tarball filenames. If your tarball unpacks into
   'myproject-1.2.0', this should be 'myproject-'.
 
-This tool provides one script, named `versioneer.py`.
+This tool provides one script, named `versioneer-installer`. That script does
+one thing: write a copy of `versioneer.py` into the current directory.
 
 To versioneer-enable your project:
 
-* 1: copy `versioneer.py` into the top of your source tree
+* 1: Run `versioneer-installer` to copy `versioneer.py` into the top of your
+  source tree.
 
-* 2: add the following lines to the top of your `setup.py`, with suitable
-     values for each configuration setting:
+* 2: add the following lines to the top of your `setup.py`, with the
+  configuration values you decided earlier:
 
-    import versioneer
-    versioneer.versionfile_source = 'src/myproject/_version.py'
-    versioneer.versionfile_build = 'myproject/_version.py'
-    versioneer.tag_prefix = '' # tags are like 1.2.0
-    versioneer.parentdir_prefix = 'myproject-' # dirname like 'myproject-1.2.0'
+        import versioneer
+        versioneer.versionfile_source = 'src/myproject/_version.py'
+        versioneer.versionfile_build = 'myproject/_version.py'
+        versioneer.tag_prefix = '' # tags are like 1.2.0
+        versioneer.parentdir_prefix = 'myproject-' # dirname like 'myproject-1.2.0'
 
 * 3: add the following arguments to the setup() call in your setup.py:
 
-    version=versioneer.get_version(),
-    cmdclass=versioneer.get_cmdclass(),
+        version=versioneer.get_version(),
+        cmdclass=versioneer.get_cmdclass(),
 
-* 4: run `setup.py update_files`, which will create `_version.py`, and will
-     modify your `__init__.py` to define `__version__` (by calling a function
-     from `_version.py`)
+* 4: now run `setup.py update_files`, which will create `_version.py`, and
+  will modify your `__init__.py` to define `__version__` (by calling a
+  function from `_version.py`)
 
 * 5: modify your MANIFEST.in to include `versioneer.py` in sdist tarballs
 
 * 6: commit these changes to your VCS. `update_files` will mark both
-     `versioneer.py` and the generated `_version.py` for addition.
+  `versioneer.py` and the generated `_version.py` for addition.
 
 ## Post-Installation Usage
 
@@ -167,6 +167,48 @@
 report "unknown" until your tree has at least one tag in its history. This
 restriction will be fixed eventually (see issue #12).
 
+## Version-String Flavors
+
+Code which uses Versioneer can learn about its version string at runtime by
+importing `_version` from your main `__init__.py` file and running the
+`get_versions()` function. From the "outside" (e.g. in `setup.py`), you can
+import the top-level `versioneer.py` and run `get_versions()`.
+
+Both functions return a dictionary with different keys for different flavors
+of the version string:
+
+* `['version']`: condensed tag+distance+shortid+dirty identifier. For git,
+  this uses the output of `git describe --tags --dirty --always` but strips
+  the tag_prefix. For example "0.11-2-g1076c97-dirty" indicates that the tree
+  is like the "1076c97" commit but has uncommitted changes ("-dirty"), and
+  that this commit is two revisions ("-2-") beyond the "0.11" tag. For
+  released software (exactly equal to a known tag), the identifier will only
+  contain the stripped tag, e.g. "0.11".
+
+* `['full']`: detailed revision identifier. For Git, this is the full SHA1
+  commit id, followed by "-dirty" if the tree contains uncommitted changes,
+  e.g. "1076c978a8d3cfc70f408fe5974aa6c092c949ac-dirty".
+
+Some variants are more useful than others. Including `full` in a bug report
+should allow developers to reconstruct the exact code being tested (or
+indicate the presence of local changes that should be shared with the
+developers). `version` is suitable for display in an "about" box or a CLI
+`--version` output: it can be easily compared against release notes and lists
+of bugs fixed in various releases.
+
+In the future, this will also include a
+[PEP-0440](http://legacy.python.org/dev/peps/pep-0440/) -compatible flavor
+(e.g. `1.2.post0.dev123`). This loses a lot of information (and has no room
+for a hash-based revision id), but is safe to use in a `setup.py`
+"`version=`" argument. It also enables tools like *pip* to compare version
+strings and evaluate compatibility constraint declarations.
+
+The `setup.py update_files` command adds the following text to your
+`__init__.py` to place a basic version in `YOURPROJECT.__version__`:
+
+    from ._version import get_versions
+    __version = get_versions()['version']
+    del get_versions
 
 ## Future Directions
 
@@ -185,7 +227,8 @@
 ## License
 
 To make Versioneer easier to embed, all its code is hereby released into the
-public domain. The `_version.py` that it creates is also in the public domain.
+public domain. The `_version.py` that it creates is also in the public
+domain.
 
 """
 
@@ -210,7 +253,7 @@
 # that just contains the computed version number.
 
 # This file is released into the public domain. Generated by
-# versioneer-0.8+ (https://github.com/warner/python-versioneer)
+# versioneer-0.9 (https://github.com/warner/python-versioneer)
 
 # these strings will be replaced by git during git-archive
 git_refnames = "%(DOLLAR)sFormat:%%d%(DOLLAR)s"
@@ -588,7 +631,7 @@ def do_vcs_install(versionfile_source, ipy):
     run_command(GITS, ["add", "--"] + files)
 
 SHORT_VERSION_PY = """
-# This file was generated by 'versioneer.py' (0.8+) from
+# This file was generated by 'versioneer.py' (0.9) from
 # revision-control system data, or from the parent directory name of an
 # unpacked source archive. Distribution tarballs contain a pre-generated copy
 # of this file.