jinja-tree
What is it?
jinja-tree is a CLI utility to process jinja (jinja2) templates
recursively in a directory tree.
It is very configurable and very easy to extend with its included plugin system.
The default behavior is to recursively search for files with a given extension (.template for example) and to process the context with Jinja (Jinja2) templates engine reading the context variables from:
- a configuration file
- environment variables
- dotenv files
Then, the processed content is written into another file with the same name/path but with the configured extension (.template by default) removed. The original file can also be deleted (but this is not the default behavior).
Full example about overall operation (in default mode)
Note: this is only the default behavior as you can tune this with your own plugins!
Let's imagine the following directory structure:
/foo/
/foo/README.md.template
/foo/bar/baz.py.template
/foo/bar/another.file
And execute jinja-tree /foo with the default configuration.
We get:
/foo/
/foo/README.md.template
/foo/README.md <= NEW FILE FROM README.md.template jinja2 processing
/foo/bar/baz.py.template
/foo/bar/baz.py <= NEW FILE FROM baz.py.template jinja2 processing
/foo/bar/another.file
What's it for?
Your imagination is your limit ๐
but it's very useful for maintaining DRY documentation (for example your-cli --help output automatically updated in a markdown file), configuration files with default values read in code, including common blocks in different files...
So it's a great tool for maintaining repositories in general.
[!TIP] Do you cant real-life examples? You can find some details about how we use it in this repository for:
[!NOTE] Another "action" plugin will be soon ๐ provided to bootstrap directory trees from templates (like with the cookiecutter project).
Features
1๏ธโฃ Easy to extend
jinja-tree includes a plugin system. You can override the default behavior with your own plugins.
There are two extension points:
- context plugins: to provide context variables to Jinja templates
- file plugins: to change the way how
jinja-treefinds files to process (including target files)
See this specification documentation page for more details.
2๏ธโฃ Very configurable
jinja-tree is very configurable. You can configure global options via CLI options or a configuration file.
Plugins are configurable via the configuration file.
See this specification documentation page for more details.
3๏ธโฃ Embedded extensions
jinja-tree includes some extensions to Jinja templates engine:
- to execute some commands (and get the corresponding output)
- to parse JSON strings into Python objects)
- ..
Usage examples
shell extension
{{ "date"|shell() }}
=> will render something like: Sun Jan 28 15:11:44 CET 2024
from_json extension
export MYENV='["foo", "bar", "baz"]'
(
cat <<EOF
{% for item in MYENV|from_json() -%}
- {{ item }}
{% endfor %}
EOF
) | jinja-stdin
=> will render something like:
- foo
- bar
- bar
See this directory for others
4๏ธโฃ Full Jinja / Jinja2 support (including "includes" and "inheritance")
jinja-tree has several options for Jinja "search paths". So you can use Jinja "includes" and "inheritance" features.
Installation
pip install jinja-tree
[!TIP] If you want to get a better readability of
jinja-treeoutput (colors...), you can also usepip install richto install this optional dependency.
Usage
Main CLI
jinja-tree .
[!NOTE] The
.in the previous command in the "root directory" (the directoryjinja-treewill explore recursively to find files to process). You can replace it with any directory you want. By using., you will process all files in the current directory and its subdirectories.
Main CLI options
Usage: jinja-tree [OPTIONS] ROOT_DIR
Process a directory tree with the Jinja / Jinja2 templating system.
โญโ Arguments โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ * root_dir PATH root directory [required] โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
โญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ --config-file TEXT config file path (default: first โ
โ '.jinja-tree.toml' file found up โ
โ from current working dir), can โ
โ also be see with โ
โ JINJA_TREE_CONFIG_FILE env var โ
โ [env var: JINJA_TREE_CONFIG_FILE] โ
โ --log-level TEXT log level (DEBUG, INFO, WARNING or โ
โ ERROR) โ
โ [default: INFO] โ
โ --verbose --no-verbose increase verbosity of the DEBUG โ
โ log level (note: this forces โ
โ log-level = DEBUG) โ
โ [default: no-verbose] โ
โ --extra-search-path PATH Search path to jinja (can be used โ
โ multiple times) โ
โ --add-cwd-to-search-path --no-add-cwd-to-search-path add current working directory โ
โ (CWD) to jinja search path โ
โ --add-root-dir-to-search-path --no-add-root-dir-to-search-path add root directory to jinja search โ
โ path โ
โ --jinja-extension TEXT jinja extension to load โ
โ --context-plugin TEXT context plugins (full python class โ
โ path, can be used multiple times) โ
โ --action-plugin TEXT action plugin (full python class โ
โ path, can be used multiple times) โ
โ --strict-undefined --no-strict-undefined if set, raise an error if a โ
โ variable does not exist in context โ
โ --blank-run --no-blank-run if set, execute a blank run โ
โ (without modifying or deleting โ
โ anything) โ
โ [default: no-blank-run] โ
โ --disable-embedded-jinja-extensioโฆ --no-disable-embedded-jinja-extenโฆ disable embedded jinja extensions โ
โ --help Show this message and exit. โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
Bonus CLI (if you want to process only one file but with the same behavior)
cat /path/to/your/file/to/process | jinja-stdin >/path/to/your/processed/file
or (if you want to process only a string):
$ export FOO=bar
$ echo "Hello {{FOO}}" | jinja-stdin
Hello bar
Bonus CLI options
Usage: jinja-stdin [OPTIONS]
Process the standard input with Jinja templating system and return the result on the standard output.
โญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ --config-file TEXT config file path (default: first โ
โ '.jinja-tree.toml' file found up โ
โ from current working dir), can โ
โ also be see with โ
โ JINJA_TREE_CONFIG_FILE env var โ
โ [env var: JINJA_TREE_CONFIG_FILE] โ
โ --log-level TEXT log level (DEBUG, INFO, WARNING or โ
โ ERROR) โ
โ [default: INFO] โ
โ --verbose --no-verbose increase verbosity of the DEBUG โ
โ log level (note: this forces โ
โ log-level = DEBUG) โ
โ [default: no-verbose] โ
โ --extra-search-path PATH Search path to jinja (can be used โ
โ multiple times) โ
โ --add-cwd-to-search-path --no-add-cwd-to-search-path add current working directory โ
โ (CWD) to jinja search path โ
โ --jinja-extension TEXT jinja extension to load โ
โ --context-plugin TEXT context plugins (full python class โ
โ path, can be used multiple times) โ
โ --strict-undefined --no-strict-undefined if set, raise an error if a โ
โ variable does not exist in context โ
โ --disable-embedded-jinja-extensioโฆ --no-disable-embedded-jinja-extenโฆ disable embedded jinja extensions โ
โ --help Show this message and exit. โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file jinja_tree-0.9.0.tar.gz.
File metadata
- Download URL: jinja_tree-0.9.0.tar.gz
- Upload date:
- Size: 17.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
06db15debae622133d8aaba268fc01f0e2fd2e6af6b7a1162031fbe70959068b
|
|
| MD5 |
75af418e7d0217daa13f2130c75744b3
|
|
| BLAKE2b-256 |
184f0d8edaf48c9fc71616e53f12297ac4415896b56383ec53b28fcc044f2118
|
File details
Details for the file jinja_tree-0.9.0-py3-none-any.whl.
File metadata
- Download URL: jinja_tree-0.9.0-py3-none-any.whl
- Upload date:
- Size: 25.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
d16f4193a960b33bfaa654b3495f6683dd778195ec324e1a0e8039b330c9f94c
|
|
| MD5 |
abeebfb91835531b1769f454a6d8e195
|
|
| BLAKE2b-256 |
230b0c3f9402dcde0ff95e4cafab6043abbcd79e34fa9838d4a03d00f2b05e98
|
