Metadata-Version: 2.1
Name: polyversion
Version: 0.2.2a1
Summary: Polyvers's lib to derive subproject versions from tags on Git monorepos.
Home-page: https://github.com/jrcstu/polyvers
Author: Kostis Anagnostopoulos
Author-email: ankostis@gmail.com
License: MIT
Download-URL: https://pypi.org/project/polyversion/
Project-URL: Documentation, http://polyvers.readthedocs.io/en/latest/usage-pvlib.html
Project-URL: Source, https://github.com/jrcstu/polyvers
Project-URL: Tracker, https://github.com/jrcstu/polyvers/issues
Description: ==================================================================
        Polyversion: derive subproject versions from tags on Git monorepos
        ==================================================================
        
        ..  https://img.shields.io/pypi/v/polyversion.svg
            :alt: Deployed in PyPi?
            :target: https://pypi.org/pypi/polyversion
        
        ..  https://img.shields.io/travis/JRCSTU/polyvers.svg
            :alt: TravisCI (linux) build ok?
            :target: https://travis-ci.org/JRCSTU/polyvers
        
        ..  https://ci.appveyor.com/api/projects/status/lyyjtmit5ti7tg1n?svg=true
            :alt: Apveyor (Windows) build?
            :scale: 100%
            :target: https://ci.appveyor.com/project/ankostis/polyvers
        
        ..  https://img.shields.io/coveralls/github/JRCSTU/polyvers.svg
            :alt: Test-case coverage report
            :scale: 100%
            :target: https://coveralls.io/github/JRCSTU/polyvers?branch=master&service=github
        
        ..  https://readthedocs.org/projects/polyvers/badge/?version=latest
            :target: https://polyvers.readthedocs.io/en/latest/?badge=latest
            :alt: Auto-generated documentation status
        
        ..  https://api.codacy.com/project/badge/Grade/11b2545fd0264f1cab4c862998833503
            :target: https://www.codacy.com/app/ankostis/polyvers_jrc
            :alt: Code quality metric
        
        .. _coord-start:
        
        :version:       0.2.2a1
        :updated:       2018-08-07T13:30:07.616687
        :Documentation: http://polyvers.readthedocs.io/en/latest/usage-pvlib.html
        :repository:    https://github.com/JRCSTU/polyvers
        :pypi-repo:     https://pypi.org/project/polyversion/
        :copyright:     2018 JRC.C4(STU), European Commission (`JRC <https://ec.europa.eu/jrc/>`_)
        :license:       `MIT License <https://choosealicense.com/licenses/mit/>`_
        
        The python 2.7+ library needed by (sub-)projects managed by `polyvers cmd
        <https://github.com/JRCSTU/polyvers>`_ to derive their version-ids on runtime from Git.
        
        Specifically, the configuration file ``.polyvers.yaml`` is NOT read -
        you have to repeat any non-default configurations as function/method keywords
        when calling this API.
        
        Here only a very rudimentary documentation is provided - consult `polyvers`
        documents provided in the link above.
        
        .. Note::
            Only this library is (permissive) MIT-licensed, so it can be freely vendorized
            by any program - the respective `polyvers` command-line tool is
            "copylefted" under EUPLv1.2.
        
        .. _coord-end:
        
        Quickstart
        ==========
        .. _usage:
        
        There are 4 ways to use this library:
          - As a **setuptools plugin**;
          - through its Python-API (to dynamically version your project);
          - through its barebone cmdline tool: ``polyversion``
            (installation required);
          - through the standalone executable wheel: ``bin/pvlib.run``
            (no installation, but sources required; behaves identically
            to ``polyversion`` command).
        
        
        *setuptools* usage
        ------------------
        currentmodule: polyversion
        
        The `polyversion` library function as a *setuptools* "plugin", and
        adds two new ``setup()`` keywords for deriving subproject versions
        from PKG-INFO or git tags  (see func(`polyversion.init_plugin_kw`)):
        
        1. keyword: ``polyversion --> (bool | dict)``
            When a dict, its keys roughly mimic those in func(`polyversion()`),
            and can be used like this:
        
            .. code-block:: python
        
                from setuptools import setup
        
                setup(
                    project='myname',
                    version=''              # omit (or None) to abort if cannot auto-version
                    polyversion={           # dict or bool
                        'mono_project': True, # false by default
                        ...  # See `polyversion.init_plugin_kw()` for more keys.
                    },
                    setup_requires=[..., 'polyversion'],
                    ...
                )
        
        2. keyword: ``polyversion_check_bdist_enabled --> bool``
            When it is true, the **bdist-check** is enabled, and any `bdist_*` setup-commands
            (e.g. ``bdist_wheel``) will abort if not run from **engrave**\d sources
            (ie from an **release tag**).
        
            To enable this check without editing the sources, add the following into
            your ``$CWD/setup.cfg`` file::
        
                [global]
                polyversion_check_bdist_enabled = true
                ...
        
        
        API usage
        ---------
        An API sample of using also func(`polytime()`) from within your
        ``myproject.git/myproject/__init__.py`` file:
        
        .. code-block:: python
        
            from polyversion import polyversion, polytime  # no hack, dependency already installed
        
            __version__ = polyversion()  # project assumed equal to this module-name: 'myproject'
            __updated__ = polytime()
            ...
        
        .. Tip::
           Depending on your repo's *versioning scheme* (eg you have a **mono-project** repo,
           with version-tags simply like ``vX.Y.Z``), you must add in both invocations
           of func(`polyversion.polyversion()`) above the kw-arg ``mono_project=True``.
        
        
        Console usage
        -------------
        The typical command-line usage of this library (assuming you don't want to install
        the full blown `polyvers` command tool) is given below:
        
        .. code-block:: console
        
        
            user@host:~/ $ polyversion --help
            Describe the version of a *polyvers* projects from git tags.
        
            USAGE:
                polyversion [PROJ-1] ...
                polyversion [-v | -V ]     # print my version information
        
            user@host:~/ $ polyversion polyversion    # fails, not in a git repo
            b'fatal: not a git repository (or any of the parent directories): .git\n'
              cmd: ['git', 'describe', '--match=cf-v*']
            Traceback (most recent call last):
              File "/pyenv/site-packages/pvlib/polyversion/__main__.py", line 18, in main
                polyversion.run(*sys.argv[1:])
              File "/pyenv/site-packages/pvlib/polyversion/__init__.py", line 340, in run
                res = polyversion(args[0], repo_path=os.curdir)
              File "/pyenv/site-packages/pvlib/polyversion/__init__.py", line 262, in polyversion
                pvtag = _my_run(cmd, cwd=repo_path)
              File "/pyenv/site-packages/pvlib/polyversion/__init__.py", line 106, in _my_run
                raise sbp.CalledProcessError(proc.returncode, cmd)
            subprocess.CalledProcessError: Command '['git', 'describe', '--match=cf-v*']' returned non-zero exit status 128.
        
            user@host:~/ $ cd polyvers.git
            user@host:~/polyvers.git (dev) $ polyversion polyvers polyversion
            polyvers: 0.0.2a10
            polyversion: 0.0.2a9
        
        Standalone wheel
        ----------------
        Various ways to use the standalone wheel from *bash*
        (these will still work without having installed anything):
        
        .. code-block:: console
        
            user@host:~/polyvers.git (master) $
            user@host:~/polyvers.git (master) $ ./bin/pvlib.run polyversion
            polyversion: 0.0.2a9
            user@host:~/polyvers.git (master) $ python ./bin/pvlib.run --help
            ...
            user@host:~/polyvers.git (master) $ python ./bin/pvlib.run -m polyversion  -v
            version: 0.0.2a9
            user@host:~/polyvers.git (master) $ PYTHONPATH=./bin/pvlib.run  python -m polyversion  -V
            version: 0.0.2a9
            updated: Thu, 24 May 2018 02:47:37 +0300
        
        
        .. Note:
           You cannot define what is your *versioning-scheme* from console tools - it is
           your repo's ``.polyvers.yaml` configuration file that defines whether
           you have a *mono-project* or a *monorepo* (version-tags like ``proj-vX.Y.Z``).
        
        
        For the rest, consult the *polyvers* project: https://polyvers.readthedocs.io
        
Keywords: version-management,configuration-management,versioning,git,monorepo,tool,library
Platform: any
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Provides-Extra: test
