search

kpfleming / jinjanator

Jinja2 Command-Line Tool, reworked, again
BSD 2-Clause "Simplified" License
74 stars 5 forks source link
cli jinja2 jinja2-cli python python3

readme

jinjanator

Open Source Initiative Approved License logo CI Python License - Apache 2.0 Types - Mypy Code Style and Quality - Ruff Project Management - Hatch Testing - Pytest

This repo contains jinjanator, a CLI tool to render Jinja2 templates. It is a fork of j2cli, which itself was a fork of jinja2-cli, both of which are no longer actively maintained.

Open Source software: Apache License 2.0

 

Features:

Installation

pip install jinjanator

Available Plugins

Tutorial

Suppose you have an NGINX configuration file template, nginx.j2:

server {
  listen 80;
  server_name {{ nginx.hostname }};

  root {{ nginx.webroot }};
  index index.htm;
}

And you have a JSON file with the data, nginx.json:

{
    "nginx":{
        "hostname": "localhost",
        "webroot": "/var/www/project"
    }
}

This is how you render it into a working configuration file:

$ jinjanate nginx.j2 nginx.json > nginx.conf

The output is saved to nginx.conf:

server {
  listen 80;
  server_name localhost;

  root /var/www/project;
  index index.htm;
}

Alternatively, you can use the -o nginx.conf or --output-file nginx.confoptions to write directly to the file.

Tutorial with environment variables

Suppose, you have a very simple template, person.xml.j2:

<data><name>{{ name }}</name><age>{{ age }}</age></data>

What is the easiest way to use jinjanator here? Use environment variables in your Bash script:

$ export name=Andrew
$ export age=31
$ jinjanate /tmp/person.xml.j2
<data><name>Andrew</name><age>31</age></data>

Using environment variables

Even when you use a data file as the data source, you can always access environment variables using the env() function:

Username: {{ login }}
Password: {{ env("APP_PASSWORD") }}

Or, if you prefer, as a filter:

Username: {{ login }}
Password: {{ "APP_PASSWORD" | env }}

CLI Reference

jinjanate accepts the following arguments:

Options:

There is some special behavior with environment variables:

Usage Examples

Render a template using INI-file data source:

$ jinjanate config.j2 data.ini

Render using JSON data source:

$ jinjanate config.j2 data.json

Render using YAML data source:

$ jinjanate config.j2 data.yaml

Render using JSON data on stdin:

$ curl http://example.com/service.json | jinjanate --format=json config.j2 -

Render using environment variables:

$ jinjanate config.j2

Or use environment variables from a file:

$ jinjanate config.j2 data.env

Or pipe it: (note that you'll have to use "-" in this particular case):

$ jinjanate --format=env config.j2 - < data.env

Data Formats

dotenv

Data input from environment variables.

Options

This format does not support any options.

Usage

Render directly from the current environment variable values:

$ jinjanate config.j2

Or alternatively, read the values from a dotenv file:

NGINX_HOSTNAME=localhost
NGINX_WEBROOT=/var/www/project
NGINX_LOGS=/var/log/nginx/

And render with:

$ jinjanate config.j2 data.env

Or:

$ env | jinjanate --format=env config.j2

If you're going to pipe a dotenv file into jinjanate, you'll need to use "-" as the second argument:

$ jinjanate config.j2 - < data.env

INI

INI data input format.

Options

This format does not support any options.

Usage

data.ini:

[nginx]
hostname=localhost
webroot=/var/www/project
logs=/var/log/nginx

Usage:

$ jinjanate config.j2 data.ini

Or:

$ cat data.ini | jinjanate --format=ini config.j2

JSON

JSON data input format.

Options

Usage

data.json:

{
    "nginx":{
        "hostname": "localhost",
        "webroot": "/var/www/project",
        "logs": "/var/log/nginx"
    }
}

Usage:

$ jinjanate config.j2 data.json

Or:

$ cat data.json | jinjanate --format=ini config.j2

YAML

YAML data input format.

Options

Usage

data.yaml:

nginx:
  hostname: localhost
  webroot: /var/www/project
  logs: /var/log/nginx

Usage:

$ jinjanate config.j2 data.yml

Or:

$ cat data.yml | jinjanate --format=yaml config.j2

Filters

env(varname, default=None)

Use an environment variable's value in the template.

This filter is available even when your data source is something other than the environment.

Example:

User: {{ user_login }}
Pass: {{ "USER_PASSWORD" | env }}

You can provide a default value:

Pass: {{ "USER_PASSWORD" | env("-none-") }}

For your convenience, it's also available as a global function:

User: {{ user_login }}
Pass: {{ env("USER_PASSWORD") }}

Notice that there must be quotes around the environment variable name when it is a literal string.

Chat

If you'd like to chat with the jinjanator community, join us on Matrix!

Credits

This tool was created from j2cli, which itself was created from jinja2-cli. It was created to bring the project up to 'modern' Python coding, packaging, and project-management standards, and to support plugins to provide extensibility.

"Standing on the shoulders of giants" could not be more true than it is in the Python community; this project relies on many wonderful tools and libraries produced by the global open source software community, in addition to Python itself. I've listed many of them below, but if I've overlooked any please do not be offended :-)