Metadata-Version: 2.1
Name: makejinja
Version: 1.0.0b3
Summary: Automatically generate files based on Jinja templates. Use it to easily generate complex Home Assistant dashboards!
Home-page: https://github.com/mirkolenz/makejinja
License: MIT
Author: Mirko Lenz
Author-email: mirko@mirkolenz.com
Requires-Python: >=3.9,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: dtyper (>=2.0.3,<3.0.0)
Requires-Dist: jinja2 (>=3.1.2,<4.0.0)
Requires-Dist: pyyaml (>=6.0,<7.0)
Requires-Dist: rich (>=13.0.0,<14.0.0)
Requires-Dist: typer (>=0.7.0,<0.8.0)
Project-URL: Repository, https://github.com/mirkolenz/makejinja
Description-Content-Type: text/markdown

# makejinja

**Note:** Development happens in the [beta branch](https://github.com/mirkolenz/makejinja/tree/beta).

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.

A concrete example for Home Assistant can be found in the [test directory](./tests/data)

## Installation

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`

Alternatively, the application can also be used via Docker.
We automatically publish an image at `ghcr.io/mirkolenz/makejinja`.
To use it, mount a folder to the container and pass the command options via the environment variable `cmd`.
For example, to process files in `./data/input` and render them to `./data/output` while using the extension `jinja2.ext.do`, you could run:

`docker run --rm -it -v $(pwd)/data:/data -e args="/data/input /data/output --extension jinja2.ext.do" ghcr.io/mirkolenz/makejinja@latest`

## Usage

In its default configuration, makejinja searches the input folder recursively for files ending in `.jinja`.
Also, we copy all contents (except raw template files) of the input folder to the output folder and remove the `.jinja` ending during the render process.
To get an overview of the remaining options, we advise you to run `makejinja --help`:

<!-- echo -e "\n```txt\n$(COLUMNS=120 poetry run makejinja --help)\n```" >> README.md -->

```txt

 Usage: makejinja [OPTIONS] INPUT_FOLDER OUTPUT_FOLDER

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    input_folder       DIRECTORY  Path to a folder containing template files. It is passed to Jinja's               │
│                                    FileSystemLoader when creating the environment.                                   │
│                                    [default: None]                                                                   │
│                                    [required]                                                                        │
│ *    output_folder      DIRECTORY  Path to a folder where the rendered templates are stored. makejinja preserves the │
│                                    relative paths in the process, meaning that you can even use it on nested         │
│                                    directories.                                                                      │
│                                    [default: None]                                                                   │
│                                    [required]                                                                        │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Input File Handling ────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --pattern             TEXT  Glob pattern to search for files in input_folder. Accepts all pattern supported by       │
│                             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. Note: Do not add a special suffix  │
│                             used by your template files here, instead use the jinja-suffix option.                   │
│                             [default: **/*]                                                                          │
│ --jinja-suffix        TEXT  File ending of Jinja template files. All files with this suffix in input_folder matched  │
│                             by pattern are passed to the Jinja renderer. Note: Should be provided with the leading   │
│                             dot.                                                                                     │
│                             [default: .jinja]                                                                        │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Jinja Environment Options ──────────────────────────────────────────────────────────────────────────────────────────╮
│ --data             PATH  Load variables from yaml/yaml files for use in your Jinja templates. The defintions are     │
│                          passed to Jinja's render function. Can either be a file or a folder containg 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.              │
│ --globals          PATH  You can import functions/varibales defined in .py files to use them in your Jinja           │
│                          templates. Can either be a file or a folder containg files. Note: This option may be passed │
│                          multiple times to pass a list of files/folders. If multiple files are supplied, beware that │
│                          previous declarations will be overwritten by newer ones.                                    │
│ --filters          PATH  Jinja has support for filters (e.g., [1, 2, 3] | length) to easily call functions. This     │
│                          option allows you to define custom filters in .py files. Can either be a file or a folder   │
│                          containg files. Note: This option may be passed multiple times to pass a list of            │
│                          files/folders. If multiple files are supplied, beware that previous declarations will be    │
│                          overwritten by newer ones.                                                                  │
│ --extension        TEXT  Extend Jinja's parser by loading the specified extensions. An overview of the built-in ones │
│                          can be found on the project website. Currently, only those built-in filters are allowed.    │
│                          Note: This option may be passed multiple times to pass a list of values.                    │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Jinja Whitespace Control ───────────────────────────────────────────────────────────────────────────────────────────╮
│ --lstrip-blocks            --no-lstrip-blocks              The lstrip_blocks option can also be set to strip tabs    │
│                                                            and spaces from the beginning of a line to the start of a │
│                                                            block. (Nothing will be stripped if there are other       │
│                                                            characters before the start of the block.) Refer to the   │
│                                                            Jinja docs for more details.                              │
│                                                            [default: lstrip-blocks]                                  │
│ --trim-blocks              --no-trim-blocks                If an application configures Jinja to trim_blocks, the    │
│                                                            first newline after a template tag is removed             │
│                                                            automatically (like in PHP). Refer to the Jinja docs for  │
│                                                            more details.                                             │
│                                                            [default: trim-blocks]                                    │
│ --keep-trailing-newline    --no-keep-trailing-newline      By default, Jinja also removes trailing newlines. To keep │
│                                                            single trailing newlines, configure Jinja to              │
│                                                            keep_trailing_newline. Refer to the Jinja docs for more   │
│                                                            details.                                                  │
│                                                            [default: no-keep-trailing-newline]                       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Jinja Delimiters ───────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --block-start-string           TEXT  [default: {%]                                                                   │
│ --block-end-string             TEXT  [default: %}]                                                                   │
│ --comment-start-string         TEXT  [default: {#]                                                                   │
│ --comment-end-string           TEXT  [default: #}]                                                                   │
│ --variable-start-string        TEXT  [default: {{]                                                                   │
│ --variable-end-string          TEXT  [default: }}]                                                                   │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output File Handling ───────────────────────────────────────────────────────────────────────────────────────────────╮
│ --copy-tree              --no-copy-tree                If your input_folder containes additional files besides Jinja │
│                                                        templates, you may want to copy them to output_folder as      │
│                                                        well. This operation maintains the metadata of all files and  │
│                                                        folders, meaning that tools like rsync will treat them        │
│                                                        exactly like the original ones. Note: Even if set to          │
│                                                        no-copy-tree, files that are matched by your provided pattern │
│                                                        within input_folder are still copied over. In both cases, a   │
│                                                        file's metadata is untouched. The main difference is that     │
│                                                        with copy-tree, folders keep their metadata while matched     │
│                                                        files are copied to newly-created subfolders that differ in   │
│                                                        their metadata.                                               │
│                                                        [default: copy-tree]                                          │
│ --remove-jinja-suffix    --no-remove-jinja-suffix      Decide whether the specified jinja-suffix is removed from the │
│                                                        file after rendering.                                         │
│                                                        [default: remove-jinja-suffix]                                │
│ --skip-empty             --no-skip-empty               Some Jinja template files may be empty after rendering (e.g., │
│                                                        if they only contain macros that are imported by other        │
│                                                        templates). By default, we do not copy such empty files. If   │
│                                                        there is a need to have them available anyway, you can adjust │
│                                                        that.                                                         │
│                                                        [default: skip-empty]                                         │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

