Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

Polyvers's lib to derive subproject versions from tags on Git monorepos.

Project description

Version: 0.2.2a1
Copyright: 2018 JRC.C4(STU), European Commission (JRC)
license:MIT License

The python 2.7+ library needed by (sub-)projects managed by polyvers cmd 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.


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.


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/ (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:

    from setuptools import setup
        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 engraved sources (ie from an release tag).

    To enable this check without editing the sources, add the following into your $CWD/setup.cfg file:

    polyversion_check_bdist_enabled = true

API usage

An API sample of using also func(polytime()) from within your myproject.git/myproject/ file:

from polyversion import polyversion, polytime  # no hack, dependency already installed

__version__ = polyversion()  # project assumed equal to this module-name: 'myproject'
__updated__ = polytime()


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:

user@host:~/ $ polyversion --help
Describe the version of a *polyvers* projects from git tags.

    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/", line 18, in main*sys.argv[1:])
  File "/pyenv/site-packages/pvlib/polyversion/", line 340, in run
    res = polyversion(args[0], repo_path=os.curdir)
  File "/pyenv/site-packages/pvlib/polyversion/", line 262, in polyversion
    pvtag = _my_run(cmd, cwd=repo_path)
  File "/pyenv/site-packages/pvlib/polyversion/", 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):

user@host:~/polyvers.git (master) $
user@host:~/polyvers.git (master) $ ./bin/ polyversion
polyversion: 0.0.2a9
user@host:~/polyvers.git (master) $ python ./bin/ --help
user@host:~/polyvers.git (master) $ python ./bin/ -m polyversion  -v
version: 0.0.2a9
user@host:~/polyvers.git (master) $ PYTHONPATH=./bin/  python -m polyversion  -V
version: 0.0.2a9
updated: Thu, 24 May 2018 02:47:37 +0300

For the rest, consult the polyvers project:

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for polyversion, version 0.2.2a1
Filename, size File type Python version Upload date Hashes
Filename, size polyversion-0.2.2a1-py2.py3-none-any.whl (21.4 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size polyversion-0.2.2a1.tar.gz (19.5 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page