Metadata-Version: 2.1
Name: jinja2-render
Version: 1.3
Summary: jinja2-render – A CLI tool to render Jinja2 templates
Home-page: https://github.com/pklaus/jinja2-render
Author: Philipp Klaus
Author-email: philipp.l.klaus@web.de
License: GPL
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`:
        
        ```Dockerfile
        FROM {{ base_img }}
        
        RUN apt-get update \
         && apt-get install -yq {{ packages | join(' ') }}
        
        RUN echo "Done!"
        
        ```
        
        Content of `contexts.py`:
        
        ```python
        CONTEXTS = {
            "v1.0": {
                "base_img": "debian:10-slim",
                "packages": ["glibc-devel", "turboshutdown"],
            }
        }
        
        ```
        
        Call to `jinja2-render`:
        
        ```sh
        jinja2-render v1.0
        ```
        
        Resulting in the following rendered Dockerfile:
        
        ```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()](https://jinja.palletsprojects.com/en/2.11.x/api/#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](https://github.com/pklaus/docker-epics/tree/master/epics_contapps),
        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*
        
        [Jinja2 For Loop]: https://jinja.palletsprojects.com/en/2.11.x/templates/#for
        
Keywords: Context-dependent Jinja2 Template Rendering CLI Docker Dockerfile
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Archiving :: Packaging
Description-Content-Type: text/markdown
