Poetry Setuptools SCM Plugin

poetry-setuptools-scm-plugin is a Poetry plugin that uses setuptools_scm to extract a package version from git or Mercurial metadata.

Installation

Add the plugin to Poetry:

poetry self add poetry-setuptools-scm-plugin

Usage

To enable it in your Poetry-based project add the following to your pyproject.toml:

[tool.setuptools_scm]

With this the version specified in version of the tool.poetry section in pyproject.toml is ignored and the version derived by setuptools_scm is used instead. See its documentation on further configuration options.

Note

The Poetry team believes "that the version is one of the static metadata and the pyproject.toml is the single source of truth for it".

Similar tools

• poetry-version-plugin: This plugin allows to read the version either from a git tag or a version definition in an __init__.py file. To my latest knowledge it cannot derive dev-versions from git.
• poetry-dynamic-versioning: Instead of using setuptools_scm this plugin utilizes Dunami which comes with even more features than setuptools_scm.

Development

Prerequisites

• Python >=3.10, can for example be installed with pyenv:

  pyenv install 3.10
  pyenv local 3.10

• Poetry >=1.2

• the latest release of the plugin installed in poetry

  poetry self add poetry-setuptools-scm-plugin

Setup

poetry install

To simplify running commands in the Poetry environment:

poetry shell

The following section assume that the commands are executed from such a Poetry shell.

Test

pytest

Check

ruff check

Build

poetry build