: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)):

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'],
     ...
 )
```
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

FAQs

What is polyversion?

Is polyversion well maintained?

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install