Reference¶

Using Poetry in Nox sessions.

This package provides a drop-in replacement for the session() decorator, and for the Session object passed to user-defined session functions. This enables session.install to install packages at the versions specified in the Poetry lock file.

Example

>>> @session(python=["3.9", "3.10"])
... def tests(session: Session) -> None:
...     session.install("pytest", ".")
...     session.run("pytest")

It also provides helper functions that allow more fine-grained control:

session.poetry.installroot
session.poetry.build_package
session.poetry.export_requirements

Two constants are defined to specify the format for distribution archives:

WHEEL
SDIST

Functions¶

nox_poetry.session(*args, **kwargs)¶

Drop-in replacement for the nox.session() decorator.

Use this decorator instead of @nox.session. Session functions are passed Session instead of nox.sessions.Session; otherwise, the decorators work exactly the same.

Parameters:

args (Any) – Positional arguments are forwarded to nox.session.
kwargs (Any) – Keyword arguments are forwarded to nox.session.

Returns:

The decorated session function.

Return type:

Any

Classes¶

class nox_poetry.Session(session)¶

Proxy for nox.sessions.Session, passed to session functions.

This class overrides session.install, and provides Poetry-related utilities:

Session.poetry.installroot
Session.poetry.build_package
Session.poetry.export_requirements

Parameters:: session (Session)

_PoetrySession.install(*args, **kwargs)¶

Install packages into a Nox session using Poetry.

This function installs packages into the session’s virtual environment. It is a wrapper for nox.sessions.Session.install(), whose positional arguments are command-line arguments for pip install, and whose keyword arguments are the same as those for nox.sessions.Session.run().

If a positional argument is “.”, a wheel is built using build_package(), and the argument is replaced with the file URL returned by that function. Otherwise, the argument is forwarded unchanged.

In addition, a constraints file is generated for the package dependencies using export_requirements(), and passed to pip install via its --constraint option. This ensures that any package installed will be at the version specified in Poetry’s lock file.

Parameters:

args (str) – Command-line arguments for pip install.
kwargs (Any) – Keyword-arguments for session.install. These are the same as those for nox.sessions.Session.run().

Return type:

None

_PoetrySession.installroot(*, distribution_format=DistributionFormat.WHEEL, extras=())¶

Install the root package into a Nox session using Poetry.

This function installs the package located in the current directory into the session’s virtual environment.

A constraints file is generated for the package dependencies using export_requirements(), and passed to pip install via its --constraint option. This ensures that core dependencies are installed using the versions specified in Poetry’s lock file.

Parameters:

distribution_format (str) – The distribution format, either wheel or sdist.
extras (Iterable[str]) – Extras to install for the package.

Return type:

None

_PoetrySession.export_requirements()¶

Export a requirements file from Poetry.

This function uses poetry export to generate a requirements file containing the project dependencies at the versions specified in poetry.lock. The requirements file includes both core and development dependencies.

The requirements file is stored in a per-session temporary directory, together with a hash digest over poetry.lock to avoid generating the file when the dependencies have not changed since the last run.

Returns:: The path to the requirements file.
Return type:: Path

_PoetrySession.build_package(*, distribution_format=DistributionFormat.WHEEL)¶

Build a distribution archive for the package.

This function uses poetry build to build a wheel or sdist archive for the local package, as specified via the distribution_format parameter. It returns a file URL with the absolute path to the built archive.

Parameters:: distribution_format (str) – The distribution format, either wheel or sdist.
Returns:: The file URL for the distribution package.
Return type:: str

Constants¶

nox_poetry.WHEEL: str = DistributionFormat.WHEEL¶: A wheel archive.

nox_poetry.SDIST: str = DistributionFormat.SDIST¶: A source archive.