nmk_base.common =============== .. py:module:: nmk_base.common .. autoapi-nested-parse:: Python module for **nmk-base** utility classes and builders 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.DownloadBuilder 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:: DownloadBuilder(model: nmk.model.model.NmkModel) Bases: :py:obj:`nmk.model.builder.NmkTaskBuilder` Generic builder logic to download a file from a URL .. py:method:: download(url: str, target: pathlib.Path, request_function: collections.abc.Callable[[str], requests.Response], request_kwargs: dict[str, Any] | None = None, extract: bool = False) Download file from provided URL and save it as main output :param url: URL to download file from :param target: Path to save/extract the downloaded file :param request_function: Function to use for the HTTP request. The function must behave like **requests.get** :param request_kwargs: Map of extra keyword arguments to be passed to the request function :param extract: Whether to extract the downloaded file if it's an archive (zip, tar.gz, or others). In this case, the main output is expected to be a directory instead of a file, and the downloaded file will be extracted into it. .. py:method:: build(url: str, request_function: str = 'requests.get', request_kwargs: dict[str, Any] | None = None, extract: bool = False) Build logic: download file from provided URL and save it as main output :param url: URL to download file from :param request_function: Function name to import and use for the HTTP request. The function must behave like **requests.get**; default is **requests.get**. :param request_kwargs: Map of extra keyword arguments to be passed to the request function :param extract: Whether to extract the downloaded file if it's an archive (zip, tar.gz, or others). In this case, the main output is expected to be a directory instead of a file, and the downloaded file will be extracted into it.