Skip to main content

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

Project description







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.


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

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.

Source Distribution

polyversion-0.2.2a1.tar.gz (19.5 kB view hashes)

Uploaded source

Built Distribution

polyversion-0.2.2a1-py2.py3-none-any.whl (21.4 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page