Metadata-Version: 2.1
Name: pygitversion
Version: 0.1.0
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
Description: ============
        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']``
           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(__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.
        
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
