makejinja 2.3.5__tar.gz → 2.4.0__tar.gz

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: makejinja
-Version: 2.3.5
-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 directory.
+- 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,32 +79,30 @@ 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 directory 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
 

{makejinja-2.3.5 → makejinja-2.4.0}/README.md

@@ -1,16 +1,17 @@
 <!-- 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>
 
 ---
@@ -18,22 +19,18 @@
 # 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 directory.
+- 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
 
@@ -42,32 +39,30 @@ 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 directory 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
 

{makejinja-2.3.5 → 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.5 → 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,9 +39,16 @@ 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 dirs, they will have the same template name (i.e., relative path)
@@ -57,7 +65,12 @@ def makejinja(config: Config):
             handle_input_file(user_input_path, config, env, rendered_files)
         elif user_input_path.is_dir():
             handle_input_dir(
-                user_input_path, config, env, rendered_files, rendered_dirs
+                user_input_path,
+                config,
+                env,
+                rendered_files,
+                rendered_dirs,
+                plugin_path_filters,
             )
 
     postprocess_rendered_dirs(config, rendered_dirs)
@@ -122,6 +135,7 @@ def handle_input_dir(
     env: Environment,
     rendered_files: 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,7 +147,13 @@ def handle_input_dir(
         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 path '{input_path}'")
 
@@ -169,14 +189,6 @@ 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()}
     )
@@ -299,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] = {}
 
@@ -310,29 +324,33 @@ 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
+
+    plugin = cls(**params)
 
-    loader = cls(**params)
+    if hasattr(plugin, "globals"):
+        env.globals.update({func.__name__: func for func in plugin.globals()})
 
-    if hasattr(loader, "globals"):
-        env.globals.update({func.__name__: func for func in loader.globals()})
+    if hasattr(plugin, "functions"):
+        env.globals.update({func.__name__: func for func in plugin.functions()})
 
-    if hasattr(loader, "functions"):
-        env.globals.update({func.__name__: func for func in loader.functions()})
+    if hasattr(plugin, "data"):
+        env.globals.update(plugin.data())
 
-    if hasattr(loader, "data"):
-        env.globals.update(loader.data())
+    if hasattr(plugin, "extensions"):
+        load_extensions(env, plugin.extensions())
 
-    if hasattr(loader, "extensions"):
-        load_extensions(env, loader.extensions())
+    if hasattr(plugin, "filters"):
+        env.filters.update({func.__name__: func for func in plugin.filters()})
 
-    if hasattr(loader, "filters"):
-        env.filters.update({func.__name__: func for func in loader.filters()})
+    if hasattr(plugin, "tests"):
+        env.tests.update({func.__name__: func for func in plugin.tests()})
 
-    if hasattr(loader, "tests"):
-        env.tests.update({func.__name__: func for func in loader.tests()})
+    if hasattr(plugin, "policies"):
+        env.policies.update(plugin.policies())
 
-    if hasattr(loader, "policies"):
-        env.policies.update(loader.policies())
+    return plugin
 
 
 def render_dir(input: Path, output: Path, config: Config) -> None:

{makejinja-2.3.5 → 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.
@@ -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(
@@ -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.
         """,
     )
@@ -360,7 +369,7 @@ OPTION_GROUPS = {
             "options": [
                 "--data",
                 "--data-var",
-                "--loader",
+                "--plugin",
                 "--import-path",
                 "--extension",
                 "--undefined",

makejinja-2.3.5/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.5 → makejinja-2.4.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "makejinja"
-version = "2.3.5"
-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]