buildenv.backends.backend

Attributes

LOCKFLAG_NAME

File name for the "flag" file, stating if the project is locked or not

Classes

EnvBackend	Helper class that provides a standard way to create an ABC using
EnvBackendWithRequirements	Helper class that provides a standard way to create an ABC using
MutableEnvBackend	Helper class that provides a standard way to create an ABC using

Module Contents

buildenv.backends.backend.LOCKFLAG_NAME = 'buildenv.lock'

File name for the “flag” file, stating if the project is locked or not

class buildenv.backends.backend.EnvBackend(venv_bin: pathlib.Path, project_path: pathlib.Path | None = None, verbose_subprocess: bool = True, shell_name: str = 'bash')

Bases: abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

property is_locked: bool

State if this environment is locked (i.e. if it has a lockfile)

Returns:

True if environment is locked

property lock_file: pathlib.Path

Abstractmethod:

Path to the backend specific lockfile

property version: int

Main version detected from loading scripts

subprocess(args: list[str], check: bool = True, cwd: pathlib.Path | None = None, env: dict[str, str] | None = None, verbose: bool | None = None, error_msg: str | None = None, log_as_cmd: bool = False) → subprocess.CompletedProcess[str]

Execute subprocess, and logs output/error streams + error code

Parameters:

• args – subprocess commands and arguments

• check – if True and subprocess return code is not 0, raise an exception

• cwd – current working directory for subprocess

• env – environment variables map for subprocess

• verbose – override verbose subprocess logging for this call (default: use backend setting)

• error_msg – error message to be logged in case of subprocess failure

• log_as_cmd – if True, log the command as a CMD level message (only if backend setting is verbose)

Returns:

completed process instance

property venv_name: str

Venv folder name, if any (empty string otherwise)

property venv_root: pathlib.Path

Venv root folder path

property project_path: pathlib.Path

Project path

Returns:

project path

property use_requirements: bool

State if this backend uses requirements.txt file

property shell_instance: buildenv._shells.factory.EnvShell

Get the shell instance used by this backend

property name: str

Abstractmethod:

Environment backend implementation name

property command: str

Backend setup command

property install_url: str

Abstractmethod:

Environment backend install instructions URL

is_mutable() → bool

State if this backend supports installed packages update once created

Returns:

True if environment is mutable

abstractmethod has_pip() → bool

State if this backend includes pip tool

Returns:

True if environment includes pip

init(force: bool = False, skip_ext: list[str] | None = None, no_ext: bool = False, show_updates_from: pathlib.Path | None = None) → int

Initialize the backend extensions

Parameters:

• force – Force re-initialization of extensions

• skip_ext – List of extensions names to skip

• no_ext – Skip all extensions initialization

• show_updates_from – Path to a file to show updates from

Returns:

always 0

shell(show_updates_from: pathlib.Path | None = None, command: str | None = None) → int

Launch an interractive shell from the backend

Parameters:

• show_updates_from – Path to a file to show updates from

• command – command to be executed in the shell

Returns:

shell exit code

run(command: str) → int

Run command in the backend shell

Parameters:

command – command to be executed

Returns:

command exit code

install(packages: list[str] | None = None, template: buildenv.extension.BuildEnvProjectTemplate | None = None, extra_templates: list[buildenv.extension.BuildEnvProjectTemplate] | None = None, clean_old_files: bool = True) → int

Install loading scripts for the backend

Parameters:

• packages – additional packages to install

• template – template used to create a new project

• extra_templates – additional templates to generate files from

• clean_old_files – clean legacy buildenv files (python loader, config file)

Returns:

command exit code

add_packages(packages: list[str])

Add packages to the environment (if mutable)

Parameters:

packages – list of packages to add

lock(log_level: int = logging.INFO) → int

Create a lockfile for this environment, so that next time the environment is loaded, it will be restored to this state

Parameters:

log_level – logging level to use for file generation

Returns:

command exit code

unlock() → int

Remove the lockfile for this environment, so that next time the environment is loaded, it will not be restored to a previous state

Returns:

command exit code

upgrade(full: bool = True, only_deps: bool = False, print_updates: bool = True) → int

Upgrade all packages in this environment to their latest version. Also dumps upgraded versions to the console.

Parameters:

• full – if True, check for updates from remote repositories (may be slow); if False, ignore already installed packages

• only_deps – if True, upgrade only dependencies (not current project)

• print_updates – if True, print updates after upgrade

Returns:

command exit code

handle_updates(old_packages: dict[str, str], print_updates: bool = True)

Handle packages updates from previous versions

Parameters:

• old_packages – map of old installed packages versions (indexed by package name)

• print_updates – if True, print updates after upgrade

print_updates(old_packages: dict[str, str], ignored_packages: set[str] | None = None)

Pretty print packages updates to stdout

Parameters:

• old_packages – map of old installed packages versions (indexed by package name)

• ignored_packages – set of package names to ignore in updates printing

property installed_packages: dict[str, str]

List installed packages in this environment

Returns:

map of installed packages versions (indexed by package name)

list() → int

List installed packages in this environment and print them to stdout

Returns:

command exit code

dump(output_file: pathlib.Path, log_level: int = logging.INFO)

Dump installed packages in this environment to a requirements-like file

Parameters:

• output_file – path to the output requirements file

• log_level – logging level to use for file generation

class buildenv.backends.backend.EnvBackendWithRequirements(venv_bin: pathlib.Path, project_path: pathlib.Path | None = None, verbose_subprocess: bool = True, shell_name: str = 'bash')

Bases: EnvBackend

Helper class that provides a standard way to create an ABC using inheritance.

property use_requirements: bool

State if this backend uses requirements.txt file

property lock_file: pathlib.Path

Path to the backend specific lockfile

handle_updates(old_packages: dict[str, str], print_updates: bool = True)

Handle packages updates from previous versions

Parameters:

• old_packages – map of old installed packages versions (indexed by package name)

• print_updates – if True, print updates after upgrade

class buildenv.backends.backend.MutableEnvBackend(venv_bin: pathlib.Path, project_path: pathlib.Path | None = None, verbose_subprocess: bool = True, shell_name: str = 'bash')

Bases: EnvBackend

Helper class that provides a standard way to create an ABC using inheritance.

is_mutable() → bool

State if this backend supports installed packages update once created

Returns:

True if environment is mutable