bucket_57/python-vcversioner

   1 # Buildsheet autogenerated by ravenadm tool -- Do not edit.
   2
   3 NAMEBASE=               python-vcversioner
   4 VERSION=                2.16.0.0
   5 KEYWORDS=               python devel
   6 VARIANTS=               py27 py38 py37
   7 SDESC[py37]=            Extract version from version control tag (PY 37)
   8 SDESC[py38]=            Extract version from version control tag (PY 38)
   9 SDESC[py27]=            Extract version from version control tag (PY 27)
  10 HOMEPAGE=               https://github.com/habnabit/vcversioner
  11 CONTACT=                Python_Automaton[python@ironwolf.systems]
  12
  13 DOWNLOAD_GROUPS=        main
  14 SITES[main]=            PYPI/v/vcversioner
  15 DISTFILE[1]=            vcversioner-2.16.0.0.tar.gz:main
  16 DF_INDEX=               1
  17 SPKGS[py37]=            single
  18 SPKGS[py38]=            single
  19 SPKGS[py27]=            single
  20
  21 OPTIONS_AVAILABLE=      PY27 PY38 PY37
  22 OPTIONS_STANDARD=       none
  23 VOPTS[py37]=            PY27=OFF PY38=OFF PY37=ON
  24 VOPTS[py38]=            PY27=OFF PY38=ON PY37=OFF
  25 VOPTS[py27]=            PY27=ON PY38=OFF PY37=OFF
  26
  27 DISTNAME=               vcversioner-2.16.0.0
  28
  29 GENERATED=              yes
  30
  31 [PY37].USES_ON=                         python:py37
  32
  33 [PY38].USES_ON=                         python:py38
  34
  35 [PY27].USES_ON=                         python:py27
  36
  37 [FILE:3360:descriptions/desc.single]
  38 .. image:: https://travis-ci.org/habnabit/vcversioner.png
  39
  40 ===========
  41 vcversioner
  42 ===========
  43
  44 `Elevator pitch`_: you can write a ``setup.py`` with no version information
  45 specified, and vcversioner will find a recent, properly-formatted VCS tag
  46 and
  47 extract a version from it.
  48
  49 It's much more convenient to be able to use your version control system's
  50 tagging mechanism to derive a version number than to have to duplicate that
  51 information all over the place. I eventually ended up copy-pasting the same
  52 code into a couple different ``setup.py`` files just to avoid duplicating
  53 version information. But, copy-pasting is dumb and unit testing
  54 ``setup.py``
  55 files is hard. This code got factored out into vcversioner.
  56
  57
  58 Basic usage
  59 -----------
  60
  61 vcversioner installs itself as a setuptools hook, which makes its use
  62 exceedingly simple::
  63
  64   from setuptools import setup
  65
  66   setup(
  67       # [...]
  68       setup_requires=['vcversioner'],
  69       vcversioner={},
  70   )
  71
  72 The presence of a ``vcversioner`` argument automagically activates
  73 vcversioner
  74 and updates the project's version. The parameter to the ``vcversioner``
  75 argument can also be a dict of keyword arguments which |find_version|
  76 will be called with.
  77
  78 To allow tarballs to be distributed without requiring a ``.git`` (or
  79 ``.hg``,
  80 etc.) directory, vcversioner will also write out a file named (by default)
  81 ``version.txt``. Then, if there is no VCS program or the program is unable
  82 to
  83 find any version information, vcversioner will read version information
  84 from
  85 the ``version.txt`` file. However, this file needs to be included in a
  86 distributed tarball, so the following line should be added to
  87 ``MANIFEST.in``::
  88
  89   include version.txt
  90
  91 This isn't necessary if ``setup.py`` will always be run from a checkout,
  92 but
  93 otherwise is essential for vcversioner to know what version to use.
  94
  95 The name ``version.txt`` also can be changed by specifying the
  96 ``version_file``
  97 parameter. For example::
  98
  99   from setuptools import setup
 100
 101   setup(
 102       # [...]
 103       setup_requires=['vcversioner'],
 104       vcversioner={
 105           'version_file': 'custom_version.txt',
 106       },
 107   )
 108
 109 For compatibility with `semantic versioning`_, ``vcversioner`` will strip
 110 leading ``'v'``\ s  from version tags. That is, the tag ``v1.0`` will be
 111 treated as if it was ``1.0``.
 112
 113 Other prefixes can be specified to be stripped by using the
 114 ``strip_prefix``
 115 argument to vcversioner. For compatibility with ``git-dch``, one could
 116 specify
 117 the ``strip_prefix`` as ``'debian/'``.
 118
 119
 120 Non-hook usage
 121 --------------
 122
 123 It's not necessary to depend on vcversioner; while `pip`_ will take care of
 124 dependencies automatically, sometimes having a self-contained project is
 125 simpler. vcversioner is a single file which is easy to add to a project.
 126 Simply
 127 copy the entire ``vcversioner.py`` file adjacent to the existing
 128 ``setup.py``
 129 file and update the usage slightly::
 130
 131   from setuptools import setup
 132   import vcversioner
 133
 134   setup(
 135       # [...]
 136       version=vcversioner.find_version().version,
 137   )
 138
 139 This is necessary because the ``vcversioner`` distutils hook won't be
 140 available.
 141
 142
 143 Version modules
 144 ---------------
 145
 146 ``setup.py`` isn't the only place that version information gets
 147 duplicated. By
 148 generating a version module, the ``__init__.py`` file of a package can
 149 import
 150 version information. For example, with a package named ``spam``::
 151
 152   from setuptools import setup
 153
 154
 155 [FILE:106:distinfo]
 156 dae60c17a479781f44a4010701833f1829140b1eeccd258762a74974aa06e19b         9024 vcversioner-2.16.0.0.tar.gz
 157