Metadata-Version: 2.3
Name: jinjanator
Version: 24.2.0
Summary: Command-line interface to Jinja2 for templating in shell scripts.
Project-URL: Bug Tracker, https://github.com/kpfleming/jinjanator/issues
Project-URL: Homepage, https://github.com/kpfleming/jinjanator
Author-email: "Kevin P. Fleming" <jinjanator@kevin.km6g.us>, Mark Vartanyan <kolypto@gmail.com>
License: Apache-2.0
License-File: LICENSE.apache-2.0
License-File: LICENSE.bsd-2-clause
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: attrs
Requires-Dist: jinja2>=2.7.2
Requires-Dist: jinjanator-plugins==24.1.*
Requires-Dist: pyyaml
Requires-Dist: typing-extensions
Description-Content-Type: text/markdown

# *jinjanator*: CLI tool for rendering Jinja2 templates


Features:

* Jinja2 templating
* INI, YAML, JSON data sources supported
* Environment variables can be used with or without data files
* Plugins can provide additional formats, filters, tests, extensions and global
  functions (see
  [jinjanator-plugins](https://github.com/kpfleming/jinjanator-plugins)
  for details)

## Installation

```
pip install jinjanator
```

## Available Plugins

* [jinjanator-plugin-ansible](https://pypi.org/project/jinjanator-plugin-ansible) -
  makes Ansible's 'core' filters and tests available during template
  rendering
* [jinjanator-plugin-format-toml](https://pypi.org/project/jinjanator-plugin-format-toml) -
  provides a TOML parser for input data files
* [jinjanator-plugin-format-xml](https://pypi.org/project/jinjanator-plugin-format-xml) -
  provides an XML parser for input data files

## Tutorial

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

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

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

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

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

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

```bash
$ 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.conf`options to write directly to the file.

## Tutorial with environment variables

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

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

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

```bash
$ 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:

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

Or, if you prefer, as a filter:

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

## CLI Reference
`jinjanate` accepts the following arguments:

* `template`: Jinja2 template file to render
* `data`: (optional) path to the data used for rendering.
    The default is `-`: use stdin.

Options:

* `--format FMT, -f FMT`: format for the data file. The default is
  `?`: guess from file extension. Supported formats are YAML (.yaml or
  .yml), JSON (.json), INI (.ini), and dotenv (.env), plus any formats
  provided by plugins you have installed.
* `--format-option OPT`: option to be passed to the parser for the
  data format selected with `--format` (or auto-selected). This can be
  specified multiple times. Refer to the documentation for the format
  itself to learn whether it supports any options.
* `--help, -h`: generates a help message describing usage of the tool.
* `--import-env VAR, -e VAR`: import all environment variables into
    the template as `VAR`.  To import environment variables into the
    global scope, give it an empty string: `--import-env=`.  (This
    will overwrite any existing variables with the same names!)
* `--output-file OUTFILE, -o OUTFILE`: Write rendered template to a
  file.
* `--quiet`: Avoid generating any output on stderr.
* `--undefined`: Allow undefined variables to be used in templates (no
  error will be raised).
* `--version`: prints the version of the tool and the Jinja2 package installed.

There is some special behavior with environment variables:

* When `data` is not provided (data is `-`), `--format` defaults to
  `env` and thus reads 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

* `array-name`: accepts a single string (e.g. `array-name=foo`), which
  must be a valid Python identifier and not a Python keyword. If this
  option is specified, and the JSON data provided is an `array`
  (sequence, list), the specified name will be used to make the data
  available to the Jinja2 template. Errors will be generated if
  `array` data is provided and this option is not specified, or if
  this option is specified and the data provided is an `object`.

#### 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

* `sequence-name`: accepts a single string (e.g. `sequence-name=foo`),
  which must be a valid Python identifier and not a Python keyword. If
  this option is specified, and the YAML data provided is a `sequence`
  (array, list), the specified name will be used to make the data
  available to the Jinja2 template. Errors will be generated if
  `sequence` data is provided and this option is not specified, or if
  this option is specified and the data provided is a `mapping`.

#### 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:

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

You can provide a default value:

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

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

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

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

- Added 'j2' CLI entrypoint, for users converting from 'j2cli'.
  [[#25](https://github.com/kpfleming/jinjanator/issues/25)](https://github.com/kpfleming/jinjanator/issues/25)
- Added support for Python 3.13.
  [[#31](https://github.com/kpfleming/jinjanator/issues/31)](https://github.com/kpfleming/jinjanator/issues/31)

---
[→ Full Changelog](https://github.com/kpfleming/jinjanator/blob/main/CHANGELOG.md)
