# Poem Plugins
[](https://pypi.org/project/poem-plugins)
[](https://coveralls.io/github/Alviner/poem-plugins?branch=main)
A set of plugins for [**Poetry**](https://python-poetry.org/).
## How to use
Make sure you have Poetry version `1.4.0` or above. Read below for instructions to install it if you haven't.
### Install Poem Plugins
Install this plugin to your Poetry:
```(console)
poetry self add poem-plugins
```
### Version Plugin
The poetry plugin for project versioning allows users to specify
the version of their project via the provider other than the default `pyproject.toml` file.
This can be useful for users who prefer to set the project version based on a git tag, for example.
Plugin can be configured via a section in the `pyproject.toml` file.
To use the plugin, you will need to add a section to your `pyproject.toml`
file that specifies the provider.
Here's an example of how you might configure the plugin in your `pyproject.toml` file:
```(toml)
[tool.poem-plugins.version]
provider = "git"
```
Likewise, you can specify a number of optional arguments to control the plugin
behavior. Here are some of the arguments that you can use:
| Name | description | Default |
|-------|-------------|---------|
| `update_pyproject` | plugin will not only use version from provider for building, but save it in `pyproject.toml` | `false` |
| `write_version_file` | plugin will create a file `version.py` inside a module, with version information | `false` |
| `version_file_quotes` | plugin will replace default quotes in `version.py` file with provided by: `'` or `"` | `unset` |
You can specify provider-specific settings in your configuration.
To specify provider-specific settings, you can use the `tool.poem-plugins.version.{provider}` section.
Here are some of the arguments that you can use for `git` provider:
| Name | description | Default |
|-------|-------------|---------|
| `version_prefix` | filter tags only starts with this prefix | `v` |
| `format` | plugin will use commit hash (long) or not (short) to build a project version | `short` |
Example:
```(toml)
[tool.poem-plugins.version.git]
version_prefix = "v"
format = "short"
```
To build your project, run the `poetry build` command.
The plugin will build the version via provider and use it to set the version for the project.
```(console)
$ git tag -a v0.1 -m 'tag description'
$ poetry build
poem-plugins: Setting version to: 0.1.0
Building awesome_package (0.1.0)
- Building sdist
- Built awesome_package-0.1.0.tar.gz
- Building wheel
- Built awesome_package-0.1.0-py3-none-any.whl
```
## How to develop
Before getting started with development, you'll need to have poetry installed.
Once you have poetry installed, you can create a virtual environment for the project by running:
```(bash)
poetry install
```
This will also install all the dependencies required for the project.
### Pre-commit hooks
This project uses pre-commit to automatically run
simple formatter `gray` before committing changes.
To set up the pre-commit hooks, run the following
command in the project root:
```(bash)
poetry run pre-commit install
```
### Type checking
This project uses `mypy` for type checking.
You can run the type checker
with the following command:
```(bash)
poetry run mypy poem_plugins
```
### Linting
This project uses `pylama` for linting.
You can run the linter
with the following command:
```(bash)
poetry run pylama poem_plugins
```
### Tests
We use `pytest` for running tests.
You can run the tests
with the following command:
```(bash)
poetry run pytest
```
Please make sure that all tests pass and linter and type checker does not
report any issues before submitting a pull request.
## Repo Activity
Raw data
{
"_id": null,
"home_page": "https://pypi.org/project/poem-plugins",
"name": "poem-plugins",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "plugins, poetry, packaging",
"author": "Ivan Sitkin",
"author_email": "alvinera@yandex.ru",
"download_url": "https://files.pythonhosted.org/packages/3a/e1/a66cb59d49e6e32ac95974f322fb2d0e80e42e22554cc05368e1559f993e/poem_plugins-1.1.101.tar.gz",
"platform": null,
"description": "# Poem Plugins\n\n[](https://pypi.org/project/poem-plugins)\n[](https://coveralls.io/github/Alviner/poem-plugins?branch=main)\n\nA set of plugins for [**Poetry**](https://python-poetry.org/).\n\n## How to use\n\nMake sure you have Poetry version `1.4.0` or above. Read below for instructions to install it if you haven't.\n\n### Install Poem Plugins\n\nInstall this plugin to your Poetry:\n\n```(console)\npoetry self add poem-plugins\n```\n\n### Version Plugin\n\nThe poetry plugin for project versioning allows users to specify\nthe version of their project via the provider other than the default `pyproject.toml` file.\nThis can be useful for users who prefer to set the project version based on a git tag, for example.\n\nPlugin can be configured via a section in the `pyproject.toml` file.\nTo use the plugin, you will need to add a section to your `pyproject.toml`\nfile that specifies the provider.\n\nHere's an example of how you might configure the plugin in your `pyproject.toml` file:\n\n```(toml)\n[tool.poem-plugins.version]\nprovider = \"git\"\n```\n\nLikewise, you can specify a number of optional arguments to control the plugin\nbehavior. Here are some of the arguments that you can use:\n| Name | description | Default |\n|-------|-------------|---------|\n| `update_pyproject` | plugin will not only use version from provider for building, but save it in `pyproject.toml` | `false` |\n| `write_version_file` | plugin will create a file `version.py` inside a module, with version information | `false` |\n| `version_file_quotes` | plugin will replace default quotes in `version.py` file with provided by: `'` or `\"` | `unset` |\n\nYou can specify provider-specific settings in your configuration.\nTo specify provider-specific settings, you can use the `tool.poem-plugins.version.{provider}` section.\nHere are some of the arguments that you can use for `git` provider:\n| Name | description | Default |\n|-------|-------------|---------|\n| `version_prefix` | filter tags only starts with this prefix | `v` |\n| `format` | plugin will use commit hash (long) or not (short) to build a project version | `short` |\n\nExample:\n\n```(toml)\n[tool.poem-plugins.version.git]\nversion_prefix = \"v\"\nformat = \"short\"\n```\n\nTo build your project, run the `poetry build` command.\nThe plugin will build the version via provider and use it to set the version for the project.\n\n```(console)\n$ git tag -a v0.1 -m 'tag description'\n$ poetry build\npoem-plugins: Setting version to: 0.1.0\nBuilding awesome_package (0.1.0)\n - Building sdist\n - Built awesome_package-0.1.0.tar.gz\n - Building wheel\n - Built awesome_package-0.1.0-py3-none-any.whl\n```\n\n## How to develop\n\nBefore getting started with development, you'll need to have poetry installed.\n\nOnce you have poetry installed, you can create a virtual environment for the project by running:\n\n```(bash)\npoetry install\n```\n\nThis will also install all the dependencies required for the project.\n\n### Pre-commit hooks\n\nThis project uses pre-commit to automatically run\nsimple formatter `gray` before committing changes.\nTo set up the pre-commit hooks, run the following\ncommand in the project root:\n\n```(bash)\npoetry run pre-commit install\n```\n\n### Type checking\n\nThis project uses `mypy` for type checking.\nYou can run the type checker\nwith the following command:\n\n```(bash)\npoetry run mypy poem_plugins\n```\n\n### Linting\n\nThis project uses `pylama` for linting.\nYou can run the linter\nwith the following command:\n\n```(bash)\npoetry run pylama poem_plugins\n```\n\n### Tests\n\nWe use `pytest` for running tests.\nYou can run the tests\nwith the following command:\n\n```(bash)\npoetry run pytest\n```\n\nPlease make sure that all tests pass and linter and type checker does not\nreport any issues before submitting a pull request.\n\n## Repo Activity\n![Alt](https://repobeats.axiom.co/api/embed/57f4a173f622ac131cd32a02516289b4aba64a1e.svg \"Repobeats analytics image\")\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Some set of poetry plugins",
"version": "1.1.101",
"project_urls": {
"Documentation": "https://github.com/alviner/poem-plugins",
"Homepage": "https://pypi.org/project/poem-plugins",
"Repository": "https://github.com/alviner/poem-plugins"
},
"split_keywords": [
"plugins",
" poetry",
" packaging"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f0897ca523162450f86ee579d6bc4fcf7e9c8ec881bc97c48e7eb41a15423647",
"md5": "d6bcedd788dba18dc5ed3b6e7deb7dbc",
"sha256": "3cced4e893019e746e0be2142ae3c4e4dff32b360787e27a0aef79d2952dacf4"
},
"downloads": -1,
"filename": "poem_plugins-1.1.101-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d6bcedd788dba18dc5ed3b6e7deb7dbc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 11673,
"upload_time": "2024-10-18T15:51:07",
"upload_time_iso_8601": "2024-10-18T15:51:07.491095Z",
"url": "https://files.pythonhosted.org/packages/f0/89/7ca523162450f86ee579d6bc4fcf7e9c8ec881bc97c48e7eb41a15423647/poem_plugins-1.1.101-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3ae1a66cb59d49e6e32ac95974f322fb2d0e80e42e22554cc05368e1559f993e",
"md5": "732f222369665963500fca2d1b0a3068",
"sha256": "597df8dd286066cb2e09565a8262a053b72e36af4390c895388dcd0d5de68b91"
},
"downloads": -1,
"filename": "poem_plugins-1.1.101.tar.gz",
"has_sig": false,
"md5_digest": "732f222369665963500fca2d1b0a3068",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 8976,
"upload_time": "2024-10-18T15:51:08",
"upload_time_iso_8601": "2024-10-18T15:51:08.709484Z",
"url": "https://files.pythonhosted.org/packages/3a/e1/a66cb59d49e6e32ac95974f322fb2d0e80e42e22554cc05368e1559f993e/poem_plugins-1.1.101.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-18 15:51:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alviner",
"github_project": "poem-plugins",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "poem-plugins"
}
JSON
