nmk_base.common
===============

.. py:module:: nmk_base.common

.. autoapi-nested-parse::

   Python module for **nmk-base** utility classes.



Classes
-------

.. autoapisummary::

   nmk_base.common.TemplateBuilder
   nmk_base.common.TomlFileBuilder
   nmk_base.common.MkdirBuilder
   nmk_base.common.ProcessBuilder
   nmk_base.common.CleanBuilder


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

.. py:class:: TemplateBuilder(model: nmk.model.model.NmkModel)

   Bases: :py:obj:`nmk.model.builder.NmkTaskBuilder`


   Generic builder logic to generate files from templates


   .. py:method:: relative_path(v: str) -> str

      Make an absolute path as project relative if possible

      :param v: Path string to be converted
      :return: Project relative path (if possible); unchanged input value otherwise



   .. py:method:: config_value(config_name: str) -> Any

      Get config value by name & turn absolute paths to project relative ones (if possible)

      :param config_name: Config item name
      :return: Config item value



   .. py:method:: render_template(template: pathlib.Path, kwargs: dict[str, str]) -> str

      Render template into a string, with provided keywords and config items

      :param template: Path to template file to be rendered
      :param kwargs: Map of keywords for templates rendering, indexed by name
      :return: Rendered template string
      :throw: AssertionError if unknown keyword is referenced in template



   .. py:method:: build_from_template(template: pathlib.Path, output: pathlib.Path, kwargs: dict[str, str]) -> str

      Generate file from template

      :param template: Path to template file to be rendered
      :param output: Path to output file to be generated
      :param kwargs: Map of keywords for templates rendering, indexed by name
      :return: Rendered template string
      :throw: AssertionError if unknown keyword is referenced in template



   .. py:method:: build(template: str)

      Default build behavior: generate main output file from provided template

      :param template: Path to the Jinja template to use for generation



.. py:class:: TomlFileBuilder(model: nmk.model.model.NmkModel)

   Bases: :py:obj:`TemplateBuilder`


   Generic builder logic to generate TOML files from templates and contributed items


   .. py:method:: build(fragment_files: list[str], items: dict, plugin_name: str = 'nmk-base')

      Generates toml file from fragments and items

      :param fragment_files: List of fragment files (processed as Jinja templates) to be merged
      :param items: Dict of toml items to be merged
      :param plugin_name: Plugin name to be inserted in generated file heading comment



.. py:class:: MkdirBuilder(model: nmk.model.model.NmkModel)

   Bases: :py:obj:`nmk.model.builder.NmkTaskBuilder`


   Generic builder logic to create directory


   .. py:method:: build()

      Build logic:
      create specified directory (main output of the task)



.. py:class:: ProcessBuilder(model: nmk.model.model.NmkModel)

   Bases: :py:obj:`nmk.model.builder.NmkTaskBuilder`


   Generic builder logic to call a sub-process


   .. py:method:: build(cmd: Union[str, list[str]], verbose: bool = False)

      Build logic:

      * call subprocess specified through **cmd** parameter; process is invoked in project directory
      * depending on the **verbose** parameter, redirect output to stdout (if True) or to nmk logs (if False)
      * touch the specified output file

      :param cmd: process command line; may be a string or a list of parameters
      :param verbose: states if the process output shall be displayed in stdout or saved in logs



.. py:class:: CleanBuilder(model: nmk.model.model.NmkModel)

   Bases: :py:obj:`nmk.model.builder.NmkTaskBuilder`


   Generic builder logic to clean a directory


   .. py:method:: build(path: str)

      Build logic: delete (recursively) provided directory, if it exists

      :param path: Directory to be deleted