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
   nmk_base.common.MultiChoiceResolver
   nmk_base.common.MultiStrChoiceResolver
   nmk_base.common.MultiListChoiceResolver
   nmk_base.common.MultiDictChoiceResolver


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], file_updated_info: str | None = None) -> 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
      :param file_updated_info: Config item name where to store information that output file has been updated
      :return: Rendered template string
      :throw: AssertionError if unknown keyword is referenced in template



   .. py:method:: build(template: str, kwargs: dict[str, str] | None = None, file_updated_info: str | None = None)

      Default build behavior: generate main output file from provided template

      :param template: Path to the Jinja template to use for generation
      :param kwargs: Map of keywords for templates rendering, indexed by name
      :param file_updated_info: Config item name where to store information that output file has been updated



.. 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', kwargs: dict[str, str] = None)

      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; only non-empty items are considered (no empty section will be added)
      :param plugin_name: Plugin name to be inserted in generated file heading comment
      :param kwargs: Map of keywords for templates rendering, indexed by name



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



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

   Bases: :py:obj:`nmk.model.resolver.NmkConfigResolver`


   Multi-choice config item resolver base class


   .. py:method:: get_value(name: str, key: int | str | bool, choices: dict[int | str | bool, _MultiChoiceValue], default: _MultiChoiceValue) -> _MultiChoiceValue

      Resolve multi-choice config item value using provided key and available choices

      :param name: config item name
      :param key: key to select value
      :param choices: available choices
      :param default: default value
      :return: item value



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

   Bases: :py:obj:`MultiChoiceResolver`, :py:obj:`nmk.model.resolver.NmkStrConfigResolver`


   Multi-choice string config item resolver class


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

   Bases: :py:obj:`MultiChoiceResolver`, :py:obj:`nmk.model.resolver.NmkListConfigResolver`


   Multi-choice list config item resolver class


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

   Bases: :py:obj:`MultiChoiceResolver`, :py:obj:`nmk.model.resolver.NmkDictConfigResolver`


   Multi-choice dict config item resolver class