J2Escape

Installation

pip install j2escape

Overview

This module, written in Python, facilitates the storage of Jinja2 templates within a project managed by Cookiecutter or Cruft.

Cookiecutter utilizes Jinja templates internally when substituting input variables in the source code. However, this can result in errors if a Jinja template, such as {% if config.allow_duplicates %}, is intended for the application rather than Cookiecutter or Cruft.

To circumvent this problem, this module employs the jinja2.lex() function to parse and appropriately escape the template blocks.

The transformation process is idempotent, meaning that an already escaped template will remain unchanged when escaped again.

Example:

Template	Escaped Template
{{ variable }}	{{ '{{' }} variable {{ '}}' }}
{% if config.allow_duplicates %}	{{ '{%' }} if config.allow_duplicates {{ '%}' }}

The module also provides a command-line interface that can be accessed using the j2escape command. This command can be utilized to escape jinja2 tags within a directory of templates.

j2escape usage

j2escape --help
usage: j2escape [-h] [-t TEMPLATES] [-o OUTPUT_DIR] [--overwrite] [-c] [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-f LOGFILE]

Escape jinja2 tags in a directory of templates.

options:
  -h, --help            show this help message and exit
  -t TEMPLATES, --templates TEMPLATES
                        A comma-separated string of Jinja Templates (*.j2) or a directory with *.j2 files.
  -o OUTPUT_DIR, --output-dir OUTPUT_DIR
                        Specifies the directory path where the escaped templates will be stored.
  --overwrite           Replaces the original templates. This is necessary if the --output-dir is not provided.
  -c, --create-ok       Generates the output directory if it doesn’t already exist.
  -l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --loglevel {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        log level
  -f LOGFILE, --logfile LOGFILE
                        Specifies the logfile. If not provided, the default is None

To use the module in Python code, you can import it as follows:

import j2escape

template_directory = "./source-dir"
output_directory = "./excaped-templates"
allow_create_output_dir = True

j2e = J2Escape(template_directory)
j2e.save_to_directory(outputdir=output_directory, create_ok=allow_create_output_dir)

The static method get_escaped() can be used to escape templates in memory:

escaped_tamplate_string = J2Escape.get_escaped(plain_template_string)

Development

Install poetry and pre-commit to manage the development environment.

Clone the repository and install the development dependencies:

git clone https://github.com/jifox/j2escape.git
cd j2escape
poetry install

pre-commit hooks are used to ensure code quality. To install the pre-commit hooks, run the following command:

pre-commit install

Use pre-commit to run the hooks on all files:

pre-commit run --all-files

Publishing to PyPi

To publish a new version to PyPi, first update the version number in pyproject.toml. Then, run the following commands to build and publish the package:

Initialize the pypi token:

At a first step you need to initialize the pypi token. This is a one time step. You can find the token in your pypi account settings.

MY_PYPI_USERNAME='__token__'
MY_PYPI_PASSWORD='pypi-myApiToken'

# Run once:
poetry config pypi-token.pypi $MY_PYPI_PASSWORD

Build and publish the package

# Build the package
poetry build

# Publish the package
poetry publish