/usr/lib/python2.7/dist-packages/vcversioner-2.16.0.0.egg-info/PKG-INFO is in python-vcversioner 2.16.0.0-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 | Metadata-Version: 1.1
Name: vcversioner
Version: 2.16.0.0
Summary: Use version control tags to discover version numbers
Home-page: https://github.com/habnabit/vcversioner
Author: Aaron Gallagher
Author-email: _@habnab.it
License: ISC
Description: .. image:: https://travis-ci.org/habnabit/vcversioner.png
===========
vcversioner
===========
`Elevator pitch`_: you can write a ``setup.py`` with no version information
specified, and vcversioner will find a recent, properly-formatted VCS tag and
extract a version from it.
It's much more convenient to be able to use your version control system's
tagging mechanism to derive a version number than to have to duplicate that
information all over the place. I eventually ended up copy-pasting the same
code into a couple different ``setup.py`` files just to avoid duplicating
version information. But, copy-pasting is dumb and unit testing ``setup.py``
files is hard. This code got factored out into vcversioner.
Basic usage
-----------
vcversioner installs itself as a setuptools hook, which makes its use
exceedingly simple::
from setuptools import setup
setup(
# [...]
setup_requires=['vcversioner'],
vcversioner={},
)
The presence of a ``vcversioner`` argument automagically activates vcversioner
and updates the project's version. The parameter to the ``vcversioner``
argument can also be a dict of keyword arguments which |find_version|
will be called with.
To allow tarballs to be distributed without requiring a ``.git`` (or ``.hg``,
etc.) directory, vcversioner will also write out a file named (by default)
``version.txt``. Then, if there is no VCS program or the program is unable to
find any version information, vcversioner will read version information from
the ``version.txt`` file. However, this file needs to be included in a
distributed tarball, so the following line should be added to ``MANIFEST.in``::
include version.txt
This isn't necessary if ``setup.py`` will always be run from a checkout, but
otherwise is essential for vcversioner to know what version to use.
The name ``version.txt`` also can be changed by specifying the ``version_file``
parameter. For example::
from setuptools import setup
setup(
# [...]
setup_requires=['vcversioner'],
vcversioner={
'version_file': 'custom_version.txt',
},
)
For compatibility with `semantic versioning`_, ``vcversioner`` will strip
leading ``'v'``\ s from version tags. That is, the tag ``v1.0`` will be
treated as if it was ``1.0``.
Other prefixes can be specified to be stripped by using the ``strip_prefix``
argument to vcversioner. For compatibility with ``git-dch``, one could specify
the ``strip_prefix`` as ``'debian/'``.
Non-hook usage
--------------
It's not necessary to depend on vcversioner; while `pip`_ will take care of
dependencies automatically, sometimes having a self-contained project is
simpler. vcversioner is a single file which is easy to add to a project. Simply
copy the entire ``vcversioner.py`` file adjacent to the existing ``setup.py``
file and update the usage slightly::
from setuptools import setup
import vcversioner
setup(
# [...]
version=vcversioner.find_version().version,
)
This is necessary because the ``vcversioner`` distutils hook won't be
available.
Version modules
---------------
``setup.py`` isn't the only place that version information gets duplicated. By
generating a version module, the ``__init__.py`` file of a package can import
version information. For example, with a package named ``spam``::
from setuptools import setup
setup(
# [...]
setup_requires=['vcversioner'],
vcversioner={
'version_module_paths': ['spam/_version.py'],
},
)
This will generate a ``spam/_version.py`` file that defines ``__version__`` and
``__revision__``. Then, in ``spam/__init__.py``::
from spam._version import __version__, __revision__
Since this acts like (and *is*) a regular python module, changing
``MANIFEST.in`` is not required.
Customizing VCS commands
------------------------
vcversioner by default tries to detect which VCS is being used and picks a
command to run based on that. For git, that is ``git --git-dir %(root)s/.git
describe --tags --long``. For hg, that is ``hg log -R %(root)s -r . --template
'{latesttag}-{latesttagdistance}-hg{node|short}'``.
Any command should output a string that describes the current commit in the
format ``1.0-0-gdeadbeef``. Specifically, that is ``<version number>-<number of
commits between the current commit and the version tagged commit>-<revision>``.
The revision should have a VCS-specific prefix, e.g. ``g`` for git and ``hg``
for hg.
However, sometimes this isn't sufficient. If someone wanted to only use
annotated tags, the git command could be amended like so::
from setuptools import setup
setup(
# [...]
setup_requires=['vcversioner'],
vcversioner={
'vcs_args': ['git', 'describe', '--long'],
},
)
The ``vcs_args`` parameter must always be a list of strings, which will not be
interpreted by the shell. This is the same as what ``subprocess.Popen``
expects.
This argument used to be spelled ``git_args`` until support for multiple VCS
systems was added.
Development versions
--------------------
vcversioner can also automatically make a version that corresponds to a commit
that isn't itself tagged. Following `PEP 386`_, this is done by adding a
``.post`` suffix to the version specified by a tag on an earlier commit. For
example, if the current commit is three revisions past the ``1.0`` tag, the
computed version will be ``1.0.post3``.
This behavior can be disabled by setting the ``include_dev_version`` parameter
to ``False``. In that case, the aforementioned untagged commit's version would
be just ``1.0``.
Since hg requires a commit to make a tag, there's a parameter
``decrement_dev_version`` to subtract one from the number of commits after the
most recent tag. If the VCS used is detected to be hg (i.e. the revision starts
with ``'hg'``) and ``decrement_dev_version`` is not specified as ``False``,
``decrement_dev_version`` will be automatically set to ``True``.
Project roots
-------------
In order to prevent contamination from other source repositories, vcversioner
in the 1.x version series will only look in the project root directory for
repositories. The project root defaults to the current working directory, which
is often the case when running setup.py. This can be changed by specifying the
``root`` parameter. Someone concerned with being able to run setup.py from
directories other than the directory containing setup.py should determine the
project root from ``__file__`` in setup.py::
from setuptools import setup
import os
setup(
# [...]
setup_requires=['vcversioner'],
vcversioner={
'root': os.path.dirname(os.path.abspath(__file__)),
},
)
To get the same behavior in the 0.x version series, ``vcs_args`` can be set to
include the ``--git-dir`` flag::
from setuptools import setup
setup(
# [...]
setup_requires=['vcversioner'],
vcversioner={
vcs_args=['git', '--git-dir', '%(root)s/.git', 'describe',
'--tags', '--long'],
},
)
By default, ``version.txt`` is also read from the project root.
Substitutions
~~~~~~~~~~~~~
As seen above, *root*, *version_file*, and *vcs_args* each support some
substitutions:
``%(root)s``
The value provided for *root*. This is not available for the *root*
parameter itself.
``%(pwd)s``
The current working directory.
``/`` will automatically be translated into the correct path separator for the
current platform, such as ``:`` or ``\``.
Sphinx documentation
--------------------
`Sphinx`_ documentation is yet another place where version numbers get
duplicated. Fortunately, since sphinx configuration is python code, vcversioner
can be used there too. Assuming vcversioner is installed system-wide, this is
quite easy. Since Sphinx is typically run with the current working directory as
``<your project root>/docs``, it's necessary to tell vcversioner where the
project root is. Simply change your ``conf.py`` to include::
import vcversioner
version = release = vcversioner.find_version(root='..').version
This assumes that your project root is the parent directory of the current
working directory. A slightly longer version which is a little more robust
would be::
import vcversioner, os
version = release = vcversioner.find_version(
root=os.path.dirname(os.path.dirname(os.path.abspath(__file__)))).version
This version is more robust because it finds the project root not relative to
the current working directory but instead relative to the ``conf.py`` file.
If vcversioner is bundled with your project instead of relying on it being
installed, you might have to add the following to your ``conf.py`` before
``import vcversioner``::
import sys, os
sys.path.insert(0, os.path.abspath('..'))
This line, or something with the same effect, is sometimes already present when
using the sphinx ``autodoc`` extension.
Read the Docs
~~~~~~~~~~~~~
Using vcversioner is even possible when building documentation on `Read the
Docs`_. If vcversioner is bundled with your project, nothing further needs to
be done. Otherwise, you need to tell Read the Docs to install vcversioner
before it builds the documentation. This means using a ``requirements.txt``
file.
If your project is already set up to install dependencies with a
``requirements.txt`` file, add ``vcversioner`` to it. Otherwise, create a
``requirements.txt`` file. Assuming your documentation is in a ``docs``
subdirectory of the main project directory, create ``docs/requirements.txt``
containing a ``vcversioner`` line.
Then, make the following changes to your project's configuration: (Project
configuration is edited at e.g.
https://readthedocs.org/dashboard/vcversioner/edit/)
- Check the checkbox under **Use virtualenv**.
- If there was no ``requirements.txt`` previously, set the **Requirements
file** to the newly-created one, e.g. ``docs/requirements.txt``.
.. _Elevator pitch: http://en.wikipedia.org/wiki/Elevator_pitch
.. _pip: https://pypi.python.org/pypi/pip
.. _PEP 386: http://www.python.org/dev/peps/pep-0386/
.. _Sphinx: http://sphinx-doc.org
.. _Read the Docs: https://readthedocs.org/
.. _semantic versioning: http://semver.org/
.. |find_version| replace:: ``find_version``
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Topic :: Software Development :: Version Control
|