Metadata-Version: 2.1
Name: poem-plugins
Version: 0.15.17
Summary: Some set of poetry plugins
Home-page: https://pypi.org/project/poem-plugins
License: MIT
Keywords: plugins,poetry
Author: Ivan Sitkin
Author-email: alvinera@yandex.ru
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.9
Requires-Dist: poetry (>=1.2,<2.0)
Project-URL: Documentation, https://github.com/alviner/poem-plugins
Project-URL: Repository, https://github.com/alviner/poem-plugins
Description-Content-Type: text/markdown

# Poem Plugins

[![Pypi](https://img.shields.io/pypi/v/poem-plugins?color=%2334D058&label=pypi%20package)](https://pypi.org/project/poem-plugins)
[![Coverage Status](https://coveralls.io/repos/github/Alviner/poem-plugins/badge.svg?branch=main)](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.2.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` |


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.

