buildenv.extension

Classes

BuildEnvInfo	BuildEnv information holding object, used to give some context to extensions.
BuildEnvRenderer	Rendering interface for buildenv extensions
BuildEnvEntryPoint	Base class for buildenv entry points, to be contributed through "buildenv_entry_point" entry point
BuildEnvExtension	Base class for buildenv extensions, to be contributed through "buildenv_init" entry point
BuildEnvProjectTemplate	Base class for buildenv project templates, to be contributed through "buildenv_template" entry point

Module Contents

class buildenv.extension.BuildEnvInfo

BuildEnv information holding object, used to give some context to extensions.

venv_bin: pathlib.Path | None = None

Path to the virtual environment binary directory (i.e. the one with all installed scripts and executables)

project_root: pathlib.Path | None = None

Path to the project root directory, if any (None otherwise)

backend_name: str | None = None

Name of the buildenv backend in use, if any (None otherwise)

class buildenv.extension.BuildEnvRenderer

Bases: abc.ABC

Rendering interface for buildenv extensions

abstractmethod render(environment: jinja2.Environment, template: str, executable: bool = False, keywords: dict[str, str] | None = None, sub_path: pathlib.Path | str | None = None)

Render extension activation script from template

Parameters:

• environment – Jinja2 environment to use for rendering

• template – Template file to render (relative to provided environment)

• executable – States if target file as to be set as executable

• keyword – Map of keywords provided to template

• sub_path – Sub-path for the target file within the project

class buildenv.extension.BuildEnvEntryPoint(info: BuildEnvInfo)

Base class for buildenv entry points, to be contributed through “buildenv_entry_point” entry point

Parameters:

info – BuildEnvInfo object holding information about the build environment

info

class buildenv.extension.BuildEnvExtension(info: BuildEnvInfo)

Bases: BuildEnvEntryPoint

Base class for buildenv extensions, to be contributed through “buildenv_init” entry point

Parameters:

info – BuildEnvInfo object holding information about the build environment

abstractmethod init(force: bool) → None

Method called by buildenv backend when initializing environment.

The extension is supposed to perform some build logic initialization (once for all). This method will always be called by buildenv; the extension must decide by itself if it needs to perform some action or not.

The self.info attribute can be used to access to buildenv information.

Parameters:

force – Tells the extension if the –force argument was used on the buildenv init command line.

get_completion_commands() → list[buildenv.completion.CompletionCommand]

Method called by buildenv backend to get the list of commands to be completed.

The extension can use this method to provide its own completion commands.

Returns:

List of commands to be completed

generate_activation_scripts(renderer: BuildEnvRenderer)

Method called by buildenv backend when generating activation scripts.

The extension can use this method to generate its own activation scripts in the provided temporary directory. The default implementation does nothing.

Parameters:

renderer – Rendering interface to use for generating activation scripts

class buildenv.extension.BuildEnvProjectTemplate(info: BuildEnvInfo, name: str)

Bases: BuildEnvEntryPoint

Base class for buildenv project templates, to be contributed through “buildenv_template” entry point

Parameters:

• info – BuildEnvInfo object holding information about the build environment

• name – Template name, used to select the template when creating a new project; read from entry point definition on instance creation

property name: str

Template name, used to select the template when creating a new project

property description: str

Template description, used to describe the template to users when creating a new project

property preferred_backend: str

Preferred buildenv backend for this template; will be used by default (instead of detected one) on buildenv install if this template is selected, but can be overridden by user on command line.

property generated_files: set[pathlib.Path]

List of paths to the files generated by this template, relative to project root.

property weight: int

Template “weight”. Most weighted template will be the main template selected by default.

property auto_extra: bool

State if this template shall be automatically included in extra templates list by default.

abstractmethod generate_project_files(renderer: BuildEnvRenderer, packages: list[str], extra_templates: list[Self]) → None

Method called by buildenv backend when generating project files for a new project.

The extension is supposed to generate all the files needed for the project, using the provided renderer.

Parameters:

• renderer – Rendering interface to use for generating project files

• packages – additional packages to be added to the project

• extra_templates – additional templates to generate files from