Skip to main content

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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jinja2-render-1.3.tar.gz (4.6 kB view details)

Uploaded Source

Built Distribution

jinja2_render-1.3-py2.py3-none-any.whl (5.6 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file jinja2-render-1.3.tar.gz.

File metadata

  • Download URL: jinja2-render-1.3.tar.gz
  • Upload date:
  • Size: 4.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.1 importlib_metadata/3.10.0 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.60.0 CPython/3.9.5

File hashes

Hashes for jinja2-render-1.3.tar.gz
Algorithm Hash digest
SHA256 1ca191587d024aefb70129e5d93f073f3db198809662059d30ce90601caea357
MD5 01bf528f27c6039e1ac9655dadc6540e
BLAKE2b-256 0279a35e65816ee566bd4197cdaa21bba2cc596afa5627d08d5b0c7e26ec7e3b

See more details on using hashes here.

File details

Details for the file jinja2_render-1.3-py2.py3-none-any.whl.

File metadata

  • Download URL: jinja2_render-1.3-py2.py3-none-any.whl
  • Upload date:
  • Size: 5.6 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.1 importlib_metadata/3.10.0 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.60.0 CPython/3.9.5

File hashes

Hashes for jinja2_render-1.3-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 e3ce033fc7ea73be3f86ec185aec6a921c236454be2739d313342aadadac1bcd
MD5 23c461081bce3c14ad7fbbf52ffbd16f
BLAKE2b-256 ddf088012dd34d8878d7318b2b2eca0a7bcddd8e500edbb16211621cf612a5fb

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page