nox-poetry
Use Poetry inside Nox sessions
This package provides a drop-in replacement for the nox.session
decorator,
and for the nox.Session
object passed to user-defined session functions.
This enables session.install
to install packages at the versions specified in the Poetry lock file.
from nox_poetry import session
@session(python=["3.10", "3.9"])
def tests(session):
session.install("pytest", ".")
session.run("pytest")
Disclaimer: This project is not affiliated with Nox, and not an official Nox plugin.
Install nox-poetry
from the Python Package Index:
$ pip install nox-poetry
Important: This package must be installed into the same environment that Nox is run from. If you installed Nox using pipx, use the following command to install this package into the same environment:
$ pipx inject nox nox-poetry
You need to have a Poetry installation on your system.
nox-poetry
uses Poetry via its command-line interface.
Import the @session
decorator from nox_poetry
instead of nox
.
There is nothing else you need to do.
The session.install
method automatically honors the Poetry lock file when installing dependencies.
This allows you to manage packages used in Nox sessions as development dependencies in Poetry.
This works because session functions are passed instances of nox_poetry.Session
,
a proxy for nox.Session
adding Poetry-related functionality.
Behind the scenes, nox-poetry uses Poetry to export a constraints file and build the package.
For more fine-grained control, additional utilities are available under the session.poetry
attribute:
session.poetry.installroot(distribution_format=["wheel"|"sdist"])
session.poetry.build_package(distribution_format=["wheel"|"sdist"])
session.poetry.export_requirements()
Note that distribution_format
is a keyword-only parameter.
Here is a comparison of the different installation methods:
session.install(...)
to install specific development dependencies, e.g. session.install("pytest")
.session.install(".")
(or session.poetry.installroot()
) to install your own package.session.run_always("poetry", "install", external=True)
to install your package with all development dependencies.Please read the next section for the tradeoffs of each method.
Let's look at an example:
from nox_poetry import session
@session(python=["3.10", "3.9"])
def tests(session):
session.install("pytest", ".")
session.run("pytest")
This session performs the following steps:
pytest
package.pytest
to run the test suite against the installation.Consider what would happen in this session
if we had imported @session
from nox
instead of nox_poetry
:
pytest
dependency would not be constrained at all.Unpinned dependencies mean that your checks are not reproducible and deterministic,
which can lead to surprises in Continuous Integration and when collaborating with others.
You can solve these issues by declaring pytest
as a development dependency,
and installing your package and its dependencies using poetry install
:
@nox.session
def tests(session: Session) -> None:
"""Run the test suite."""
session.run_always("poetry", "install", external=True)
session.run("pytest")
Unfortunately, this approach comes with its own set of problems:
nox-poetry
uses a third approach:
session.install
method.In summary, this approach brings the following advantages:
pytest
as development dependencies in Poetry.Contributions are very welcome. To learn more, see the Contributor Guide.
Distributed under the terms of the MIT license, nox-poetry is free and open source software.
If you encounter any problems, please file an issue along with a detailed description.
This project was generated from @cjolowicz's Hypermodern Python Cookiecutter template.