# Poetry Setuptools SCM Plugin
poetry-setuptools-scm-plugin is a [Poetry](https://python-poetry.org/) plugin that uses
[setuptools_scm](https://github.com/pypa/setuptools_scm) to extract a package version from [git](https://git-scm.com/)
or [Mercurial](https://www.mercurial-scm.org/) metadata.
## Installation
Add the plugin to Poetry:
```bash
poetry self add poetry-setuptools-scm-plugin
```
## Usage
To enable it in your Poetry-based project add the following to your `pyproject.toml`:
```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](https://setuptools-scm.readthedocs.io/)
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"](https://github.com/python-poetry/poetry/issues/4971#issuecomment-1013930810).
## Similar tools
- [poetry-version-plugin](https://github.com/tiangolo/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](https://github.com/mtkennerly/poetry-dynamic-versioning):
Instead of using
setuptools_scm this plugin utilizes [Dunami](https://github.com/mtkennerly/dunamai) which
comes with even more features than setuptools_scm.
## Development
### Prerequisites
- Python >=3.10, can for example be installed with [pyenv](https://github.com/pyenv/pyenv):
```bash
pyenv install 3.10
pyenv local 3.10
```
- [Poetry](https://python-poetry.org/docs/#installation) >=1.2
- the latest release of the plugin installed in poetry
```bash
poetry self add poetry-setuptools-scm-plugin
```
### Setup
```bash
poetry install
```
To simplify running commands in the Poetry environment:
```bash
poetry shell
```
The following section assume that the commands are executed from such a Poetry shell.
### Test
```bash
pytest
```
### Check
```bash
ruff check
```
### Build
```bash
poetry build
```
Raw data
{
"_id": null,
"home_page": "https://github.com/volkerstampa/poetry-setuptools-scm-plugin",
"name": "poetry-setuptools-scm-plugin",
"maintainer": "Volker Stampa",
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": "Volker.Stampa@gmx.net",
"keywords": "poetry, plugin, version, git",
"author": "Volker Stampa",
"author_email": "Volker.Stampa@gmx.net",
"download_url": "https://files.pythonhosted.org/packages/dc/da/d4d3b5f64d7b2d0269435abf664bede4b9aad1d5a959e27681b4f51b2fee/poetry_setuptools_scm_plugin-0.2.0.tar.gz",
"platform": null,
"description": "# Poetry Setuptools SCM Plugin\n\npoetry-setuptools-scm-plugin is a [Poetry](https://python-poetry.org/) plugin that uses\n[setuptools_scm](https://github.com/pypa/setuptools_scm) to extract a package version from [git](https://git-scm.com/)\nor [Mercurial](https://www.mercurial-scm.org/) metadata.\n\n## Installation\n\nAdd the plugin to Poetry:\n\n```bash\npoetry self add poetry-setuptools-scm-plugin\n```\n\n## Usage\n\nTo enable it in your Poetry-based project add the following to your `pyproject.toml`:\n\n```toml\n[tool.setuptools_scm]\n```\n\nWith this the version specified in `version` of the `tool.poetry` section in `pyproject.toml` is ignored and\nthe version derived by `setuptools_scm` is used instead. See [its documentation](https://setuptools-scm.readthedocs.io/)\non further configuration options.\n\n> [!NOTE]\n> The Poetry team believes\n> [\"that the version is one of the static metadata and the pyproject.toml is the single source of truth for it\"](https://github.com/python-poetry/poetry/issues/4971#issuecomment-1013930810).\n\n## Similar tools\n\n- [poetry-version-plugin](https://github.com/tiangolo/poetry-version-plugin/):\n This plugin allows to read the version either from a git tag or a version definition in an `__init__.py` file. To my\n latest knowledge it cannot derive dev-versions from git.\n- [poetry-dynamic-versioning](https://github.com/mtkennerly/poetry-dynamic-versioning):\n Instead of using\n setuptools_scm this plugin utilizes [Dunami](https://github.com/mtkennerly/dunamai) which\n comes with even more features than setuptools_scm.\n\n## Development\n\n### Prerequisites\n\n- Python >=3.10, can for example be installed with [pyenv](https://github.com/pyenv/pyenv):\n\n ```bash\n pyenv install 3.10\n pyenv local 3.10\n ```\n\n- [Poetry](https://python-poetry.org/docs/#installation) >=1.2\n\n- the latest release of the plugin installed in poetry\n ```bash\n poetry self add poetry-setuptools-scm-plugin\n ```\n\n### Setup\n\n```bash\npoetry install\n```\n\nTo simplify running commands in the Poetry environment:\n\n```bash\npoetry shell\n```\n\nThe following section assume that the commands are executed from such a Poetry shell.\n\n### Test\n\n```bash\npytest\n```\n\n### Check\n\n```bash\nruff check\n```\n\n### Build\n\n```bash\npoetry build\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Poetry Plugin that uses setuptools-scm to determine version",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/volkerstampa/poetry-setuptools-scm-plugin"
},
"split_keywords": [
"poetry",
" plugin",
" version",
" git"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8bd865a67e425ccb42b3a1167a0a91f247d71e18d6688b0807715ddf656a9971",
"md5": "947480bc26fed0d52da4191b4b790da8",
"sha256": "46f5ffa6e97b5a98963288b7a9368c62d0ebcdd6a3e063abfcdbdaad5146fa58"
},
"downloads": -1,
"filename": "poetry_setuptools_scm_plugin-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "947480bc26fed0d52da4191b4b790da8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 7598,
"upload_time": "2024-06-23T13:56:33",
"upload_time_iso_8601": "2024-06-23T13:56:33.610885Z",
"url": "https://files.pythonhosted.org/packages/8b/d8/65a67e425ccb42b3a1167a0a91f247d71e18d6688b0807715ddf656a9971/poetry_setuptools_scm_plugin-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dcdad4d3b5f64d7b2d0269435abf664bede4b9aad1d5a959e27681b4f51b2fee",
"md5": "571232a5896d432da5c5dcd1713051a9",
"sha256": "d94dd692513f071cc1840000ab3d529ae9106f225052dd2790d84cf3039bfa9b"
},
"downloads": -1,
"filename": "poetry_setuptools_scm_plugin-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "571232a5896d432da5c5dcd1713051a9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 6550,
"upload_time": "2024-06-23T13:56:35",
"upload_time_iso_8601": "2024-06-23T13:56:35.064116Z",
"url": "https://files.pythonhosted.org/packages/dc/da/d4d3b5f64d7b2d0269435abf664bede4b9aad1d5a959e27681b4f51b2fee/poetry_setuptools_scm_plugin-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-23 13:56:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "volkerstampa",
"github_project": "poetry-setuptools-scm-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "poetry-setuptools-scm-plugin"
}
JSON
