Metadata-Version: 2.1
Name: pygitversion
Version: 0.1.2
Summary: Robustly generate exact git hashes for python packages
Home-page: https://github.com/RadioAstronomySoftwareGroup/pygitversion
Author: Radio Astronomy Software Group
Author-email: steven.g.murray@asu.edu
License: MIT
Project-URL: Documentation, https://pygitversion.readthedocs.io/
Project-URL: Changelog, https://pygitversion.readthedocs.io/en/latest/changelog.html
Project-URL: Issue Tracker, https://github.com/RadioAstronomySoftwareGroup/pygitversion/issues
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Unix
Classifier: Operating System :: POSIX
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Utilities
Requires-Python: >=3.5
Provides-Extra: dev
Requires-Dist: pre-commit ; extra == 'dev'
Requires-Dist: tox ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: black ; extra == 'dev'
Requires-Dist: twine ; extra == 'dev'

============
pygitversion
============

**Robustly generate exact git hashes for python packages**



Installation
============

::

    pip install pygitversion

Usage
=====
The point of pygitversion is to enable you to robustly create your package with exact
git version information, rather than *just* a simple version specifier.

It does *not replace* the semantic version specifier of your package, but rather
complements it. pygitversion provides the tools necessary to *always* have git
information available in a Python package (whether the actual repo is available or
not).

To use in your package, follow these steps:

1. If ``pyproject.toml`` does not exist in your package, create it.
2. Add the key ``[build-system]`` to ``pyproject.toml``, and add ``requires = ['pygitversion','setuptools>40.8.0','wheel']``
   to the key.
3. Ensure that ``__init__.py`` contains the correct semantic ``__version__`` specifier.
4. In `setup.py`, add the following::

    import pygitversion
    pygitversion.write_git_info_file(<your_installed_package_name>)

5. Ensure the package has a ``MANIFEST.in``, and that it includes ``<package>/GIT_INFO``.
6. The git version of the module may then be accessed by doing::

    import pygitversion
    pygitversion.construct_version_info(<package_name>)

7. It is recommended (but not necessary) that ``__init__.py`` contain::

    import pygitversion
    GIT_VERSION = pygitversion.construct_version_info(__name__)

Cases Addressed
---------------
There are various ways a package can be installed, and ``pygitversion`` attempts to ensure
that in each case, the git version is available. The following assumes the above
steps have been followed in your package.

1. Package cloned and installed via ``pip install .``: a ``GIT_INFO`` file is created and
   installed due to ``MANIFEST.in``. That ``GIT_INFO`` file is found whenever the package
   is loaded.
2. Package cloned and installed via ``pip install -e .``: a ``GIT_INFO`` file is created
   in the repo, and sym-linked when the package is imported.
3. Package installed directly from hosted source control via ``pip install git+git:...``:
   Unsure?
4. Package installed from PyPI (``pip install <package>``): the process of building the
   sdist and bdist to upload to PyPI inherently bundles the most current ``GIT_INFO``
   file as part of the build, and this is installed with the package.


Development
===========

To run the all tests run::

    tox



Changelog
=========

0.1.0 (2019-09-04)
------------------

* First release on PyPI.


