buildenv.extension
==================

.. py:module:: buildenv.extension


Classes
-------

.. autoapisummary::

   buildenv.extension.BuildEnvInfo
   buildenv.extension.BuildEnvRenderer
   buildenv.extension.BuildEnvEntryPoint
   buildenv.extension.BuildEnvExtension
   buildenv.extension.BuildEnvProjectTemplate


Module Contents
---------------

.. py:class:: BuildEnvInfo

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


   .. py:attribute:: venv_bin
      :type:  pathlib.Path | None
      :value: None


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



   .. py:attribute:: project_root
      :type:  pathlib.Path | None
      :value: None


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



   .. py:attribute:: backend_name
      :type:  str | None
      :value: None


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



.. py:class:: BuildEnvRenderer

   Bases: :py:obj:`abc.ABC`


   Rendering interface for buildenv extensions


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


      Render extension activation script from template

      :param environment: Jinja2 environment to use for rendering
      :param template: Template file to render (relative to provided environment)
      :param executable: States if target file as to be set as executable
      :param keyword: Map of keywords provided to template
      :param sub_path: Sub-path for the target file within the project



.. py:class:: BuildEnvEntryPoint(info: BuildEnvInfo)

   Base class for **buildenv** entry points, to be contributed through "buildenv_entry_point" entry point

   :param info: BuildEnvInfo object holding information about the build environment


   .. py:attribute:: info


.. py:class:: BuildEnvExtension(info: BuildEnvInfo)

   Bases: :py:obj:`BuildEnvEntryPoint`


   Base class for **buildenv** extensions, to be contributed through "buildenv_init" entry point

   :param info: BuildEnvInfo object holding information about the build environment


   .. py:method:: init(force: bool) -> None
      :abstractmethod:


      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.

      :param force: Tells the extension if the **--force** argument was used on the **buildenv init** command line.



   .. py:method:: 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.

      :return: List of commands to be completed



   .. py:method:: 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.

      :param renderer: Rendering interface to use for generating activation scripts



.. py:class:: BuildEnvProjectTemplate(info: BuildEnvInfo, name: str)

   Bases: :py:obj:`BuildEnvEntryPoint`


   Base class for **buildenv** project templates, to be contributed through "buildenv_template" entry point

   :param info: BuildEnvInfo object holding information about the build environment
   :param name: Template name, used to select the template when creating a new project; read from entry point definition on instance creation


   .. py:property:: name
      :type: str


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



   .. py:property:: description
      :type: str


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



   .. py:property:: preferred_backend
      :type: 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.



   .. py:property:: generated_files
      :type: set[pathlib.Path]


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



   .. py:property:: weight
      :type: int


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



   .. py:property:: auto_extra
      :type: bool


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



   .. py:method:: generate_project_files(renderer: BuildEnvRenderer, packages: list[str], extra_templates: list[Self]) -> None
      :abstractmethod:


      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.

      :param renderer: Rendering interface to use for generating project files
      :param packages: additional packages to be added to the project
      :param extra_templates: additional templates to generate files from