Skip to main content

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

Project description

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

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.

Quickstart

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:

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

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:

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

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

For the rest, consult the polyvers project: https://polyvers.readthedocs.io

Project details


Download files

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

Filename, size & hash SHA256 hash help File type Python version Upload date
polyversion-0.2.2a1-py2.py3-none-any.whl (21.4 kB) Copy SHA256 hash SHA256 Wheel py2.py3

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page