# tox-poetry-installer
A plugin for [Tox](https://tox.readthedocs.io/en/latest/) that lets you install test
environment dependencies from the [Poetry](https://python-poetry.org/) lockfile.
[](https://github.com/enpaul/tox-poetry-installer/actions)
[](https://pypi.org/project/tox-poetry-installer/)
[](https://libraries.io/pypi/tox-poetry-installer)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org)
[](https://github.com/psf/black)
⚠️ **This project is beta software and is under active development** ⚠️
## Documentation
- [Feature Overview](#feature-overview)
- [Using the Plugin](#user-documentation)
- [Installing](#installing)
- [Quick Start](#quick-start)
- [References](#references)
- [Config Options](#configuration-options)
- [Runtime Options](#runtime-options)
- [Errors](#errors)
- [Other Notes](#other-notes)
- [Unsupported Tox config options](#unsupported-tox-config-options)
- [Updating locked dependencies in a testenv](#updating-locked-dependencies-in-a-testenv)
- [Using with an unmanaged Poetry installation](#using-with-an-unmanaged-poetry-installation)
- [Developing the Plugin](#developer-documentation)
- [Road Map](#road-map)
See the
[Changelog](https://github.com/enpaul/tox-poetry-installer/blob/devel/CHANGELOG.md) for
release history.
*See also: [official Tox plugins](https://tox.readthedocs.io/en/latest/plugins.html) and
[the official Poetry documentation on using Tox](https://python-poetry.org/docs/faq/#is-tox-supported)*
## Feature Overview
- Manage package versions in exactly one place and with exactly one tool: Poetry.
- Ensure CI/CD and other automation tools are using the same package versions that you are
in your local development environment.
- Add only the packages or custom groups you need to a Tox test environment, instead of
everything in your lockfile.
- Directly integrate with Poetry, re-using your existing package indexes and credentials,
with no additional configuration.
- Wherever possible, built-in Tox config options are always respected and their behavior
kept consistent.
- Extremely configurable. Every feature can be disabled or enabled for any given Tox test
environment.
- Friendly to other Tox plugins and supports a wide range of environments.
## User Documentation
*This section is for users looking to integrate the plugin with their project or CI
system. For information on contributing to the plugin please see the
[Developer Docs](#developer-documentation)*
### Installing
The recommended way to install the plugin is to add it to a project using Poetry:
```bash
poetry add -G dev tox-poetry-installer[poetry]
```
> ℹ️ **Note:** Always install the plugin with the `[poetry]` extra, unless you are
> [managing the Poetry installation yourself](#externally-managed-poetry-installation).
Alternatively, it can be installed directly to a virtual environment using Pip, though
this is not recommended:
```bash
source somevenv/bin/activate
pip install tox-poetry-installer
```
Alternatively alternatively, it can be installed using the Tox
[`requires`](https://tox.readthedocs.io/en/latest/config.html#conf-requires) option by
adding the below to `tox.ini`, though this is also not recommended:
```ini
requires =
tox-poetry-installer[poetry] == 0.10.2
```
After installing, check that Tox recognizes the plugin by running
`poetry run tox --version`. The command should give output similar to below:
```
3.20.0 imported from .venv/lib64/python3.10/site-packages/tox/__init__.py
registered plugins:
tox-poetry-installer-0.10.2 at .venv/lib64/python3.10/site-packages/tox_poetry_installer/__init__.py
```
### Quick Start
Congratulations! 🎉 Just by installing the plugin your Tox config is already using locked
dependencies: when Tox builds and installs your project package to a test environment,
your project package's dependencies will be installed from the lockfile.
Now lets update an example `tox.ini` to install the other test environment dependencies
from the lockfile.
A `testenv` from the example `tox.ini` we're starting with is below:
```ini
[testenv]
description = Some very cool tests
deps =
black == 20.8b1
pylint >=2.4.4,<2.7.0
mypy <0.800
commands = ...
```
To update the config so that the testenv dependencies are installed from the lockfile, we
can replace the built-in
[`deps`](https://tox.readthedocs.io/en/latest/config.html#conf-deps) option with the
`locked_deps` option provided by the plugin, and then remove the inline version
specifiers. With these changes the three testenv dependencies (as well as all of their
dependencies) will be installed from the lockfile when the test environment is recreated:
```ini
[testenv]
description = Some very cool tests
locked_deps =
black
pylint
mypy
commands = ...
```
We can also add the `require_locked_deps` option to the test environment. This will both
block any other install tools (another plugin or Tox itself) from installing dependencies
to the Tox environment and also cause Tox to fail if the test environment also uses the
built-in [`deps`](https://tox.readthedocs.io/en/latest/config.html#conf-deps) option:
```ini
[testenv]
description = Some very cool tests
require_locked_deps = true
locked_deps =
black
pylint
mypy
commands = ...
```
> ℹ️ **Note:** Settings configured on the main `testenv` environment are inherited by
> child test environments (for example, `testenv:foo`). To override this, specify the
> setting in the child environment with a different value.
Alternatively, we can skip specifying all of our dependencies for a test environment in
the Tox config and install Poetry dependency groups directly:
```ini
[testenv]
description = Some very cool tests
require_locked_deps = true
poetry_dep_groups =
dev
commands = ...
```
> ℹ️ **Note:** The `install_dev_deps` configuration option is deprecated. See
> [Configuration Options](#configuration-options) for more information.
Finally, we can also install an unlocked dependency (a dependency which doesn't take its
version from the Poetry lockfile) into the test environment alongside the locked ones. We
need to remove the `require_locked_deps = true` option, otherwise the environment will
error, and then we can add the unlocked dependency using the built-in
[`deps`](https://tox.readthedocs.io/en/latest/config.html#conf-deps) option:
```ini
[testenv]
description = Some very cool tests
deps =
pytest >= 5.6.0,<6.0.0
locked_deps =
black
pylint
mypy
commands = ...
```
## References
### Configuration Options
All options listed below are Tox environment options and can be applied to one or more
environment sections of the `tox.ini` file. They cannot be applied to the global Tox
configuration section.
> ℹ️ **Note:** Settings configured on the main `testenv` environment are inherited by
> child test environments (for example, `testenv:foo`). To override this, specify the
> setting in the child environment with a different value.
| Option | Type | Default | Description |
| :--------------------- | :-----: | :-----: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `locked_deps` | List | `[]` | Names of packages to install to the test environment from the Poetry lockfile. Transient dependencies (packages required by these dependencies) are automatically included. |
| `require_locked_deps` | Boolean | False | Whether the plugin should block attempts to install unlocked dependencies to the test environment. If enabled, then the [`tox_testenv_install_deps`](https://tox.readthedocs.io/en/latest/plugins.html#tox.hookspecs.tox_testenv_install_deps) plugin hook will be intercepted and an error will be raised if the test environment has the `deps` option configured. |
| `install_project_deps` | Boolean | True | Whether all of the Poetry primary dependencies for the project package should be installed to the test environment. |
| `require_poetry` | Boolean | False | Whether Tox should be forced to fail if the plugin cannot import Poetry locally. If `False` then the plugin will be skipped for the test environment if Poetry cannot be imported. If `True` then the plugin will force the environment to error and the Tox run to fail. |
| `poetry_dep_groups` | List | `[]` | Names of Poetry dependency groups specified in `pyproject.toml` to install to the test environment. |
> ℹ️ **Note:** The `install_dev_deps` configuration option is deprecated and will be
> removed in version 1.0.0. Please set `poetry_dep_groups = [dev]` in `tox.ini` for
> environments that install the development dependencies.
### Runtime Options
All arguments listed below can be passed to the `tox` command to modify runtime behavior
of the plugin.
| Argument | Type | Default | Description |
| :--------------------------- | :-----: | :-----: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--parallel-install-threads` | Integer | `10` | Number of worker threads to use to install dependencies in parallel. Installing in parallel with more threads can greatly speed up the install process, but can cause race conditions during install. Pass this option with the value `0` to entirely disable parallel installation. |
> ℹ️ **Note:** The `--require-poetry` runtime option is deprecated and will be removed in
> version 1.0.0. Please set `require_poetry = true` in `tox.ini` for environments that
> should fail if Poetry is not available.
> ℹ️ **Note:** The `--parallelize-locked-install` option is deprecated and will be removed
> in version 1.0.0. Please use the `--parallel-install-threads` option.
### Errors
There are several errors that the plugin can encounter for a test environment when Tox is
run. If an error is encountered then the status of the test environment that caused the
error will be set to one of the "Status" values below to indicate what the error was.
| Status/Name | Cause |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ExtraNotFoundError` | Indicates that the [`extras`](https://tox.readthedocs.io/en/latest/config.html#conf-extras) config option specified an extra that is not configured by Poetry in `pyproject.toml`. |
| `LockedDepVersionConflictError` | Indicates that an item in the `locked_deps` config option includes a [PEP-508 version specifier](https://www.python.org/dev/peps/pep-0508/#grammar) (ex: `pytest >=6.0, <6.1`). |
| `LockedDepNotFoundError` | Indicates that an item specified in the `locked_deps` config option does not match the name of a package in the Poetry lockfile. |
| `LockedDepsRequiredError` | Indicates that a test environment with the `require_locked_deps` config option set to `true` also specified unlocked dependencies using the [`deps`](https://tox.readthedocs.io/en/latest/config.html#conf-deps) config option. |
| `PoetryNotInstalledError` | Indicates that the `poetry` module could not be imported under the current runtime environment, and `require_poetry = true` was specified. |
| `RequiresUnsafeDepError` | Indicates that the package-under-test depends on a package that Poetry has classified as unsafe and cannot be installed. |
> ℹ️ **Note:** One or more of these errors can be caused by the `pyproject.toml` being out
> of sync with the Poetry lockfile. If this is the case, than a warning will be logged
> when Tox is run.
### Other Notes
#### Unsupported Tox config options
Below are the built-in Tox config options that are not respected by this plugin. All of
these options are made obsolete by the Poetry lockfile: either they aren't needed or their
equivalent functionality is instead taken directly from the package details Poetry stores
in its lockfile.
> ℹ️ **Note:** The unsupported Tox config options will still apply to unlocked
> dependencies being installed with the default Tox installation backend.
- [`install_command`](https://tox.readthedocs.io/en/latest/config.html#conf-install_command)
- [`pip_pre`](https://tox.readthedocs.io/en/latest/config.html#conf-pip_pre)
- [`download`](https://tox.readthedocs.io/en/latest/config.html#conf-download)
- [`indexserver`](https://tox.readthedocs.io/en/latest/config.html#conf-indexserver)
- [`usedevelop`](https://tox.readthedocs.io/en/latest/config.html#conf-indexserver)
#### Updating locked dependencies in a testenv
When Poetry updates the version of a package in the lockfile (using either `poetry lock`
or `poetry update`) then the plugin will automatically use this new version to install the
package to a test environment; there is no need to manually update `tox.ini` after
updating the Poetry lockfile.
However, the plugin cannot determine when the lockfile is updated. If a Tox test
environment has already been created then it will need to be recreated (using Tox's
built-in
[`--recreate`](https://tox.readthedocs.io/en/latest/example/basic.html#forcing-re-creation-of-virtual-environments)
option) for the new version to be found and installed.
> ℹ️ **Note:** To force Tox to always recreate a test environment the
> [`recreate`](https://tox.readthedocs.io/en/latest/config.html#conf-recreate) config
> option can be set.
#### Using with an unmanaged Poetry installation
In CI/CD systems, automation environments, or other Python environments where the loaded
site packages are not managed by Poetry, it can be useful to manage the local installation
of Poetry externally. This also helps to avoid problems that can be caused by the
`--no-root`, `--without dev`, or `--sync` arguments to the `poetry install` command which,
in some situations, can cause Poetry to uninstall itself if Poetry is specified as a
dependency of one of the packages it is managing (like this plugin). To support these use
cases, this plugin specifies the `poetry` package as an optional dependency that can be
installed using a setuptools extra also named `poetry`.
> ⚠️ **Warning:** This plugin requires Poetry to function. If the plugin is installed
> without the `poetry` setuptools extra then Poetry must be installed independently for
> the plugin to function properly.
To skip installing the `poetry` package as a dependency of `tox-poetry-installer`, do not
specify the `poetry` extra when adding the plugin:
```bash
# Adding the package without the "[poetry]" extra specifier so that
# Poetry is not added as a transient dev-dependency:
poetry add -G dev tox-poetry-installer
# Adding the package with the "[poetry]" extra specifier, so the Poetry
# package will be added to the environment and tracked in the lockfile:
poetry add -G dev tox-poetry-installer[poetry]
```
Once the plugin is installed- either with or without the Poetry extra- you can validate
that the plugin will run correctly with the following command. This command checks that
all three required components (Tox, Poetry, and the plugin itself) are available in the
current Python environment:
```bash
python -c '\
import tox;\
import tox_poetry_installer;\
from poetry.poetry import Poetry;\
'
```
> ℹ️ **Note:** To force Tox to fail if Poetry is not installed, add the
> `require_poetry = true` option to the tox `[testenv]` configuration. See the
> [Config Options](#configuration-options) for more information.
## Developer Documentation
All project contributors and participants are expected to adhere to the
[Contributor Covenant Code of Conduct, v2](CODE_OF_CONDUCT.md)
([external link](https://www.contributor-covenant.org/version/2/0/code_of_conduct/)).
The `devel` branch has the latest (and potentially unstable) changes. The stable releases
are tracked on [Github](https://github.com/enpaul/tox-poetry-installer/releases),
[PyPi](https://pypi.org/project/tox-poetry-installer/#history), and in the
[Changelog](CHANGELOG.md).
- To report a bug, request a feature, or ask for assistance, please
[open an issue on the Github repository](https://github.com/enpaul/tox-poetry-installer/issues/new).
- To report a security concern or code of conduct violation, please contact the project
author directly at **me \[at\] enp dot one**.
- To submit an update, please
[fork the repository](https://docs.github.com/en/enterprise/2.20/user/github/getting-started-with-github/fork-a-repo)
and [open a pull request](https://github.com/enpaul/tox-poetry-installer/compare).
Developing this project requires [Python 3.10+](https://www.python.org/downloads/) and
[Poetry 1.4](https://python-poetry.org/docs/#installation) or later. GNU Make can
optionally be used to quickly setup a local development environment, but this is not
required.
To setup a local development environment:
```bash
# Clone the repository...
# ...over HTTPS
git clone https://github.com/enpaul/tox-poetry-installer.git
# ...over SSH
git clone git@github.com:enpaul/tox-poetry-installer.git
cd tox-poetry-installer/
# Create and configure the local development environment
make dev
# Run tests and CI locally
make test
# See additional make targets
make help
```
> ℹ️ **Note:** The pre-commit hooks require dependencies in the Poetry environment to run.
> To make a commit with the pre-commit hooks, you will need to run `poetry run git commit`
> or, alternatively,
> [launch an environment shell](https://python-poetry.org/docs/cli/#shell).
## Road Map
This project is under active development and is classified as beta software, ready for
production environments on a provisional basis only.
- Beta classification was assigned with
[v0.6.0](https://github.com/enpaul/tox-poetry-installer/releases/tag/0.6.0)
- Stable classification will be assigned when the test suite covers an acceptable number
of use cases
### Path to Beta
- [x] Verify that primary package dependencies (from the `.package` env) are installed
correctly using the Poetry backend.
- [x] Support the [`extras`](https://tox.readthedocs.io/en/latest/config.html#conf-extras)
Tox configuration option ([#4](https://github.com/enpaul/tox-poetry-installer/issues/4))
- [x] Add per-environment Tox configuration option to fall back to default installation
backend.
- [ ] ~Add warnings when an unsupported Tox configuration option is detected while using
the Poetry backend.~ ([#5](https://github.com/enpaul/tox-poetry-installer/issues/5))
- [x] Add trivial tests to ensure the project metadata is consistent between the
pyproject.toml and the module constants.
- [x] Update to use [poetry-core](https://github.com/python-poetry/poetry-core) and
improve robustness of the Tox and Poetry module imports to avoid potentially breaking
API changes in upstream packages.
([#2](https://github.com/enpaul/tox-poetry-installer/issues/2))
- [ ] ~Find and implement a way to mitigate the
[UNSAFE_DEPENDENCIES issue](https://github.com/python-poetry/poetry/issues/1584) in
Poetry.~ ([#6](https://github.com/enpaul/tox-poetry-installer/issues/6))
- [x] Fix logging to make proper use of Tox's logging reporter infrastructure
([#3](https://github.com/enpaul/tox-poetry-installer/issues/3))
- [x] Add configuration option for installing all dev-dependencies to a testenv
([#14](https://github.com/enpaul/tox-poetry-installer/issues/14))
### Path to Stable
Everything in Beta plus...
- [ ] Fully replace dependency on `poetry` with dependency on `poetry-core`
([#2](https://github.com/enpaul/tox-poetry-installer/issues/2))
- [x] Add comprehensive unit tests
- [ ] ~Add tests for each feature version of Tox between 3.8 and 3.20~
- [x] Add tests for Python-3.6, 3.7, 3.8, and 3.9
- [x] Add Github Actions based CI
Raw data
{
"_id": null,
"home_page": "https://github.com/enpaul/tox-poetry-installer/",
"name": "tox-poetry-installer",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "tox,poetry,plugin",
"author": "Ethan Paul",
"author_email": "24588726+enpaul@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/9e/69/f57a579ac09a9ff17261054d55ff2c1a2ac0975219f4695fdcba6bdfd387/tox_poetry_installer-0.10.3.tar.gz",
"platform": null,
"description": "# tox-poetry-installer\n\nA plugin for [Tox](https://tox.readthedocs.io/en/latest/) that lets you install test\nenvironment dependencies from the [Poetry](https://python-poetry.org/) lockfile.\n\n[](https://github.com/enpaul/tox-poetry-installer/actions)\n[](https://pypi.org/project/tox-poetry-installer/)\n[](https://libraries.io/pypi/tox-poetry-installer)\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org)\n[](https://github.com/psf/black)\n\n\u26a0\ufe0f **This project is beta software and is under active development** \u26a0\ufe0f\n\n## Documentation\n\n- [Feature Overview](#feature-overview)\n- [Using the Plugin](#user-documentation)\n - [Installing](#installing)\n - [Quick Start](#quick-start)\n - [References](#references)\n - [Config Options](#configuration-options)\n - [Runtime Options](#runtime-options)\n - [Errors](#errors)\n - [Other Notes](#other-notes)\n - [Unsupported Tox config options](#unsupported-tox-config-options)\n - [Updating locked dependencies in a testenv](#updating-locked-dependencies-in-a-testenv)\n - [Using with an unmanaged Poetry installation](#using-with-an-unmanaged-poetry-installation)\n- [Developing the Plugin](#developer-documentation)\n- [Road Map](#road-map)\n\nSee the\n[Changelog](https://github.com/enpaul/tox-poetry-installer/blob/devel/CHANGELOG.md) for\nrelease history.\n\n*See also: [official Tox plugins](https://tox.readthedocs.io/en/latest/plugins.html) and\n[the official Poetry documentation on using Tox](https://python-poetry.org/docs/faq/#is-tox-supported)*\n\n## Feature Overview\n\n- Manage package versions in exactly one place and with exactly one tool: Poetry.\n- Ensure CI/CD and other automation tools are using the same package versions that you are\n in your local development environment.\n- Add only the packages or custom groups you need to a Tox test environment, instead of\n everything in your lockfile.\n- Directly integrate with Poetry, re-using your existing package indexes and credentials,\n with no additional configuration.\n- Wherever possible, built-in Tox config options are always respected and their behavior\n kept consistent.\n- Extremely configurable. Every feature can be disabled or enabled for any given Tox test\n environment.\n- Friendly to other Tox plugins and supports a wide range of environments.\n\n## User Documentation\n\n*This section is for users looking to integrate the plugin with their project or CI\nsystem. For information on contributing to the plugin please see the\n[Developer Docs](#developer-documentation)*\n\n### Installing\n\nThe recommended way to install the plugin is to add it to a project using Poetry:\n\n```bash\npoetry add -G dev tox-poetry-installer[poetry]\n```\n\n> \u2139\ufe0f **Note:** Always install the plugin with the `[poetry]` extra, unless you are\n> [managing the Poetry installation yourself](#externally-managed-poetry-installation).\n\nAlternatively, it can be installed directly to a virtual environment using Pip, though\nthis is not recommended:\n\n```bash\nsource somevenv/bin/activate\npip install tox-poetry-installer\n```\n\nAlternatively alternatively, it can be installed using the Tox\n[`requires`](https://tox.readthedocs.io/en/latest/config.html#conf-requires) option by\nadding the below to `tox.ini`, though this is also not recommended:\n\n```ini\nrequires =\n tox-poetry-installer[poetry] == 0.10.2\n```\n\nAfter installing, check that Tox recognizes the plugin by running\n`poetry run tox --version`. The command should give output similar to below:\n\n```\n3.20.0 imported from .venv/lib64/python3.10/site-packages/tox/__init__.py\nregistered plugins:\n tox-poetry-installer-0.10.2 at .venv/lib64/python3.10/site-packages/tox_poetry_installer/__init__.py\n```\n\n### Quick Start\n\nCongratulations! \ud83c\udf89 Just by installing the plugin your Tox config is already using locked\ndependencies: when Tox builds and installs your project package to a test environment,\nyour project package's dependencies will be installed from the lockfile.\n\nNow lets update an example `tox.ini` to install the other test environment dependencies\nfrom the lockfile.\n\nA `testenv` from the example `tox.ini` we're starting with is below:\n\n```ini\n[testenv]\ndescription = Some very cool tests\ndeps =\n black == 20.8b1\n pylint >=2.4.4,<2.7.0\n mypy <0.800\ncommands = ...\n```\n\nTo update the config so that the testenv dependencies are installed from the lockfile, we\ncan replace the built-in\n[`deps`](https://tox.readthedocs.io/en/latest/config.html#conf-deps) option with the\n`locked_deps` option provided by the plugin, and then remove the inline version\nspecifiers. With these changes the three testenv dependencies (as well as all of their\ndependencies) will be installed from the lockfile when the test environment is recreated:\n\n```ini\n[testenv]\ndescription = Some very cool tests\nlocked_deps =\n black\n pylint\n mypy\ncommands = ...\n```\n\nWe can also add the `require_locked_deps` option to the test environment. This will both\nblock any other install tools (another plugin or Tox itself) from installing dependencies\nto the Tox environment and also cause Tox to fail if the test environment also uses the\nbuilt-in [`deps`](https://tox.readthedocs.io/en/latest/config.html#conf-deps) option:\n\n```ini\n[testenv]\ndescription = Some very cool tests\nrequire_locked_deps = true\nlocked_deps =\n black\n pylint\n mypy\ncommands = ...\n```\n\n> \u2139\ufe0f **Note:** Settings configured on the main `testenv` environment are inherited by\n> child test environments (for example, `testenv:foo`). To override this, specify the\n> setting in the child environment with a different value.\n\nAlternatively, we can skip specifying all of our dependencies for a test environment in\nthe Tox config and install Poetry dependency groups directly:\n\n```ini\n[testenv]\ndescription = Some very cool tests\nrequire_locked_deps = true\npoetry_dep_groups =\n dev\ncommands = ...\n```\n\n> \u2139\ufe0f **Note:** The `install_dev_deps` configuration option is deprecated. See\n> [Configuration Options](#configuration-options) for more information.\n\nFinally, we can also install an unlocked dependency (a dependency which doesn't take its\nversion from the Poetry lockfile) into the test environment alongside the locked ones. We\nneed to remove the `require_locked_deps = true` option, otherwise the environment will\nerror, and then we can add the unlocked dependency using the built-in\n[`deps`](https://tox.readthedocs.io/en/latest/config.html#conf-deps) option:\n\n```ini\n[testenv]\ndescription = Some very cool tests\ndeps =\n pytest >= 5.6.0,<6.0.0\nlocked_deps =\n black\n pylint\n mypy\ncommands = ...\n```\n\n## References\n\n### Configuration Options\n\nAll options listed below are Tox environment options and can be applied to one or more\nenvironment sections of the `tox.ini` file. They cannot be applied to the global Tox\nconfiguration section.\n\n> \u2139\ufe0f **Note:** Settings configured on the main `testenv` environment are inherited by\n> child test environments (for example, `testenv:foo`). To override this, specify the\n> setting in the child environment with a different value.\n\n| Option | Type | Default | Description |\n| :--------------------- | :-----: | :-----: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `locked_deps` | List | `[]` | Names of packages to install to the test environment from the Poetry lockfile. Transient dependencies (packages required by these dependencies) are automatically included. |\n| `require_locked_deps` | Boolean | False | Whether the plugin should block attempts to install unlocked dependencies to the test environment. If enabled, then the [`tox_testenv_install_deps`](https://tox.readthedocs.io/en/latest/plugins.html#tox.hookspecs.tox_testenv_install_deps) plugin hook will be intercepted and an error will be raised if the test environment has the `deps` option configured. |\n| `install_project_deps` | Boolean | True | Whether all of the Poetry primary dependencies for the project package should be installed to the test environment. |\n| `require_poetry` | Boolean | False | Whether Tox should be forced to fail if the plugin cannot import Poetry locally. If `False` then the plugin will be skipped for the test environment if Poetry cannot be imported. If `True` then the plugin will force the environment to error and the Tox run to fail. |\n| `poetry_dep_groups` | List | `[]` | Names of Poetry dependency groups specified in `pyproject.toml` to install to the test environment. |\n\n> \u2139\ufe0f **Note:** The `install_dev_deps` configuration option is deprecated and will be\n> removed in version 1.0.0. Please set `poetry_dep_groups = [dev]` in `tox.ini` for\n> environments that install the development dependencies.\n\n### Runtime Options\n\nAll arguments listed below can be passed to the `tox` command to modify runtime behavior\nof the plugin.\n\n| Argument | Type | Default | Description |\n| :--------------------------- | :-----: | :-----: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--parallel-install-threads` | Integer | `10` | Number of worker threads to use to install dependencies in parallel. Installing in parallel with more threads can greatly speed up the install process, but can cause race conditions during install. Pass this option with the value `0` to entirely disable parallel installation. |\n\n> \u2139\ufe0f **Note:** The `--require-poetry` runtime option is deprecated and will be removed in\n> version 1.0.0. Please set `require_poetry = true` in `tox.ini` for environments that\n> should fail if Poetry is not available.\n\n> \u2139\ufe0f **Note:** The `--parallelize-locked-install` option is deprecated and will be removed\n> in version 1.0.0. Please use the `--parallel-install-threads` option.\n\n### Errors\n\nThere are several errors that the plugin can encounter for a test environment when Tox is\nrun. If an error is encountered then the status of the test environment that caused the\nerror will be set to one of the \"Status\" values below to indicate what the error was.\n\n| Status/Name | Cause |\n| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `ExtraNotFoundError` | Indicates that the [`extras`](https://tox.readthedocs.io/en/latest/config.html#conf-extras) config option specified an extra that is not configured by Poetry in `pyproject.toml`. |\n| `LockedDepVersionConflictError` | Indicates that an item in the `locked_deps` config option includes a [PEP-508 version specifier](https://www.python.org/dev/peps/pep-0508/#grammar) (ex: `pytest >=6.0, <6.1`). |\n| `LockedDepNotFoundError` | Indicates that an item specified in the `locked_deps` config option does not match the name of a package in the Poetry lockfile. |\n| `LockedDepsRequiredError` | Indicates that a test environment with the `require_locked_deps` config option set to `true` also specified unlocked dependencies using the [`deps`](https://tox.readthedocs.io/en/latest/config.html#conf-deps) config option. |\n| `PoetryNotInstalledError` | Indicates that the `poetry` module could not be imported under the current runtime environment, and `require_poetry = true` was specified. |\n| `RequiresUnsafeDepError` | Indicates that the package-under-test depends on a package that Poetry has classified as unsafe and cannot be installed. |\n\n> \u2139\ufe0f **Note:** One or more of these errors can be caused by the `pyproject.toml` being out\n> of sync with the Poetry lockfile. If this is the case, than a warning will be logged\n> when Tox is run.\n\n### Other Notes\n\n#### Unsupported Tox config options\n\nBelow are the built-in Tox config options that are not respected by this plugin. All of\nthese options are made obsolete by the Poetry lockfile: either they aren't needed or their\nequivalent functionality is instead taken directly from the package details Poetry stores\nin its lockfile.\n\n> \u2139\ufe0f **Note:** The unsupported Tox config options will still apply to unlocked\n> dependencies being installed with the default Tox installation backend.\n\n- [`install_command`](https://tox.readthedocs.io/en/latest/config.html#conf-install_command)\n- [`pip_pre`](https://tox.readthedocs.io/en/latest/config.html#conf-pip_pre)\n- [`download`](https://tox.readthedocs.io/en/latest/config.html#conf-download)\n- [`indexserver`](https://tox.readthedocs.io/en/latest/config.html#conf-indexserver)\n- [`usedevelop`](https://tox.readthedocs.io/en/latest/config.html#conf-indexserver)\n\n#### Updating locked dependencies in a testenv\n\nWhen Poetry updates the version of a package in the lockfile (using either `poetry lock`\nor `poetry update`) then the plugin will automatically use this new version to install the\npackage to a test environment; there is no need to manually update `tox.ini` after\nupdating the Poetry lockfile.\n\nHowever, the plugin cannot determine when the lockfile is updated. If a Tox test\nenvironment has already been created then it will need to be recreated (using Tox's\nbuilt-in\n[`--recreate`](https://tox.readthedocs.io/en/latest/example/basic.html#forcing-re-creation-of-virtual-environments)\noption) for the new version to be found and installed.\n\n> \u2139\ufe0f **Note:** To force Tox to always recreate a test environment the\n> [`recreate`](https://tox.readthedocs.io/en/latest/config.html#conf-recreate) config\n> option can be set.\n\n#### Using with an unmanaged Poetry installation\n\nIn CI/CD systems, automation environments, or other Python environments where the loaded\nsite packages are not managed by Poetry, it can be useful to manage the local installation\nof Poetry externally. This also helps to avoid problems that can be caused by the\n`--no-root`, `--without dev`, or `--sync` arguments to the `poetry install` command which,\nin some situations, can cause Poetry to uninstall itself if Poetry is specified as a\ndependency of one of the packages it is managing (like this plugin). To support these use\ncases, this plugin specifies the `poetry` package as an optional dependency that can be\ninstalled using a setuptools extra also named `poetry`.\n\n> \u26a0\ufe0f **Warning:** This plugin requires Poetry to function. If the plugin is installed\n> without the `poetry` setuptools extra then Poetry must be installed independently for\n> the plugin to function properly.\n\nTo skip installing the `poetry` package as a dependency of `tox-poetry-installer`, do not\nspecify the `poetry` extra when adding the plugin:\n\n```bash\n# Adding the package without the \"[poetry]\" extra specifier so that\n# Poetry is not added as a transient dev-dependency:\npoetry add -G dev tox-poetry-installer\n\n# Adding the package with the \"[poetry]\" extra specifier, so the Poetry\n# package will be added to the environment and tracked in the lockfile:\npoetry add -G dev tox-poetry-installer[poetry]\n```\n\nOnce the plugin is installed- either with or without the Poetry extra- you can validate\nthat the plugin will run correctly with the following command. This command checks that\nall three required components (Tox, Poetry, and the plugin itself) are available in the\ncurrent Python environment:\n\n```bash\npython -c '\\\n import tox;\\\n import tox_poetry_installer;\\\n from poetry.poetry import Poetry;\\\n'\n```\n\n> \u2139\ufe0f **Note:** To force Tox to fail if Poetry is not installed, add the\n> `require_poetry = true` option to the tox `[testenv]` configuration. See the\n> [Config Options](#configuration-options) for more information.\n\n## Developer Documentation\n\nAll project contributors and participants are expected to adhere to the\n[Contributor Covenant Code of Conduct, v2](CODE_OF_CONDUCT.md)\n([external link](https://www.contributor-covenant.org/version/2/0/code_of_conduct/)).\n\nThe `devel` branch has the latest (and potentially unstable) changes. The stable releases\nare tracked on [Github](https://github.com/enpaul/tox-poetry-installer/releases),\n[PyPi](https://pypi.org/project/tox-poetry-installer/#history), and in the\n[Changelog](CHANGELOG.md).\n\n- To report a bug, request a feature, or ask for assistance, please\n [open an issue on the Github repository](https://github.com/enpaul/tox-poetry-installer/issues/new).\n- To report a security concern or code of conduct violation, please contact the project\n author directly at **\u200cme \\[at\u200c\\] enp dot\u200e \u200cone**.\n- To submit an update, please\n [fork the repository](https://docs.github.com/en/enterprise/2.20/user/github/getting-started-with-github/fork-a-repo)\n and [open a pull request](https://github.com/enpaul/tox-poetry-installer/compare).\n\nDeveloping this project requires [Python 3.10+](https://www.python.org/downloads/) and\n[Poetry 1.4](https://python-poetry.org/docs/#installation) or later. GNU Make can\noptionally be used to quickly setup a local development environment, but this is not\nrequired.\n\nTo setup a local development environment:\n\n```bash\n# Clone the repository...\n# ...over HTTPS\ngit clone https://github.com/enpaul/tox-poetry-installer.git\n# ...over SSH\ngit clone git@github.com:enpaul/tox-poetry-installer.git\n\ncd tox-poetry-installer/\n\n# Create and configure the local development environment\nmake dev\n\n# Run tests and CI locally\nmake test\n\n# See additional make targets\nmake help\n```\n\n> \u2139\ufe0f **Note:** The pre-commit hooks require dependencies in the Poetry environment to run.\n> To make a commit with the pre-commit hooks, you will need to run `poetry run git commit`\n> or, alternatively,\n> [launch an environment shell](https://python-poetry.org/docs/cli/#shell).\n\n## Road Map\n\nThis project is under active development and is classified as beta software, ready for\nproduction environments on a provisional basis only.\n\n- Beta classification was assigned with\n [v0.6.0](https://github.com/enpaul/tox-poetry-installer/releases/tag/0.6.0)\n- Stable classification will be assigned when the test suite covers an acceptable number\n of use cases\n\n### Path to Beta\n\n- [x] Verify that primary package dependencies (from the `.package` env) are installed\n correctly using the Poetry backend.\n- [x] Support the [`extras`](https://tox.readthedocs.io/en/latest/config.html#conf-extras)\n Tox configuration option ([#4](https://github.com/enpaul/tox-poetry-installer/issues/4))\n- [x] Add per-environment Tox configuration option to fall back to default installation\n backend.\n- [ ] ~Add warnings when an unsupported Tox configuration option is detected while using\n the Poetry backend.~ ([#5](https://github.com/enpaul/tox-poetry-installer/issues/5))\n- [x] Add trivial tests to ensure the project metadata is consistent between the\n pyproject.toml and the module constants.\n- [x] Update to use [poetry-core](https://github.com/python-poetry/poetry-core) and\n improve robustness of the Tox and Poetry module imports to avoid potentially breaking\n API changes in upstream packages.\n ([#2](https://github.com/enpaul/tox-poetry-installer/issues/2))\n- [ ] ~Find and implement a way to mitigate the\n [UNSAFE_DEPENDENCIES issue](https://github.com/python-poetry/poetry/issues/1584) in\n Poetry.~ ([#6](https://github.com/enpaul/tox-poetry-installer/issues/6))\n- [x] Fix logging to make proper use of Tox's logging reporter infrastructure\n ([#3](https://github.com/enpaul/tox-poetry-installer/issues/3))\n- [x] Add configuration option for installing all dev-dependencies to a testenv\n ([#14](https://github.com/enpaul/tox-poetry-installer/issues/14))\n\n### Path to Stable\n\nEverything in Beta plus...\n\n- [ ] Fully replace dependency on `poetry` with dependency on `poetry-core`\n ([#2](https://github.com/enpaul/tox-poetry-installer/issues/2))\n- [x] Add comprehensive unit tests\n- [ ] ~Add tests for each feature version of Tox between 3.8 and 3.20~\n- [x] Add tests for Python-3.6, 3.7, 3.8, and 3.9\n- [x] Add Github Actions based CI\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A plugin for Tox that lets you install test environment dependencies from the Poetry lockfile",
"version": "0.10.3",
"project_urls": {
"Homepage": "https://github.com/enpaul/tox-poetry-installer/",
"Repository": "https://github.com/enpaul/tox-poetry-installer/"
},
"split_keywords": [
"tox",
"poetry",
"plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e58a28be9365098a58707372c7c362ce29b332b95e72aea484fb9846b9c05540",
"md5": "2ff599746c9fa2b038f2cf5cfc9d4046",
"sha256": "8580caf05f1ac83a7a938e449cfcb220cadaf6b087e9581ae837d782804ad4bc"
},
"downloads": -1,
"filename": "tox_poetry_installer-0.10.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2ff599746c9fa2b038f2cf5cfc9d4046",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 21420,
"upload_time": "2023-05-19T18:29:31",
"upload_time_iso_8601": "2023-05-19T18:29:31.128485Z",
"url": "https://files.pythonhosted.org/packages/e5/8a/28be9365098a58707372c7c362ce29b332b95e72aea484fb9846b9c05540/tox_poetry_installer-0.10.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9e69f57a579ac09a9ff17261054d55ff2c1a2ac0975219f4695fdcba6bdfd387",
"md5": "d622170ff02752a2e9d3129053bccfb0",
"sha256": "58af36082293b87e3488184f46ccf6f288c52c90e802066f53d3209c0f1c6226"
},
"downloads": -1,
"filename": "tox_poetry_installer-0.10.3.tar.gz",
"has_sig": false,
"md5_digest": "d622170ff02752a2e9d3129053bccfb0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 26271,
"upload_time": "2023-05-19T18:29:32",
"upload_time_iso_8601": "2023-05-19T18:29:32.393890Z",
"url": "https://files.pythonhosted.org/packages/9e/69/f57a579ac09a9ff17261054d55ff2c1a2ac0975219f4695fdcba6bdfd387/tox_poetry_installer-0.10.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-19 18:29:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "enpaul",
"github_project": "tox-poetry-installer",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "tox-poetry-installer"
}
JSON
