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