jinja2-render – A CLI tool to render Jinja2 templates
Project description
jinja2-render
A Python Tool to Render Jinja2 Templates on the Command Line with Different Contexts
jinja2-render hugely simplifies creating different versions of a text file. It takes a jinja2 Template file as input and renders it to a final document using a context loaded from a Python script. It was invented for use with Dockerfiles but its use case goes far beyond.
This is useful for example in the following cases:
- The desired document (eg. Dockerfile) contains a lot of repeated statements. In a Jinja2 Template they can be replaced by a [For Loop][].
- The configuration space for the desired document is large and the differences would be small, so maintaining a single template file is much easier.
Workflow
jinja2-render
(& contexts.py)
↓
Jinja2 Template File Rendered File
(eg. Dockerfile.jinja2) 🡆 (eg. Dockerfile)
Synopsis
$ jinja2-render -h
usage: jinja2-render [-h] [-c CONTEXTS] [-f TEMPLATE]
[-o OUTPUT]
[which]
Render a Jinja2 template from the command line.
positional arguments:
which Context to choose. Omit for a list of contexts
available in the contexts file (-c).
(default: None)
optional arguments:
-h, --help show this help message and exit
-c CONTEXTS The Python file defining the contexts to
render the template. (default: ./contexts.py)
-f TEMPLATE The Jinja2 template to use. (default:
Dockerfile.jinja2)
-o OUTPUT The output file to write to. (default:
Dockerfile)
Minimal Example
Content of Dockerfile.jinja2
:
FROM {{ base_img }}
RUN apt-get update \
&& apt-get install -yq {{ packages | join(' ') }}
RUN echo "Done!"
Content of contexts.py
:
CONTEXTS = {
"v1.0": {
"base_img": "debian:10-slim",
"packages": ["glibc-devel", "turboshutdown"],
}
}
Call to jinja2-render
:
jinja2-render v1.0
Resulting in the following rendered Dockerfile:
FROM debian:10-slim
RUN apt-get update \
&& apt-get install -yq glibc-devel turboshutdown
RUN echo "Done!"
The Contexts File
The contexts file (defaults to ./contexts.py
) contains
one ore multiple context definitions to render the template.
This includes variables to be substituted, lists to render for loops, etc.
- The contexts file must contain a global
CONTEXTS = {}
with keys corresponding to different contexts that can be selected. (Pro Tip™: Instead of a dictionary, this CONTEXTS object could also be a class that derives from dict.) - The items in
CONTEXTS
are the actual context handed over to jinja2.Template.render(). Usually this would also be a dictionary.
Original Use Case
The script was originally developed to automate building different configurations of the control system software EPICS and it's various modules. Traditionally, those modules were installed by a single shell script with fixed versions (i.e. synApps), which is bad in the Docker world as a build failure at the end if it would require rebuilding everything before.
How it compares to other templating tools
By using a Python file to provide the context for the template, much more flexibility is possible than with a simple solution such as jinja2-cli or j2cli. They allow to use files such as YAML, INI or JSON as input for variables.
A Python script can - however - in addition to defining static information
ease additional tasks tasks such as dependency management.
As an elaborate example of such a use case, have a look at
this,
where I use a custom class in the contexts.py
along with additional code
to validate the resulting context.
Authors
- Philipp Klaus, University Frankfurt
initial author - Florian Feldbauer, University Bochum
further improvements
Project details
Release history Release notifications | RSS feed
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
Hashes for jinja2_render-1.3-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e3ce033fc7ea73be3f86ec185aec6a921c236454be2739d313342aadadac1bcd |
|
MD5 | 23c461081bce3c14ad7fbbf52ffbd16f |
|
BLAKE2b-256 | ddf088012dd34d8878d7318b2b2eca0a7bcddd8e500edbb16211621cf612a5fb |