buildenv.backends.backend ========================= .. py:module:: buildenv.backends.backend Attributes ---------- .. autoapisummary:: buildenv.backends.backend.LOCKFLAG_NAME Classes ------- .. autoapisummary:: buildenv.backends.backend.EnvBackend buildenv.backends.backend.EnvBackendWithRequirements buildenv.backends.backend.MutableEnvBackend Module Contents --------------- .. py:data:: LOCKFLAG_NAME :value: 'buildenv.lock' File name for the "flag" file, stating if the project is locked or not .. py:class:: EnvBackend(venv_bin: pathlib.Path, project_path: pathlib.Path | None = None, verbose_subprocess: bool = True, shell_name: str = 'bash') Bases: :py:obj:`abc.ABC` Helper class that provides a standard way to create an ABC using inheritance. .. py:property:: is_locked :type: bool State if this environment is locked (i.e. if it has a lockfile) :return: True if environment is locked .. py:property:: lock_file :type: pathlib.Path :abstractmethod: Path to the backend specific lockfile .. py:property:: version :type: int Main version detected from loading scripts .. py:method:: 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 :param args: subprocess commands and arguments :param check: if True and subprocess return code is not 0, raise an exception :param cwd: current working directory for subprocess :param env: environment variables map for subprocess :param verbose: override verbose subprocess logging for this call (default: use backend setting) :param error_msg: error message to be logged in case of subprocess failure :param log_as_cmd: if True, log the command as a CMD level message (only if backend setting is verbose) :return: completed process instance .. py:property:: venv_name :type: str Venv folder name, if any (empty string otherwise) .. py:property:: venv_root :type: pathlib.Path Venv root folder path .. py:property:: project_path :type: pathlib.Path Project path :return: project path .. py:property:: use_requirements :type: bool State if this backend uses requirements.txt file .. py:property:: shell_instance :type: buildenv._shells.factory.EnvShell Get the shell instance used by this backend .. py:property:: name :type: str :abstractmethod: Environment backend implementation name .. py:property:: command :type: str Backend setup command .. py:property:: install_url :type: str :abstractmethod: Environment backend install instructions URL .. py:method:: is_mutable() -> bool State if this backend supports installed packages update once created :return: True if environment is mutable .. py:method:: has_pip() -> bool :abstractmethod: State if this backend includes pip tool :return: True if environment includes pip .. py:method:: 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 :param force: Force re-initialization of extensions :param skip_ext: List of extensions names to skip :param no_ext: Skip all extensions initialization :param show_updates_from: Path to a file to show updates from :return: always 0 .. py:method:: shell(show_updates_from: pathlib.Path | None = None, command: str | None = None) -> int Launch an interractive shell from the backend :param show_updates_from: Path to a file to show updates from :param command: command to be executed in the shell :return: shell exit code .. py:method:: run(command: str) -> int Run command in the backend shell :param command: command to be executed :return: command exit code .. py:method:: 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 :param packages: additional packages to install :param template: template used to create a new project :param extra_templates: additional templates to generate files from :param clean_old_files: clean legacy buildenv files (python loader, config file) :return: command exit code .. py:method:: add_packages(packages: list[str]) Add packages to the environment (if mutable) :param packages: list of packages to add .. py:method:: 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 :param log_level: logging level to use for file generation :return: command exit code .. py:method:: 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 :return: command exit code .. py:method:: 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. :param full: if True, check for updates from remote repositories (may be slow); if False, ignore already installed packages :param only_deps: if True, upgrade only dependencies (not current project) :param print_updates: if True, print updates after upgrade :return: command exit code .. py:method:: handle_updates(old_packages: dict[str, str], print_updates: bool = True) Handle packages updates from previous versions :param old_packages: map of old installed packages versions (indexed by package name) :param print_updates: if True, print updates after upgrade .. py:method:: print_updates(old_packages: dict[str, str], ignored_packages: set[str] | None = None) Pretty print packages updates to stdout :param old_packages: map of old installed packages versions (indexed by package name) :param ignored_packages: set of package names to ignore in updates printing .. py:property:: installed_packages :type: dict[str, str] List installed packages in this environment :return: map of installed packages versions (indexed by package name) .. py:method:: list() -> int List installed packages in this environment and print them to stdout :return: command exit code .. py:method:: dump(output_file: pathlib.Path, log_level: int = logging.INFO) Dump installed packages in this environment to a requirements-like file :param output_file: path to the output requirements file :param log_level: logging level to use for file generation .. py:class:: EnvBackendWithRequirements(venv_bin: pathlib.Path, project_path: pathlib.Path | None = None, verbose_subprocess: bool = True, shell_name: str = 'bash') Bases: :py:obj:`EnvBackend` Helper class that provides a standard way to create an ABC using inheritance. .. py:property:: use_requirements :type: bool State if this backend uses requirements.txt file .. py:property:: lock_file :type: pathlib.Path Path to the backend specific lockfile .. py:method:: handle_updates(old_packages: dict[str, str], print_updates: bool = True) Handle packages updates from previous versions :param old_packages: map of old installed packages versions (indexed by package name) :param print_updates: if True, print updates after upgrade .. py:class:: MutableEnvBackend(venv_bin: pathlib.Path, project_path: pathlib.Path | None = None, verbose_subprocess: bool = True, shell_name: str = 'bash') Bases: :py:obj:`EnvBackend` Helper class that provides a standard way to create an ABC using inheritance. .. py:method:: is_mutable() -> bool State if this backend supports installed packages update once created :return: True if environment is mutable