# 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.
Raw data
{
"_id": null,
"home_page": "https://pypi.org/project/poem-plugins",
"name": "poem-plugins",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "plugins,poetry",
"author": "Ivan Sitkin",
"author_email": "alvinera@yandex.ru",
"download_url": "https://files.pythonhosted.org/packages/fa/26/538d41c87f03774ef66b840e3b9e4a37097e18c5b41906d177bc6faf9a19/poem_plugins-1.1.2.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",
"bugtrack_url": null,
"license": "MIT",
"summary": "Some set of poetry plugins",
"version": "1.1.2",
"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"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e137ed258c248311bcb6e6a4ea2922ccfffe27b56191b9895477a84b95d15a3d",
"md5": "aff5472d6ad630842d08eb5dac5bb953",
"sha256": "a353f3f927f50dd447e565985acc4aa4f12422d5854437d73d000d7983d1ea09"
},
"downloads": -1,
"filename": "poem_plugins-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "aff5472d6ad630842d08eb5dac5bb953",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 11479,
"upload_time": "2024-01-25T17:24:20",
"upload_time_iso_8601": "2024-01-25T17:24:20.313194Z",
"url": "https://files.pythonhosted.org/packages/e1/37/ed258c248311bcb6e6a4ea2922ccfffe27b56191b9895477a84b95d15a3d/poem_plugins-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fa26538d41c87f03774ef66b840e3b9e4a37097e18c5b41906d177bc6faf9a19",
"md5": "1a9bd99984cdc6d12fe7108ee9c129d4",
"sha256": "7e0769caff00fae40709b9da82d72d36cc427adf613db6c6d4401f7158c24eee"
},
"downloads": -1,
"filename": "poem_plugins-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "1a9bd99984cdc6d12fe7108ee9c129d4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 8814,
"upload_time": "2024-01-25T17:24:42",
"upload_time_iso_8601": "2024-01-25T17:24:42.189261Z",
"url": "https://files.pythonhosted.org/packages/fa/26/538d41c87f03774ef66b840e3b9e4a37097e18c5b41906d177bc6faf9a19/poem_plugins-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-25 17:24:42",
"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
