Metadata-Version: 2.1
Name: pygitversion
Version: 0.1.7
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>=0.1.6','setuptools>40.8.0','wheel']`` to the key.
3. Ensure that ``__init__.py`` contains the correct semantic ``__version__`` specifier
   (eg. `__version__ = 0.1.0`).
4. In `setup.py`, add the following::

       import pygitversion
       pygitversion.write_git_info_file(__file__, <rel_path_to_package>)

5. Ensure the package has a ``MANIFEST.in``, and that it includes at least::

       include <package>/GIT_INFO

6. The git version of the module may then be accessed inside your package by doing::

    import pygitversion
    pygitversion.construct_version_info(my_package_name)

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

    import pygitversion
    GIT_VERSION = pygitversion.construct_version_info(__name__)

8. It is also recommended to add ``GIT_INFO`` to your ``.gitignore``.

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. **This will break iff the installed files on your PYTHONPATH are directly
   modified, which should never be the case.**
2. Package cloned and installed via ``pip install -e .``: the module that is imported
   refers to the actual git repo (via symlink), and the git info is created at import
   time directly from the repo. This still works if the code is updated in place.
3. Package installed directly from hosted source control via ``pip install git+git:...``:
   When pip installs the package, it first fully clones the repo, which means the GIT_INFO
   file is built and added to the install, just as in point 1.
4. Package installed from PyPI (``pip install <package>``): the process of building the
   sdist and bdist to upload to PyPI inherently re-builds and bundles the ``GIT_INFO``
   file as part of the build, and this is installed with the package. Developers should
   be careful to build/upload only clean repositories.


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

To run the all tests run::

    tox



Changelog
=========

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

* First release on PyPI.


