sphinx_polyversion.pyvenv

Subclasses of Environment supporting python virtual environments.

Classes

`Pip`(path, name, venv, *, args[, creator, ...])	Build Environment for using a venv and installing deps with pip.
`Poetry`(path, name, *, args[, env])	Build Environment for isolated builds with poetry.
`VenvWrapper`([system_site_packages, clear, ...])	Build your virtual environments using the build-in venv module.
`VirtualPythonEnvironment`(path, name, venv, *)	An environment for running build commands in a python virtual environment.
`VirtualenvWrapper`(args)	Build your virtual environments using the virtualenv package.

class sphinx_polyversion.pyvenv.Pip(path: Path, name: str, venv: str | Path, *, args: Iterable[str], creator: Callable[[Path], Any] | None = None, temporary: bool = False, env: dict[str, str] | None = None)[source]

Bases: VirtualPythonEnvironment

Build Environment for using a venv and installing deps with pip.

Use this to run the build commands in a python virtual environment and install dependencies with pip into the venv before the build.

Parameters:

path (Path) – The path of the current revision.
name (str) – The name of the environment (usually the name of the revision).
venv (Path) – The path of the python venv.
args (Iterable[str]) – The cmd arguments to pass to pip install.
creator (Callable[[Path], Any] | None, optional) – A callable for creating the venv, by default None
temporary (bool, optional) – A flag to specify whether the environment should be created in the temporary directory, by default False. If this is True, creator must not be None and venv will be treated relative to path.
env (dict[str, str], optional) – A dictionary of environment variables which are overridden in the virtual environment, by default None

async __aenter__() → Self

Set the venv up.

Raises:: BuildError – Running pip install failed.

class sphinx_polyversion.pyvenv.Poetry(path: Path, name: str, *, args: Iterable[str], env: dict[str, str] | None = None)[source]

Bases: VirtualPythonEnvironment

Build Environment for isolated builds with poetry.

Use this to use poetry to create an isolated python venv for each build and to install specific poetry dependency groups.

Parameters:

path (Path) – The path of the current revision.
name (str) – The name of the environment (usually the name of the revision).
args (Iterable[str]) – The cmd arguments to pass to poetry install.
env (dict[str, str], optional) – A dictionary of environment variables which are overidden in the virtual environment, by default None

async __aenter__() → Self

Set the poetry venv up.

Raises:: BuildError – Running poetry install failed.

class sphinx_polyversion.pyvenv.VenvWrapper(system_site_packages=False, clear=False, symlinks=False, upgrade=False, with_pip=False, prompt=None, upgrade_deps=False)[source]

Bases: EnvBuilder

Build your virtual environments using the build-in venv module.

async __call__(path: Path) → None

Create a virtual environment at the given location.

This runs self.create in a separate thread that can be awaited.

Parameters:: path (Path) – directory for the created venv

class sphinx_polyversion.pyvenv.VirtualPythonEnvironment(path: Path, name: str, venv: str | Path, *, creator: Callable[[Path], Any] | None = None, env: dict[str, str] | None = None)[source]

Bases: Environment

An environment for running build commands in a python virtual environment.

If you want to create the venv when this environment is entered you can provide a creator which will be called with the venv location to create the environment. You can use the VenvWrapper and VirtualenvWrapper classes for that. If creator isn’t provided it is expected that a python venv already exists at the given location.

Parameters:

path (Path) – The location of the current revision.
name (str) – The name of the environment (usually the name of the current revision).
venv (Path) – The path of the python venv.
creator (Callable[[Path], Any], optional) – A callable for creating the venv, by default None
env (dict[str, str], optional) – A dictionary of environment variables which are overridden in the virtual environment, by default None

path

The location of the current revision.

Type:: Path

name

The name of the environment.

Type:: str

venv

The path of the python venv.

Type:: Path

env

The user-specified environment variables for the virtual environment.

Type:: dict

async __aenter__() → Self: Set the build environment up.

activate(env: dict[str, str]) → dict[str, str]

Activate a python venv in a dictionary of environment variables.

Warning

This modifies the given dictionary in-place.

Parameters:: env (dict[str, str]) – The environment variable mapping to update.
Returns:: The dictionary that was passed with env.
Return type:: dict[str, str]
Raises:: FileNotFoundError – If no environment is located at the location venv.

apply_overrides(env: dict[str, str]) → dict[str, str]

Prepare the environment for the build.

This method is used to modify the environment before running a build command. It activates the python venv and overrides those environment variables that were passed to the constructor. PATH is never replaced but extended instead.

Warning

This modifies the given dictionary in-place.

Parameters:: env (dict[str, str]) – The environment to modify.
Returns:: The updated environment.
Return type:: dict[str, str]

async create_venv() → None

Create the virtual python environment.

This calls creator if provided otherwise it does nothing.

Override this to customize how and when the venv is created.

async run(*cmd: str, **kwargs: Any) → Tuple[str | bytes | None, str | bytes | None, int]

Run a OS process in the environment.

This implementation passes the arguments to asyncio.create_subprocess_exec(). But alters env to activates the correct python and overrides the use-specified vars using prepare_env(). If a python venv is already activated this activation is overridden.

Returns:

stdout (str | None) – The output of the command,
stderr (str | None) – The error output of the command
returncode (int | None) – The returncode of the command

class sphinx_polyversion.pyvenv.VirtualenvWrapper(args: Sequence[str])[source]

Bases: object

Build your virtual environments using the virtualenv package.

The package can be found on pypi. Call instances of this class with a path to create a venv at the given location.

async __call__(path: Path) → None: Build the venv at the given location in a separate thread.