Skip to main content

Plugin for Poetry to enable dynamic versioning based on VCS tags for semver

Project description

Dynamic versioning plugin for Poetry

License: MIT

This package is a plugin for Poetry to enable dynamic versioning based on tags in your version control system, powered by Scmver.

Since Poetry does not yet officially support plugins (refer to this issue) as of the time of writing on 2019-12-10, this package takes some novel liberties to make the functionality possible. As soon as official support lands, this plugin will be updated to do things the official way.


Python 3.5 (or newer) and Poetry 0.12.1 (or newer) are required.

  • Run pip install poetry-scmver
  • Add this to your pyproject.toml:
    enable = true

Note that you must install the plugin in your global Python installation, not as a dependency in pyroject.toml, because the virtual environment that Poetry creates cannot see Poetry itself and therefore cannot patch it.


In your pyproject.toml file, you may configure the following options:

[tool.scmver]: General options.

  • enable: Boolean. Default: false. Since the plugin has to be installed globally, this setting is an opt-in per project. This setting will likely be removed once plugins are officially supported.

  • root: A path of the working directory. Default: '.'

  • spec: A version specifier to construct the public version indentifiers. It will be incremented by the number of commits from the latest tag.

    • major: It will increment the major version.
    • minor: It will increment the minor version.
    • micro or patch: It will increment the micro (patch) version.
    • post: It will increment the post-release segment.
    • It will increment the development release segment after incrementing the major version by 1.
    • It will increment the development release segment after incrementing the minor version by 1.
    • or It will increment the development release segment after incrementing the micro (patch) version by 1.

    Default: 'post'

  • local: A string to construct the local version identifiers.

    Available keywords:

    • {distance}
    • {reivison}
    • {branch}
    • {utc} - Return value of datetime.datetime.utcnow()
    • {local} - Return value of

    Default: '{local:%Y-%m-%d}'

  • version: A regular expression object to extract the version from SCM tags. It should contain the version group.

  • write_to: A path to a file which will be generated using template.

  • template: A format string which is used by write_to. Available keywords:

    • {version}
    • {revision}
    • {branch}
  • bazaar.tag: A regular expression pattern to filter tags.

  • fossil.tag: A regular expression pattern to filter tags.

  • git.tag: It will be passed to git describe as --match.

  • mercurial.tag: A regular expression pattern to filter tags.

  • subversion.tag: A regular expression pattern to filter tags.

  • subversion.trunk: A relative repository path of the trunk directory. Default: 'trunk'

  • `subversion.branches: A relative repository path of the directory where branches are located. Default: 'branches'

  • subversion.tags: A relative repository path of the directory where tags are located. Default: 'tags'

Simple example:

enable = true
write_to = ""


In order to side-load plugin functionality into Poetry, this package does the following:

  • Upon installation, it delivers a zzz_poetry_semver.pth file to your Python site-packages directory. This forces Python to automatically load the plugin after all other modules have been loaded (or at least those alphabetically prior to zzz).
  • It patches builtins.__import__ so that, whenever the first import from Poetry finishes, poetry.console.main will be patched. The reason we have to wait for a Poetry import is in case you've used the script, in which case there is a gap between when Python is fully loaded and when ~/.poetry/bin/poetry adds the Poetry lib folder to the PYTHONPATH.
  • The patched version of poetry.console.main will then, when called, additionally patch either poetry.poetry.Poetry.create() or poetry.factory.Factory.create_poetry() (depending on your Poetry version) to replace the version from your pyproject.toml file with the dynamically generated version.


See Changelog


See License

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

poetry-scmver-0.1.2.dev6.tar.gz (6.2 kB view hashes)

Uploaded source

Built Distribution

poetry_scmver-0.1.2.dev6-py3-none-any.whl (6.0 kB view hashes)

Uploaded py3

Supported by

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