# 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.
## 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
### 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/86/f2/f5f4f2f0e0ba1bae2857740f84177a2539cb39f7221cee8d88fda6cf24bd/poetry_setuptools_scm_plugin-0.1.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\"](\n> https://github.com/python-poetry/poetry/issues/4971#issuecomment-1013930810). \n\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\n\n\n## Development\n\n### Prerequisites\n\n- Python >=3.10, can for example be installed with [pyenv](https://github.com/pyenv/pyenv):\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### 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.1.0",
"project_urls": {
"Homepage": "https://github.com/volkerstampa/poetry-setuptools-scm-plugin"
},
"split_keywords": [
"poetry",
" plugin",
" version",
" git"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "113b11407411b5d18d1ac5fc9477e5a727fe814ff5cf8be9c03571aabedabf5c",
"md5": "f373f61c1d141717d9dba9e9b441f471",
"sha256": "fcd23ad2cd7bea89890529df149fe6bd69f403a9471f7e352209b7d6609833be"
},
"downloads": -1,
"filename": "poetry_setuptools_scm_plugin-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f373f61c1d141717d9dba9e9b441f471",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 7404,
"upload_time": "2024-04-06T16:59:43",
"upload_time_iso_8601": "2024-04-06T16:59:43.879378Z",
"url": "https://files.pythonhosted.org/packages/11/3b/11407411b5d18d1ac5fc9477e5a727fe814ff5cf8be9c03571aabedabf5c/poetry_setuptools_scm_plugin-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "86f2f5f4f2f0e0ba1bae2857740f84177a2539cb39f7221cee8d88fda6cf24bd",
"md5": "8264dfa13b11ac26e4a484279ef6076d",
"sha256": "7394a319e3243bd6d7f99c5f68de28122e34156c4c88490cb035963eb8264ed2"
},
"downloads": -1,
"filename": "poetry_setuptools_scm_plugin-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "8264dfa13b11ac26e4a484279ef6076d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 6372,
"upload_time": "2024-04-06T16:59:44",
"upload_time_iso_8601": "2024-04-06T16:59:44.982078Z",
"url": "https://files.pythonhosted.org/packages/86/f2/f5f4f2f0e0ba1bae2857740f84177a2539cb39f7221cee8d88fda6cf24bd/poetry_setuptools_scm_plugin-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-06 16:59:44",
"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
