vcversioner-1.14.1.1/0000755000076500000240000000000012327300722015173 5ustar habnabitstaff00000000000000vcversioner-1.14.1.1/MANIFEST.in0000644000076500000240000000002412166157007016734 0ustar habnabitstaff00000000000000include version.txt vcversioner-1.14.1.1/PKG-INFO0000644000076500000240000003163012327300722016273 0ustar habnabitstaff00000000000000Metadata-Version: 1.1 Name: vcversioner Version: 1.14.1.1 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``. 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 ``--``. 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 ``.dev`` 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.dev3``. 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 ``/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.2 Classifier: Programming Language :: Python :: 3.3 Classifier: Topic :: Software Development :: Version Control vcversioner-1.14.1.1/README.rst0000644000076500000240000002351012327140724016667 0ustar habnabitstaff00000000000000.. 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``. 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 ``--``. 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 ``.dev`` 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.dev3``. 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 ``/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`` vcversioner-1.14.1.1/setup.cfg0000644000076500000240000000007312327300722017014 0ustar habnabitstaff00000000000000[egg_info] tag_build = tag_date = 0 tag_svn_revision = 0 vcversioner-1.14.1.1/setup.py0000644000076500000240000000233012166156741016716 0ustar habnabitstaff00000000000000# Copyright (c) Aaron Gallagher <_@habnab.it> # See COPYING for details. import vcversioner # not this again from setuptools import setup with open('README.rst', 'r') as infile: long_description = infile.read() setup( name='vcversioner', version=vcversioner.find_version().version, description='Use version control tags to discover version numbers', long_description=long_description, author='Aaron Gallagher', author_email='_@habnab.it', url='https://github.com/habnabit/vcversioner', classifiers=[ 'Development Status :: 3 - Alpha', 'Intended Audience :: Developers', 'License :: OSI Approved :: ISC License (ISCL)', 'Operating System :: OS Independent', 'Programming Language :: Python :: 2', 'Programming Language :: Python :: 2.6', 'Programming Language :: Python :: 2.7', 'Programming Language :: Python :: 3', 'Programming Language :: Python :: 3.2', 'Programming Language :: Python :: 3.3', 'Topic :: Software Development :: Version Control', ], license='ISC', py_modules=['vcversioner'], entry_points={ 'distutils.setup_keywords': ['vcversioner = vcversioner:setup'], }, ) vcversioner-1.14.1.1/vcversioner.egg-info/0000755000076500000240000000000012327300722021232 5ustar habnabitstaff00000000000000vcversioner-1.14.1.1/vcversioner.egg-info/dependency_links.txt0000644000076500000240000000000112327300721025277 0ustar habnabitstaff00000000000000 vcversioner-1.14.1.1/vcversioner.egg-info/entry_points.txt0000644000076500000240000000007412327300721024530 0ustar habnabitstaff00000000000000[distutils.setup_keywords] vcversioner = vcversioner:setup vcversioner-1.14.1.1/vcversioner.egg-info/PKG-INFO0000644000076500000240000003163012327300721022331 0ustar habnabitstaff00000000000000Metadata-Version: 1.1 Name: vcversioner Version: 1.14.1.1 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``. 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 ``--``. 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 ``.dev`` 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.dev3``. 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 ``/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.2 Classifier: Programming Language :: Python :: 3.3 Classifier: Topic :: Software Development :: Version Control vcversioner-1.14.1.1/vcversioner.egg-info/SOURCES.txt0000644000076500000240000000035412327300721023117 0ustar habnabitstaff00000000000000MANIFEST.in README.rst setup.py vcversioner.py version.txt vcversioner.egg-info/PKG-INFO vcversioner.egg-info/SOURCES.txt vcversioner.egg-info/dependency_links.txt vcversioner.egg-info/entry_points.txt vcversioner.egg-info/top_level.txtvcversioner-1.14.1.1/vcversioner.egg-info/top_level.txt0000644000076500000240000000001412327300721023756 0ustar habnabitstaff00000000000000vcversioner vcversioner-1.14.1.1/vcversioner.py0000644000076500000240000002242412327300660020117 0ustar habnabitstaff00000000000000# Copyright (c) 2013-2014, Aaron Gallagher <_@habnab.it> # # Permission to use, copy, modify, and/or distribute this software for any # purpose with or without fee is hereby granted, provided that the above # copyright notice and this permission notice appear in all copies. # # THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH # REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY # AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, # INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM # LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR # OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR # PERFORMANCE OF THIS SOFTWARE. """Simplify your python project versioning. In-depth docs online: https://vcversioner.readthedocs.org/en/latest/ Code online: https://github.com/habnabit/vcversioner """ from __future__ import print_function, unicode_literals import collections import os import subprocess import warnings Version = collections.namedtuple('Version', 'version commits sha') _print = print def print(*a, **kw): _print('vcversioner:', *a, **kw) def _fix_path(p): "Translate ``/``s into the right path separator." return p.replace('/', os.sep) _vcs_args_by_path = [ ('%(root)s/.git', ( 'git', '--git-dir', '%(root)s/.git', 'describe', '--tags', '--long')), ('%(root)s/.hg', ( 'hg', 'log', '-R', '%(root)s', '-r', '.', '--template', '{latesttag}-{latesttagdistance}-hg{node|short}')), ] def find_version(include_dev_version=True, root='%(pwd)s', version_file='%(root)s/version.txt', version_module_paths=(), git_args=None, vcs_args=None, decrement_dev_version=None, Popen=subprocess.Popen, open=open): """Find an appropriate version number from version control. 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. The default behavior is to write out a ``version.txt`` file which contains the VCS output, for systems where the appropriate VCS is not installed or there is no VCS metadata directory present. ``version.txt`` can (and probably should!) be packaged in release tarballs by way of the ``MANIFEST.in`` file. :param include_dev_version: By default, if there are any commits after the most recent tag (as reported by the VCS), that number will be included in the version number as a ``.dev`` suffix. For example, if the most recent tag is ``1.0`` and there have been three commits after that tag, the version number will be ``1.0.dev3``. This behavior can be disabled by setting this parameter to ``False``. :param root: The directory of the repository root. The default value is the current working directory, since when running ``setup.py``, this is often (but not always) the same as the current working directory. Standard substitutions are performed on this value. :param version_file: The name of the file where version information will be saved. Reading and writing version files can be disabled altogether by setting this parameter to ``None``. Standard substitutions are performed on this value. :param version_module_paths: A list of python modules which will be automatically generated containing ``__version__`` and ``__sha__`` attributes. For example, with ``package/_version.py`` as a version module path, ``package/__init__.py`` could do ``from package._version import __version__, __sha__``. :param git_args: **Deprecated.** Please use *vcs_args* instead. :param vcs_args: The command to run to get a version. By default, this is automatically guessed from directories present in the repository root. Specify this as a list of string arguments including the program to run, e.g. ``['git', 'describe']``. Standard substitutions are performed on each value in the provided list. :param decrement_dev_version: If ``True``, subtract one from the number of commits after the most recent tag. This is primarily for hg, as hg requires a commit to make a tag. If the VCS used is hg (i.e. the revision starts with ``'hg'``) and *decrement_dev_version* is not specified as ``False``, *decrement_dev_version* will be set to ``True``. :param Popen: Defaults to ``subprocess.Popen``. This is for testing. :param open: Defaults to ``open``. This is for testing. *root*, *version_file*, and *git_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 ``\``. ``vcversioner`` will perform automatic VCS detection with the following directories, in order, and run the specified commands. ``%(root)s/.git`` ``git --git-dir %(root)s/.git describe --tags --long``. ``--git-dir`` is used to prevent contamination from git repositories which aren't the git repository of your project. ``%(root)s/.hg`` ``hg log -R %(root)s -r . --template '{latesttag}-{latesttagdistance}-hg{node|short}'``. ``-R`` is similarly used to prevent contamination. """ substitutions = {'pwd': os.getcwd()} substitutions['root'] = root % substitutions def substitute(val): return _fix_path(val % substitutions) if version_file is not None: version_file = substitute(version_file) if git_args is not None: warnings.warn( 'passing `git_args is deprecated; please use vcs_args', DeprecationWarning) vcs_args = git_args if vcs_args is None: for path, args in _vcs_args_by_path: if os.path.exists(substitute(path)): vcs_args = args break raw_version = None vcs_output = [] if vcs_args is not None: vcs_args = [substitute(arg) for arg in vcs_args] # try to pull the version from some VCS, or (perhaps) fall back on a # previously-saved version. try: proc = Popen(vcs_args, stdout=subprocess.PIPE, stderr=subprocess.PIPE) except OSError: pass else: stdout, stderr = proc.communicate() raw_version = stdout.strip().decode() vcs_output = stderr.decode().splitlines() version_source = 'VCS' failure = '%r failed' % (vcs_args,) else: failure = 'no VCS could be detected in %(root)r' % substitutions def show_vcs_output(): if not vcs_output: return print('-- VCS output follows --') for line in vcs_output: print(line) # VCS failed if the string is empty if not raw_version: if version_file is None: print('%s.' % (failure,)) show_vcs_output() raise SystemExit(2) elif not os.path.exists(version_file): print("%s and %r isn't present." % (failure, version_file)) print("are you installing from a github tarball?") show_vcs_output() raise SystemExit(2) with open(version_file, 'rb') as infile: raw_version = infile.read().decode() version_source = repr(version_file) # try to parse the version into something usable. try: tag_version, commits, sha = raw_version.rsplit('-', 2) except ValueError: print("%r (from %s) couldn't be parsed into a version." % ( raw_version, version_source)) show_vcs_output() raise SystemExit(2) # remove leading 'v' tag_version = tag_version.lstrip('v') if version_file is not None: with open(version_file, 'w') as outfile: outfile.write(raw_version) if sha.startswith('hg') and decrement_dev_version is None: decrement_dev_version = True if decrement_dev_version: commits = str(int(commits) - 1) if commits == '0' or not include_dev_version: version = tag_version else: version = '%s.dev%s' % (tag_version, commits) for path in version_module_paths: with open(path, 'w') as outfile: outfile.write(""" # This file is automatically generated by setup.py. __version__ = {0} __sha__ = {1} __revision__ = {1} """.format(repr(version).lstrip('u'), repr(sha).lstrip('u'))) return Version(version, commits, sha) def setup(dist, attr, value): """A hook for simplifying ``vcversioner`` use from distutils. This hook, when installed properly, allows vcversioner to automatically run when specifying a ``vcversioner`` argument to ``setup``. For example:: from setuptools import setup setup( setup_requires=['vcversioner'], vcversioner={}, ) The parameter to the ``vcversioner`` argument is a dict of keyword arguments which :func:`find_version` will be called with. """ dist.version = dist.metadata.version = find_version(**value).version vcversioner-1.14.1.1/version.txt0000644000076500000240000000002312327300721017413 0ustar habnabitstaff000000000000001.14.1.1-0-g8541e1b