nox-poetry

Helper functions for using Poetry inside Nox sessions

Installation

You can install nox-poetry via pip 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

Usage

• Use nox_poetry.install_package(session) to install your own package.
• Use nox_poetry.install(session, *args) to install third-party packages.
• Packages installed like this must be declared as development dependencies using Poetry.

For example, the following Nox session runs your test suite:

# noxfile.py
import nox
from nox.sessions import Session
from nox_poetry import install, install_package

@nox.session
def tests(session: Session) -> None:
    """Run the test suite."""
    install_package(session)
    install(session, "pytest")
    session.run("pytest", *session.posargs)

Why?

Compare the session above to one written without this package:

@nox.session
def tests(session: Session) -> None:
    """Run the test suite."""
    session.install(".")
    session.install("pytest")
    session.run("pytest", *session.posargs)

This session has several problems:

• Poetry is installed as a build backend every time.
• Package dependencies are only constrained by the wheel metadata, not by the lock file (pinned).
• The pytest dependency is not constrained at all.

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("poetry", "install", external=True)
    session.run("pytest", *session.posargs)

Unfortunately, this approach creates problems of its own:

• Checks run against an editable installation of your package, i.e. your local copy of the code, instead of the installed wheel your users see.
• The package is installed, as well as all of its core and development dependencies. This is wasteful when you only need to run black or flake8. It also goes against the idea of running checks in isolated environments.
• Poetry may decide to install packages into its own virtual environment instead of the one provided by Nox.

nox-poetry uses a third approach. Third-party packages are installed by exporting the lock file in requirements.txt format, and passing it as a constraints file to pip. When installing your own package, Poetry is used to build a wheel, which is then installed by pip. This approach has some advantages:

• You can declare tools like pytest as development dependencies in Poetry.
• Dependencies are pinned by Poetry's lock file, making checks predictable and deterministic.
• You can run checks against an installed wheel, instead of your local copy of the code.
• Every tool can run in an isolated environment with minimal dependencies.
• No need to install your package with all its dependencies if all you need is some linter.

For more details, take a look at this article.

API

nox_poetry.install(session, *args):

Install development dependencies into a Nox session using Poetry.

The nox_poetry.install function installs development dependencies into a Nox session, using the versions specified in Poetry's lock file. The function arguments are the same as those for nox.sessions.Session.install: The first argument is the Session object, and the remaining arguments are command-line arguments for pip install, typically just the package or packages to be installed.

nox_poetry.install_package(session):

Install the package into a Nox session using Poetry.

The nox_poetry.install_package function installs your package into a Nox session, including the core dependencies as specified in Poetry's lock file. This is done by building a wheel from the package, and installing it using pip. Dependencies are installed in the same way as in the nox_poetry.install function, i.e. using a constraints file. Its only argument is the Session object from Nox.

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

nox-poetry is free and open source software, distributed under the terms of the MIT license.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Credits

This project was generated from @cjolowicz's Hypermodern Python Cookiecutter template.