Package: tox-poetry-installer
tox-poetry-installerA plugin forToxthat lets you install test
environment dependencies from thePoetrylockfile.⚠️This project is beta software and is under active development⚠️DocumentationFeature OverviewUsing the PluginInstallingQuick StartReferencesConfig OptionsRuntime OptionsErrorsOther NotesUnsupported Tox config optionsUpdating locked dependencies in a testenvUsing with an unmanaged Poetry installationDeveloping the PluginRoad MapSee theChangelogfor
release history.See also:official Tox pluginsandthe official Poetry documentation on using ToxFeature OverviewManage 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 DocumentationThis section is for users looking to integrate the plugin with their project or CI
system. For information on contributing to the plugin please see theDeveloper DocsInstallingThe recommended way to install the plugin is to add it to a project using Poetry:poetryadd-Gdevtox-poetry-installer[poetry]ℹ️Note:Always install the plugin with the[poetry]extra, unless you aremanaging the Poetry installation yourself.Alternatively, it can be installed directly to a virtual environment using Pip, though
this is not recommended:sourcesomevenv/bin/activate
pipinstalltox-poetry-installerAlternatively alternatively, it can be installed using the Toxrequiresoption by
adding the below totox.ini, though this is also not recommended:requires=tox-poetry-installer[poetry]== 0.10.2After installing, check that Tox recognizes the plugin by runningpoetry 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__.pyQuick StartCongratulations! 🎉 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 exampletox.inito install the other test environment dependencies
from the lockfile.Atestenvfrom the exampletox.iniwe're starting with is below:[testenv]description=Some very cool testsdeps=black== 20.8b1pylint >=2.4.4,<2.7.0mypy <0.800commands=...To update the config so that the testenv dependencies are installed from the lockfile, we
can replace the built-indepsoption with thelocked_depsoption 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:[testenv]description=Some very cool testslocked_deps=blackpylintmypycommands=...We can also add therequire_locked_depsoption 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-indepsoption:[testenv]description=Some very cool testsrequire_locked_deps=truelocked_deps=blackpylintmypycommands=...ℹ️Note:Settings configured on the maintestenvenvironment 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:[testenv]description=Some very cool testsrequire_locked_deps=truepoetry_dep_groups=devcommands=...ℹ️Note:Theinstall_dev_depsconfiguration option is deprecated. SeeConfiguration Optionsfor 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 therequire_locked_deps = trueoption, otherwise the environment will
error, and then we can add the unlocked dependency using the built-indepsoption:[testenv]description=Some very cool testsdeps=pytest >=5.6.0,<6.0.0locked_deps=blackpylintmypycommands=...ReferencesConfiguration OptionsAll options listed below are Tox environment options and can be applied to one or more
environment sections of thetox.inifile. They cannot be applied to the global Tox
configuration section.ℹ️Note:Settings configured on the maintestenvenvironment are inherited by
child test environments (for example,testenv:foo). To override this, specify the
setting in the child environment with a different value.OptionTypeDefaultDescriptionlocked_depsList[]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_depsBooleanFalseWhether the plugin should block attempts to install unlocked dependencies to the test environment. If enabled, then thetox_testenv_install_depsplugin hook will be intercepted and an error will be raised if the test environment has thedepsoption configured.install_project_depsBooleanTrueWhether all of the Poetry primary dependencies for the project package should be installed to the test environment.require_poetryBooleanFalseWhether Tox should be forced to fail if the plugin cannot import Poetry locally. IfFalsethen the plugin will be skipped for the test environment if Poetry cannot be imported. IfTruethen the plugin will force the environment to error and the Tox run to fail.poetry_dep_groupsList[]Names of Poetry dependency groups specified inpyproject.tomlto install to the test environment.ℹ️Note:Theinstall_dev_depsconfiguration option is deprecated and will be
removed in version 1.0.0. Please setpoetry_dep_groups = [dev]intox.inifor
environments that install the development dependencies.Runtime OptionsAll arguments listed below can be passed to thetoxcommand to modify runtime behavior
of the plugin.ArgumentTypeDefaultDescription--parallel-install-threadsInteger10Number 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 value0to entirely disable parallel installation.ℹ️Note:The--require-poetryruntime option is deprecated and will be removed in
version 1.0.0. Please setrequire_poetry = trueintox.inifor environments that
should fail if Poetry is not available.ℹ️Note:The--parallelize-locked-installoption is deprecated and will be removed
in version 1.0.0. Please use the--parallel-install-threadsoption.ErrorsThere 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/NameCauseExtraNotFoundErrorIndicates that theextrasconfig option specified an extra that is not configured by Poetry inpyproject.toml.LockedDepVersionConflictErrorIndicates that an item in thelocked_depsconfig option includes aPEP-508 version specifier(ex:pytest >=6.0, <6.1).LockedDepNotFoundErrorIndicates that an item specified in thelocked_depsconfig option does not match the name of a package in the Poetry lockfile.LockedDepsRequiredErrorIndicates that a test environment with therequire_locked_depsconfig option set totruealso specified unlocked dependencies using thedepsconfig option.PoetryNotInstalledErrorIndicates that thepoetrymodule could not be imported under the current runtime environment, andrequire_poetry = truewas specified.RequiresUnsafeDepErrorIndicates 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 thepyproject.tomlbeing out
of sync with the Poetry lockfile. If this is the case, than a warning will be logged
when Tox is run.Other NotesUnsupported Tox config optionsBelow 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_commandpip_predownloadindexserverusedevelopUpdating locked dependencies in a testenvWhen Poetry updates the version of a package in the lockfile (using eitherpoetry lockorpoetry update) then the plugin will automatically use this new version to install the
package to a test environment; there is no need to manually updatetox.iniafter
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--recreateoption) for the new version to be found and installed.ℹ️Note:To force Tox to always recreate a test environment therecreateconfig
option can be set.Using with an unmanaged Poetry installationIn 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--syncarguments to thepoetry installcommand 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 thepoetrypackage as an optional dependency that can be
installed using a setuptools extra also namedpoetry.⚠️Warning:This plugin requires Poetry to function. If the plugin is installed
without thepoetrysetuptools extra then Poetry must be installed independently for
the plugin to function properly.To skip installing thepoetrypackage as a dependency oftox-poetry-installer, do not
specify thepoetryextra when adding the plugin:# Adding the package without the "[poetry]" extra specifier so that# Poetry is not added as a transient dev-dependency:poetryadd-Gdevtox-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:poetryadd-Gdevtox-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: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 therequire_poetry = trueoption to the tox[testenv]configuration. See theConfig Optionsfor more information.Developer DocumentationAll project contributors and participants are expected to adhere to theContributor Covenant Code of Conduct, v2(external link).Thedevelbranch has the latest (and potentially unstable) changes. The stable releases
are tracked onGithub,PyPi, and in theChangelog.To report a bug, request a feature, or ask for assistance, pleaseopen an issue on the Github repository.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, pleasefork the repositoryandopen a pull request.Developing this project requiresPython 3.10+andPoetry 1.4or 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:# Clone the repository...# ...over HTTPSgitclonehttps://github.com/enpaul/tox-poetry-installer.git# ...over SSHgitclonegit@github.com:enpaul/tox-poetry-installer.gitcdtox-poetry-installer/# Create and configure the local development environmentmakedev# Run tests and CI locallymaketest# See additional make targetsmakehelpℹ️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 runpoetry run git commitor, alternatively,launch an environment shell.Road MapThis project is under active development and is classified as beta software, ready for
production environments on a provisional basis only.Beta classification was assigned withv0.6.0Stable classification will be assigned when the test suite covers an acceptable number
of use casesPath to BetaVerify that primary package dependencies (from the.packageenv) are installed
correctly using the Poetry backend.Support theextrasTox configuration option (#4)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)Add trivial tests to ensure the project metadata is consistent between the
pyproject.toml and the module constants.Update to usepoetry-coreand
improve robustness of the Tox and Poetry module imports to avoid potentially breaking
API changes in upstream packages.
(#2)Find and implement a way to mitigate theUNSAFE_DEPENDENCIES issuein
Poetry.(#6)Fix logging to make proper use of Tox's logging reporter infrastructure
(#3)Add configuration option for installing all dev-dependencies to a testenv
(#14)Path to StableEverything in Beta plus...Fully replace dependency onpoetrywith dependency onpoetry-core(#2)Add comprehensive unit testsAdd tests for each feature version of Tox between 3.8 and 3.20Add tests for Python-3.6, 3.7, 3.8, and 3.9Add Github Actions based CI