template-specialize 1.1.0

Recursive template file specializer.

template-specialize

template-specialize is a command-line tool for rendering Jinja2 templates. It renders individual template files as well as directories of template files.

For example, consider this Markdown name tag template, "nametag.md":

## Hello, my name is

# {{name}}
{% if title is defined %}
### {{title}}
{% endif %}

To render the template file, execute template-specialize as follows. By default, templates are rendered to the terminal:

$ template-specialize nametag.md --key name --value 'John Doe'
## Hello, my name is

# John Doe

You can render the template file to an output file:

$ template-specialize nametag.md nametag-roy.md --key name --value 'Roy Hobbs' --key title --value 'The best there ever was'

You can also render templates contained within one or more directories to an output directory:

$ template-specialize templates/ output/ --key var --value value

Environment Files

template-specialize was created to "specialize" web service configuration files for different runtime environments. Environment files are YAML files that allow for the definition of inheritable, structured template configuration values. Consider the following environments file:

base:
  values:
    service_name: my-service

test_base:
  parents: [base]
  values:
     db_host: test-db-host

test:
  parents: [test_base]
  values:
     db_name: test-db

live:
  parents: [base]
  values:
     db_host: live-db-host
     db_name: live-db

To render a template file using an environment, specify the environment file (or files) and the environment name with which to render the template:

$ template-specialize config-template.yaml config.yaml -c environments.yaml -e test

To view the template configuration data use the "--dump" argument:

$ template-specialize -c environments.yaml -e test --dump
db_host: test-db-host
db_name: test-db
service_name: my-service

Renaming and Deleting Output Files

When specializing a template directory, it is sometimes necessary to rename an output file or directory. For example, consider a Python project template with the following structure:

.
|-- README.md
|-- package-name.txt
|-- setup.py
`-- src
    |-- __init__.py
    |-- package_name
    |   |-- __init__.py
    |   `-- package_name.py
    `-- tests
        |-- __init__.py
        `-- test_package_name.py

As part of the specialization, we'd like to rename the "package_name" directory, the "package_name.py" file, and the "test_package_name.py" file to the specialized package name. To accomplish this, we add the "package-name.txt' utility file and call the "template_specialize_rename" Jinja2 extension:

{# Rename template files #}
{% template_specialize_rename 'src/tests/test_package_name.py', 'test_' + package_name + '.py' %}
{% template_specialize_rename 'src/package_name/package_name.py', package_name + '.py' %}
{% template_specialize_rename 'src/package_name', package_name %}

{# Delete the package-name.txt utility template file #}
{% template_specialize_rename 'package-name.txt' %}

First, the "template_specialize_rename" extension is used to rename the package output files and directories. Finally, since we don't want the empty utility file in the output, we delete it using the "template_specialize_rename" extension with no second argument. Here's an example usage of our Python project template:

$ template-specialize python-package my-package --key package_name --value my_package

This command produces the following specialized template output with appropriately named package source directory and source files:

.
|-- README.md
|-- setup.py
`-- src
    |-- __init__.py
    |-- my_package
    |   |-- __init__.py
    |   `-- my_package.py
    `-- tests
        |-- __init__.py
        `-- test_my_package.py

AWS Parameter Store

template-specialize can retrieve template values from AWS Parameter Store using botocore.

Here's an example of a YAML configuration file with a Parameter Store secret:

my_secret: {% filter tojson %}{% aws_parameter_store 'parameter-name' %}{% endfilter %}

botocore is usually configured using environment variables.

Usage

usage: template-specialize [-h] [-c FILE] [-e ENV] [--key KEY] [--value VALUE]
                           [--dump] [-v]
                           [SRC] [DST]

positional arguments:
  SRC            the source template file or directory
  DST            the destination file or directory

options:
  -h, --help     show this help message and exit
  -c FILE        the environment files
  -e ENV         the environment name
  --key KEY      add a template key. Must be paired with a template value.
  --value VALUE  add a template value. Must be paired with a template key.
  --dump         dump the template variables
  -v, --version  show version number and quit

Development

This project is developed using Python Build.