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.8", "3.9"])
... def tests(session: Session) -> None:
... session.install("pytest", ".")
... session.run("pytest")
It also provides helper functions that allow more fine-grained control:
Two constants are defined to specify the format for distribution archives:
Functions#
- nox_poetry.session(*args, **kwargs)#
Drop-in replacement for the
nox.session()
decorator.Use this decorator instead of
@nox.session
. Session functions are passedSession
instead ofnox.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:- 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 fornox.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 topip 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 fornox.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.