makejinja 2.3.4__tar.gz → 2.4.0__tar.gz

{makejinja-2.3.4 → makejinja-2.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: makejinja
-Version: 2.3.4
-Summary: makejinja is a CLI tool and Python library to automatically generate files from Jinja2 templates. Use it to easily generate complex Home Assistant dashboards!
+Version: 2.4.0
+Summary: Generate entire directory structures using Jinja templates with support for external data and custom plugins.
 Home-page: https://mirkolenz.github.io/makejinja/
 License: MIT
 Keywords: jinja2,home-assistant,hassio,dashboard,lovelace,template,generator,cli,tool,library
@@ -33,24 +33,25 @@ Requires-Dist: immutables (>=0.20,<0.21)
 Requires-Dist: jinja2 (>=3.1,<4.0)
 Requires-Dist: pyyaml (>=6.0,<7.0)
 Requires-Dist: rich-click (>=1.7,<2.0)
-Requires-Dist: typed-settings[attrs,cattrs,click] (>=23.1,<24.0)
+Requires-Dist: typed-settings[attrs,cattrs,click] (>=23.1,<25)
 Project-URL: Documentation, https://mirkolenz.github.io/makejinja/makejinja/cli.html
 Project-URL: Repository, https://github.com/mirkolenz/makejinja
 Description-Content-Type: text/markdown
 
 <!-- markdownlint-disable MD033 MD041 -->
+<h2><p align="center">makejinja</p></h2>
 <p align="center">
   <img width="256px" alt="makejinja logo" src="https://raw.githubusercontent.com/mirkolenz/makejinja/main/assets/logo.png" />
 </p>
 <p align="center">
   <a href="https://pypi.org/project/makejinja/">PyPI</a> |
+  <a href="https://github.com/users/mirkolenz/packages/container/package/makejinja">Docker</a> |
   <a href="https://mirkolenz.github.io/makejinja">Docs</a> |
   <a href="https://github.com/mirkolenz/makejinja/tree/main/tests/data">Example</a> |
-  <a href="https://jinja.palletsprojects.com/en/3.1.x/templates">Templating</a>
+  <a href="https://jinja.palletsprojects.com/en/3.1.x/templates">Jinja reference</a>
 </p>
 <p align="center">
-  makejinja is a CLI tool and Python library to automatically generate files from Jinja2 templates.
-  Use it to easily generate complex Home Assistant dashboards!
+  Generate entire directory structures using Jinja templates with support for external data and custom plugins.
 </p>
 
 ---
@@ -58,22 +59,18 @@ Description-Content-Type: text/markdown
 # makejinja
 
 makejinja can be used to automatically generate files from [Jinja templates](https://jinja.palletsprojects.com/en/3.1.x/templates).
-This allows you to load variables from external files or create repeating patterns via loops.
-It is conceptually similar to [gomplate](https://github.com/hairyhenderson/gomplate), but is built on Python and Jinja instead of Go.
+It is conceptually similar to [Ansible templates](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/template_module.html) since both are built on top of Jinja.
+However, makejinja is a standalone tool that can be used without Ansible and offers some advanced features like custom plugins.
 A use case for this tool is generating config files for [Home Assistant](https://www.home-assistant.io/):
 Using the same language that the built-in templates use, you can greatly simplify your configuration.
 An [example for Home Assistant](https://github.com/mirkolenz/makejinja/tree/main/tests/data) can be found in the tests directory.
 
-## Features
+## Highlights
 
-- Recursively convert nested directories containing template files. One can even specify a pattern to specify relevant files in a folder.
+- Recursively render nested directories containing template files to a common output directory.
 - Load data files containing variables to use in your Jinja templates from YAML, TOML, and Python files.
-- Use custom functions in your Jinja templates by loading custom filters and/or globals.
-- Easily load bundled as well as custom Jinja extensions.
-- Tailor the whitespace behavior to your needs.
-- Use custom delimiters for Jinja blocks/comments/variables.
-- Modify _all_ init options for the Jinja environment.
-- Write custom **Python loaders** that implement a subset of our fully typed [abstract loader class](https://mirkolenz.github.io/makejinja/makejinja/loader.html#AbstractLoader)
+- Write custom [plugins](https://mirkolenz.github.io/makejinja/makejinja/plugin.html#Plugin) to extend the functionality of makejinja.
+- Adjust all Jinja options (e.g., whitespace behavior and delimiters) to your needs via CLI flags or a config file.
 
 ## Installation
 
@@ -82,36 +79,34 @@ It can be used as a CLI tool or as a Python library.
 
 ### PIP
 
-makejinja is available via `pip` and can be installed via
+makejinja is available on [PyPI](https://pypi.org/project/makejinja/) and can be installed via `pip`:
 
-`pip install makejinja`
-
-Beware that depending on other packages installed on your system via pip, there may be incompatibilities.
-Thus, we advise leveraging [`pipx`](https://github.com/pypa/pipx) instead:
-
-`pipx install makejinja`
-
-You can then directly invoke the app as follows:
-
-`makejinja -i ./input -o ./output`
+```shell
+pip install makejinja
+makejinja -i ./input -o ./output
+```
 
 ### Nix
 
 If you use the `nix` package manager, you can add this repository as an input to your flake and use `makejinja.packages.${system}.default` or apply the overlay `makejinja.overlays.default`.
-You can also run it directly
+You can also run it directly as follows:
 
-`nix run github:mirkolenz/makejinja -- -i ./input -o ./output`
+```shell
+nix run github:mirkolenz/makejinja -- -i ./input -o ./output
+```
 
 ### Docker
 
-We automatically publish an image at `ghcr.io/mirkolenz/makejinja`.
-To use it, mount a folder to the container and pass the options as the command.
+We automatically publish an image to the [GitHub Container Registry](https://ghcr.io/mirkolenz/makejinja).
+To use it, mount a directory to the container and pass the options as the command:
 
-`docker run --rm -v $(pwd)/data:/data ghcr.io/mirkolenz/makejinja:latest -i /data/input -o /data/output`
+```shell
+docker run --rm -v $(pwd)/data:/data ghcr.io/mirkolenz/makejinja:latest -i /data/input -o /data/output
+```
 
 ## Usage in Terminal / Command Line
 
-In its default configuration, makejinja searches the input folder recursively for files ending in `.jinja`.
-It then renders these files and writes them to the output folder, preserving the directory structure.
+In its default configuration, makejinja searches the input directory recursively for files ending in `.jinja`.
+It then renders these files and writes them to the output directory, preserving the directory structure.
 Our [documentation](https://mirkolenz.github.io/makejinja/makejinja/cli.html) contains a detailed description of all options and can also be accessed via `makejinja --help`.
 

makejinja-2.4.0/README.md

@@ -0,0 +1,71 @@
+<!-- markdownlint-disable MD033 MD041 -->
+<h2><p align="center">makejinja</p></h2>
+<p align="center">
+  <img width="256px" alt="makejinja logo" src="https://raw.githubusercontent.com/mirkolenz/makejinja/main/assets/logo.png" />
+</p>
+<p align="center">
+  <a href="https://pypi.org/project/makejinja/">PyPI</a> |
+  <a href="https://github.com/users/mirkolenz/packages/container/package/makejinja">Docker</a> |
+  <a href="https://mirkolenz.github.io/makejinja">Docs</a> |
+  <a href="https://github.com/mirkolenz/makejinja/tree/main/tests/data">Example</a> |
+  <a href="https://jinja.palletsprojects.com/en/3.1.x/templates">Jinja reference</a>
+</p>
+<p align="center">
+  Generate entire directory structures using Jinja templates with support for external data and custom plugins.
+</p>
+
+---
+
+# makejinja
+
+makejinja can be used to automatically generate files from [Jinja templates](https://jinja.palletsprojects.com/en/3.1.x/templates).
+It is conceptually similar to [Ansible templates](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/template_module.html) since both are built on top of Jinja.
+However, makejinja is a standalone tool that can be used without Ansible and offers some advanced features like custom plugins.
+A use case for this tool is generating config files for [Home Assistant](https://www.home-assistant.io/):
+Using the same language that the built-in templates use, you can greatly simplify your configuration.
+An [example for Home Assistant](https://github.com/mirkolenz/makejinja/tree/main/tests/data) can be found in the tests directory.
+
+## Highlights
+
+- Recursively render nested directories containing template files to a common output directory.
+- Load data files containing variables to use in your Jinja templates from YAML, TOML, and Python files.
+- Write custom [plugins](https://mirkolenz.github.io/makejinja/makejinja/plugin.html#Plugin) to extend the functionality of makejinja.
+- Adjust all Jinja options (e.g., whitespace behavior and delimiters) to your needs via CLI flags or a config file.
+
+## Installation
+
+The tool is written in Python and can be installed via pip, nix, and docker.
+It can be used as a CLI tool or as a Python library.
+
+### PIP
+
+makejinja is available on [PyPI](https://pypi.org/project/makejinja/) and can be installed via `pip`:
+
+```shell
+pip install makejinja
+makejinja -i ./input -o ./output
+```
+
+### Nix
+
+If you use the `nix` package manager, you can add this repository as an input to your flake and use `makejinja.packages.${system}.default` or apply the overlay `makejinja.overlays.default`.
+You can also run it directly as follows:
+
+```shell
+nix run github:mirkolenz/makejinja -- -i ./input -o ./output
+```
+
+### Docker
+
+We automatically publish an image to the [GitHub Container Registry](https://ghcr.io/mirkolenz/makejinja).
+To use it, mount a directory to the container and pass the options as the command:
+
+```shell
+docker run --rm -v $(pwd)/data:/data ghcr.io/mirkolenz/makejinja:latest -i /data/input -o /data/output
+```
+
+## Usage in Terminal / Command Line
+
+In its default configuration, makejinja searches the input directory recursively for files ending in `.jinja`.
+It then renders these files and writes them to the output directory, preserving the directory structure.
+Our [documentation](https://mirkolenz.github.io/makejinja/makejinja/cli.html) contains a detailed description of all options and can also be accessed via `makejinja --help`.

{makejinja-2.3.4 → makejinja-2.4.0}/makejinja/__init__.py

@@ -10,7 +10,9 @@
 While mainly intended to be used as a command line tool, makejinja can also be from Python directly.
 """
 
-from . import cli, config, loader
+from . import cli, config, plugin
 from .app import makejinja
 
-__all__ = ["makejinja", "config", "loader", "cli"]
+loader = plugin
+
+__all__ = ["makejinja", "config", "plugin", "loader", "cli"]

{makejinja-2.3.4 → makejinja-2.4.0}/makejinja/app.py

@@ -1,3 +1,4 @@
+import itertools
 import json
 import os
 import shutil
@@ -15,7 +16,7 @@ from jinja2.utils import import_string
 from rich import print
 
 from makejinja.config import Config
-from makejinja.loader import AbstractLoader, Data, MutableData
+from makejinja.plugin import Data, MutableData, PathFilter, Plugin
 
 __all__ = ["makejinja"]
 
@@ -38,48 +39,60 @@ def makejinja(config: Config):
         config.output.mkdir(exist_ok=True, parents=True)
 
     env = init_jinja_env(config, data)
+    plugins: list[Plugin] = []
 
-    for loader in config.loaders:
-        process_loader(loader, env, data)
+    for plugin_name in itertools.chain(config.plugins, config.loaders):
+        plugins.append(load_plugin(plugin_name, env, data, config))
+
+    plugin_path_filters: list[PathFilter] = []
+
+    for plugin in plugins:
+        if hasattr(plugin, "path_filters"):
+            plugin_path_filters.extend(plugin.path_filters())
 
     # Save rendered files to avoid duplicate work
-    # Even if two files are in two separate folders, they will have the same template name (i.e., relative path)
+    # Even if two files are in two separate dirs, they will have the same template name (i.e., relative path)
     # and thus only the first one will be rendered every time
     # Key: output_path, Value: input_path
     rendered_files: dict[Path, Path] = {}
 
-    # Save rendered folders to later copy metadata
+    # Save rendered dirs to later copy metadata
     # Key: output_path, Value: input_path
-    rendered_folders: dict[Path, Path] = {}
+    rendered_dirs: dict[Path, Path] = {}
 
     for user_input_path in config.inputs:
         if user_input_path.is_file():
             handle_input_file(user_input_path, config, env, rendered_files)
         elif user_input_path.is_dir():
-            handle_input_folder(
-                user_input_path, config, env, rendered_files, rendered_folders
+            handle_input_dir(
+                user_input_path,
+                config,
+                env,
+                rendered_files,
+                rendered_dirs,
+                plugin_path_filters,
             )
 
-    postprocess_rendered_folders(config, rendered_folders)
+    postprocess_rendered_dirs(config, rendered_dirs)
 
 
-def postprocess_rendered_folders(
+def postprocess_rendered_dirs(
     config: Config,
-    rendered_folders: abc.Mapping[Path, Path],
+    rendered_dirs: abc.Mapping[Path, Path],
 ) -> None:
-    # Start with the deepest folder and work our way up, otherwise the statistics could be modified after copying
+    # Start with the deepest directory and work our way up, otherwise the statistics could be modified after copying
     for output_path, input_path in sorted(
-        rendered_folders.items(), key=lambda x: x[0], reverse=True
+        rendered_dirs.items(), key=lambda x: x[0], reverse=True
     ):
         if not config.keep_empty and not any(output_path.iterdir()):
             if not config.quiet:
-                print(f"Remove empty '{output_path}'")
+                print(f"Remove empty dir '{output_path}'")
 
             shutil.rmtree(output_path)
 
         elif config.copy_metadata:
             if not config.quiet:
-                print(f"Copy metadata '{input_path}' -> '{output_path}'")
+                print(f"Copy dir metadata '{input_path}' -> '{output_path}'")
 
             shutil.copystat(input_path, output_path)
 
@@ -104,7 +117,7 @@ def handle_input_file(
     output_path = generate_output_path(config, relative_path)
 
     if output_path not in rendered_files:
-        render_path(
+        render_file(
             input_path,
             str(relative_path),
             output_path,
@@ -116,12 +129,13 @@ def handle_input_file(
     rendered_files[output_path] = input_path
 
 
-def handle_input_folder(
+def handle_input_dir(
     user_input_path: Path,
     config: Config,
     env: Environment,
     rendered_files: abc.MutableMapping[Path, Path],
-    rendered_folders: abc.MutableMapping[Path, Path],
+    rendered_dirs: abc.MutableMapping[Path, Path],
+    plugin_path_filters: abc.Sequence[abc.Callable[[Path], bool]],
 ) -> None:
     input_paths = (
         input_path
@@ -133,12 +147,18 @@ def handle_input_folder(
         relative_path = input_path.relative_to(user_input_path)
         output_path = generate_output_path(config, relative_path)
 
-        if any(input_path.match(x) for x in config.exclude_patterns):
+        exclude_pattern_match = any(
+            input_path.match(x) for x in config.exclude_patterns
+        )
+        path_filter_match = any(
+            not path_filter(input_path) for path_filter in plugin_path_filters
+        )
+        if exclude_pattern_match or path_filter_match:
             if not config.quiet:
-                print(f"Skip excluded '{input_path}'")
+                print(f"Skip excluded path '{input_path}'")
 
         elif input_path.is_file() and output_path not in rendered_files:
-            render_path(
+            render_file(
                 input_path,
                 str(relative_path),
                 output_path,
@@ -148,12 +168,9 @@ def handle_input_folder(
             )
             rendered_files[output_path] = input_path
 
-        elif input_path.is_dir() and output_path not in rendered_folders:
-            if not config.quiet:
-                print(f"Create folder '{input_path}' -> '{output_path}'")
-
-            output_path.mkdir()
-            rendered_folders[output_path] = input_path
+        elif input_path.is_dir() and output_path not in rendered_dirs:
+            render_dir(input_path, output_path, config)
+            rendered_dirs[output_path] = input_path
 
 
 def generate_output_path(config: Config, relative_path: Path) -> Path:
@@ -172,19 +189,11 @@ def init_jinja_env(
     config: Config,
     data: Data,
 ) -> Environment:
-    # If the user-provided ordering of the inputs shall be respected, use this snippet
-    # loaders: list[BaseLoader] = []
-    # for path in config.inputs:
-    #     if path.is_dir():
-    #         loaders.append(FileSystemLoader(path))
-    #     elif path.is_file():
-    #         loaders.append(DictLoader({path.name: path.read_text()}))
-
     file_loader = DictLoader(
         {path.name: path.read_text() for path in config.inputs if path.is_file()}
     )
-    folder_loader = FileSystemLoader([path for path in config.inputs if path.is_dir()])
-    loaders: list[BaseLoader] = [file_loader, folder_loader]
+    dir_loader = FileSystemLoader([path for path in config.inputs if path.is_dir()])
+    loaders: list[BaseLoader] = [file_loader, dir_loader]
 
     env = Environment(
         loader=ChoiceLoader(loaders),
@@ -302,8 +311,10 @@ def load_data(config: Config) -> dict[str, Any]:
     return data
 
 
-def process_loader(loader_name: str, env: Environment, data: Data):
-    cls: type[AbstractLoader] = import_string(loader_name)
+def load_plugin(
+    plugin_name: str, env: Environment, data: Data, config: Config
+) -> Plugin:
+    cls: type[Plugin] = import_string(plugin_name)
     sig_params = signature(cls).parameters
     params: dict[str, Any] = {}
 
@@ -313,32 +324,47 @@ def process_loader(loader_name: str, env: Environment, data: Data):
         params["environment"] = env
     if sig_params.get("data"):
         params["data"] = data
+    if sig_params.get("config"):
+        params["config"] = config
 
-    loader = cls(**params)
+    plugin = cls(**params)
 
-    if hasattr(loader, "globals"):
-        env.globals.update({func.__name__: func for func in loader.globals()})
+    if hasattr(plugin, "globals"):
+        env.globals.update({func.__name__: func for func in plugin.globals()})
 
-    if hasattr(loader, "functions"):
-        env.globals.update({func.__name__: func for func in loader.functions()})
+    if hasattr(plugin, "functions"):
+        env.globals.update({func.__name__: func for func in plugin.functions()})
 
-    if hasattr(loader, "data"):
-        env.globals.update(loader.data())
+    if hasattr(plugin, "data"):
+        env.globals.update(plugin.data())
 
-    if hasattr(loader, "extensions"):
-        load_extensions(env, loader.extensions())
+    if hasattr(plugin, "extensions"):
+        load_extensions(env, plugin.extensions())
 
-    if hasattr(loader, "filters"):
-        env.filters.update({func.__name__: func for func in loader.filters()})
+    if hasattr(plugin, "filters"):
+        env.filters.update({func.__name__: func for func in plugin.filters()})
 
-    if hasattr(loader, "tests"):
-        env.tests.update({func.__name__: func for func in loader.tests()})
+    if hasattr(plugin, "tests"):
+        env.tests.update({func.__name__: func for func in plugin.tests()})
+
+    if hasattr(plugin, "policies"):
+        env.policies.update(plugin.policies())
+
+    return plugin
+
+
+def render_dir(input: Path, output: Path, config: Config) -> None:
+    if output.exists() and not config.force:
+        if not config.quiet:
+            print(f"Skip existing dir '{output}'")
+    else:
+        if not config.quiet:
+            print(f"Create dir '{input}' -> '{output}'")
 
-    if hasattr(loader, "policies"):
-        env.policies.update(loader.policies())
+        output.mkdir(exist_ok=True)
 
 
-def render_path(
+def render_file(
     input: Path,
     template_name: str,
     output: Path,
@@ -348,7 +374,7 @@ def render_path(
 ) -> None:
     if output.exists() and not config.force:
         if not config.quiet:
-            print(f"Skip existing '{output}'")
+            print(f"Skip existing file '{output}'")
 
     elif input.suffix == config.jinja_suffix or not enforce_jinja_suffix:
         template = env.get_template(template_name)
@@ -358,7 +384,7 @@ def render_path(
         # Prevents empty macro definitions
         if rendered.strip() == "" and not config.keep_empty:
             if not config.quiet:
-                print(f"Skip empty '{input}'")
+                print(f"Skip empty file '{input}'")
         else:
             if not config.quiet:
                 print(f"Render file '{input}' -> '{output}'")

{makejinja-2.3.4 → makejinja-2.4.0}/makejinja/config.py

@@ -18,7 +18,6 @@ from jinja2.defaults import (
     BLOCK_START_STRING,
     COMMENT_END_STRING,
     COMMENT_START_STRING,
-    KEEP_TRAILING_NEWLINE,
     LINE_COMMENT_PREFIX,
     LINE_STATEMENT_PREFIX,
     NEWLINE_SEQUENCE,
@@ -31,6 +30,8 @@ frozendict = immutables.Map
 
 
 class Undefined(Enum):
+    """How to handle undefined variables."""
+
     default = DefaultUndefined
     chainable = ChainableUndefined
     debug = DebugUndefined
@@ -153,8 +154,8 @@ class Whitespace:
         """,
     )
     keep_trailing_newline: bool = ts.option(
-        default=KEEP_TRAILING_NEWLINE,
-        click={"param_decls": "--keep-trailing-newline"},
+        default=True,
+        click={"param_decls": "--keep-trailing-newline/--strip-trailing-newline"},
         help="""
             Preserve the trailing newline when rendering templates.
             The default is `False`, which causes a single newline, if present, to be stripped from the end of the template.
@@ -170,7 +171,7 @@ class Config:
             "param_decls": ("--input", "-i"),
         },
         help="""
-            Path to a folder containing template files or a single template file.
+            Path to a directory containing template files or a single template file.
             It is passed to Jinja's [FileSystemLoader](https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.FileSystemLoader) when creating the environment.
             **Note:** This option may be passed multiple times to pass a list of values.
             If a template exists in multiple inputs, the last value with be used.
@@ -182,7 +183,7 @@ class Config:
             "param_decls": ("--output", "-o"),
         },
         help="""
-            Path to a folder where the rendered templates are stored.
+            Path to a directory where the rendered templates are stored.
             makejinja preserves the relative paths in the process, meaning that you can even use it on nested directories.
         """,
     )
@@ -192,7 +193,7 @@ class Config:
         help="""
             Glob patterns to search for files in `inputs`.
             Accepts all pattern supported by [`fnmatch`](https://docs.python.org/3/library/fnmatch.html#module-fnmatch).
-            If a file is matched by this pattern and does not end with the specified `jinja-suffix`, it is copied over to the `output_folder`.
+            If a file is matched by this pattern and does not end with the specified `jinja-suffix`, it is copied over to `output`.
             Multiple can be provided.
             **Note:** Do not add a special suffix used by your template files here, instead use the `jinja-suffix` option.
         """,
@@ -219,7 +220,7 @@ class Config:
         default=False,
         click={"param_decls": "--keep-jinja-suffix"},
         help="""
-            Decide whether the specified `jinja-suffix` is removed from the file after rendering.
+            Decide whether the specified `jinja-suffix` is removed from the file name after rendering.
         """,
     )
     keep_empty: bool = ts.option(
@@ -247,7 +248,7 @@ class Config:
         help="""
                 Load variables from yaml/yml/toml/json files for use in your Jinja templates.
                 The definitions are passed to Jinja as globals.
-                Can either be a file or a folder containing files.
+                Can either be a file or a directory containing files.
                 **Note:** This option may be passed multiple times to pass a list of values.
                 If multiple files are supplied, beware that previous declarations will be overwritten by newer ones.
             """,
@@ -269,6 +270,14 @@ class Config:
         default=tuple(),
         click={
             "param_decls": ("--loader", "-l"),
+            "hidden": True,
+        },
+        help="Deprecated, use `--plugin` instead.",
+    )
+    plugins: tuple[str, ...] = ts.option(
+        default=tuple(),
+        click={
+            "param_decls": ("--plugin", "-p"),
         },
         help="""
             Use custom Python code to adjust the used Jinja environment to your needs.
@@ -277,8 +286,8 @@ class Config:
             In addition, you may add an `__init__` function that receives two positional arguments:
             the created Jinja environment and the data parsed from the files supplied to makejinja's `data` option.
             This allows you to apply arbitrary logic to makejinja.
-            An import path can be specified either in dotted notation (`your.custom.Loader`)
-            or with a colon as object delimiter (`your.custom:Loader`).
+            An import path can be specified either in dotted notation (`your.custom.Plugin`)
+            or with a colon as object delimiter (`your.custom:Plugin`).
             **Note:** This option may be passed multiple times to pass a list of values.
         """,
     )
@@ -290,7 +299,7 @@ class Config:
             "show_default": "current working directory",
         },
         help="""
-            In order to load custom loaders or Jinja extensions, the PYTHONPATH variable needs to be patched.
+            In order to load plugins or Jinja extensions, the PYTHONPATH variable needs to be patched.
             The default value works for most use cases, but you may load other paths as well.
         """,
     )
@@ -317,14 +326,14 @@ class Config:
         default=False,
         click={"param_decls": ("--clean", "-c")},
         help="""
-            Whether to remove the output folder if it exists.
+            Whether to remove the output directory if it exists.
         """,
     )
     force: bool = ts.option(
         default=False,
         click={"param_decls": ("--force", "-f")},
         help="""
-            Whether to overwrite existing files in the output folder.
+            Whether to overwrite existing files in the output directory.
         """,
     )
     quiet: bool = ts.option(
@@ -360,7 +369,7 @@ OPTION_GROUPS = {
             "options": [
                 "--data",
                 "--data-var",
-                "--loader",
+                "--plugin",
                 "--import-path",
                 "--extension",
                 "--undefined",

makejinja-2.3.4/makejinja/loader.py → makejinja-2.4.0/makejinja/plugin.py

@@ -1,24 +1,13 @@
 from collections import abc
-from typing import Any
+from pathlib import Path
+from typing import Any, Protocol
 
 from jinja2 import Environment
 from jinja2.ext import Extension
 
-__all__ = (
-    "AbstractLoader",
-    "Environment",
-    "Extension",
-    "Extensions",
-    "Filter",
-    "Filters",
-    "Function",
-    "Functions",
-    "Test",
-    "Tests",
-    "Policies",
-    "MutableData",
-    "Data",
-)
+from makejinja.config import Config
+
+__all__ = ["Plugin"]
 
 Extensions = abc.Sequence[type[Extension]]
 Filter = abc.Callable[[Any], Any]
@@ -30,10 +19,14 @@ Tests = abc.Sequence[Test]
 Policies = abc.Mapping[str, Any]
 MutableData = abc.MutableMapping[str, Any]
 Data = abc.Mapping[str, Any]
+PathFilter = abc.Callable[[Path], bool]
+PathFilters = abc.Sequence[PathFilter]
+
 
+class Plugin(Protocol):
+    """Extend the functionality of makejinja with a plugin implementing a subset of this protocol."""
 
-class AbstractLoader:
-    def __init__(self, *, env: Environment, data: Data) -> None:
+    def __init__(self, *, env: Environment, data: Data, config: Config) -> None:
         pass
 
     def functions(self) -> Functions:
@@ -54,6 +47,12 @@ class AbstractLoader:
     def extensions(self) -> Extensions:
         return []
 
+    def path_filters(self) -> PathFilters:
+        return []
+
     # Deprecated: Use functions() and data() instead
     def globals(self) -> Functions:
         return []
+
+
+AbstractLoader = Plugin

{makejinja-2.3.4 → makejinja-2.4.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "makejinja"
-version = "2.3.4"
-description = "makejinja is a CLI tool and Python library to automatically generate files from Jinja2 templates. Use it to easily generate complex Home Assistant dashboards!"
+version = "2.4.0"
+description = "Generate entire directory structures using Jinja templates with support for external data and custom plugins."
 authors = ["Mirko Lenz <mirko@mirkolenz.com>"]
 license = "MIT"
 readme = "README.md"
@@ -49,7 +49,11 @@ python = "^3.11"
 jinja2 = "^3.1"
 pyyaml = "^6.0"
 rich-click = "^1.7"
-typed-settings = { version = "^23.1", extras = ["attrs", "cattrs", "click"] }
+typed-settings = { version = ">=23.1, <25", extras = [
+    "attrs",
+    "cattrs",
+    "click",
+] }
 immutables = "^0.20"
 
 [tool.poetry.group.dev.dependencies]

makejinja-2.3.4/README.md

@@ -1,76 +0,0 @@
-<!-- markdownlint-disable MD033 MD041 -->
-<p align="center">
-  <img width="256px" alt="makejinja logo" src="https://raw.githubusercontent.com/mirkolenz/makejinja/main/assets/logo.png" />
-</p>
-<p align="center">
-  <a href="https://pypi.org/project/makejinja/">PyPI</a> |
-  <a href="https://mirkolenz.github.io/makejinja">Docs</a> |
-  <a href="https://github.com/mirkolenz/makejinja/tree/main/tests/data">Example</a> |
-  <a href="https://jinja.palletsprojects.com/en/3.1.x/templates">Templating</a>
-</p>
-<p align="center">
-  makejinja is a CLI tool and Python library to automatically generate files from Jinja2 templates.
-  Use it to easily generate complex Home Assistant dashboards!
-</p>
-
----
-
-# makejinja
-
-makejinja can be used to automatically generate files from [Jinja templates](https://jinja.palletsprojects.com/en/3.1.x/templates).
-This allows you to load variables from external files or create repeating patterns via loops.
-It is conceptually similar to [gomplate](https://github.com/hairyhenderson/gomplate), but is built on Python and Jinja instead of Go.
-A use case for this tool is generating config files for [Home Assistant](https://www.home-assistant.io/):
-Using the same language that the built-in templates use, you can greatly simplify your configuration.
-An [example for Home Assistant](https://github.com/mirkolenz/makejinja/tree/main/tests/data) can be found in the tests directory.
-
-## Features
-
-- Recursively convert nested directories containing template files. One can even specify a pattern to specify relevant files in a folder.
-- Load data files containing variables to use in your Jinja templates from YAML, TOML, and Python files.
-- Use custom functions in your Jinja templates by loading custom filters and/or globals.
-- Easily load bundled as well as custom Jinja extensions.
-- Tailor the whitespace behavior to your needs.
-- Use custom delimiters for Jinja blocks/comments/variables.
-- Modify _all_ init options for the Jinja environment.
-- Write custom **Python loaders** that implement a subset of our fully typed [abstract loader class](https://mirkolenz.github.io/makejinja/makejinja/loader.html#AbstractLoader)
-
-## Installation
-
-The tool is written in Python and can be installed via pip, nix, and docker.
-It can be used as a CLI tool or as a Python library.
-
-### PIP
-
-makejinja is available via `pip` and can be installed via
-
-`pip install makejinja`
-
-Beware that depending on other packages installed on your system via pip, there may be incompatibilities.
-Thus, we advise leveraging [`pipx`](https://github.com/pypa/pipx) instead:
-
-`pipx install makejinja`
-
-You can then directly invoke the app as follows:
-
-`makejinja -i ./input -o ./output`
-
-### Nix
-
-If you use the `nix` package manager, you can add this repository as an input to your flake and use `makejinja.packages.${system}.default` or apply the overlay `makejinja.overlays.default`.
-You can also run it directly
-
-`nix run github:mirkolenz/makejinja -- -i ./input -o ./output`
-
-### Docker
-
-We automatically publish an image at `ghcr.io/mirkolenz/makejinja`.
-To use it, mount a folder to the container and pass the options as the command.
-
-`docker run --rm -v $(pwd)/data:/data ghcr.io/mirkolenz/makejinja:latest -i /data/input -o /data/output`
-
-## Usage in Terminal / Command Line
-
-In its default configuration, makejinja searches the input folder recursively for files ending in `.jinja`.
-It then renders these files and writes them to the output folder, preserving the directory structure.
-Our [documentation](https://mirkolenz.github.io/makejinja/makejinja/cli.html) contains a detailed description of all options and can also be accessed via `makejinja --help`.