https://github.com/jifox/j2escape
Jinja2 Template Escaper
https://github.com/jifox/j2escape
command-line-tool cookiecutter cruft jinja2-templates python-module python3
Last synced: 2 months ago
JSON representation
Jinja2 Template Escaper
- Host: GitHub
- URL: https://github.com/jifox/j2escape
- Owner: jifox
- License: apache-2.0
- Created: 2023-03-17T10:06:14.000Z (about 3 years ago)
- Default Branch: develop
- Last Pushed: 2023-10-04T03:50:16.000Z (over 2 years ago)
- Last Synced: 2025-09-28T07:21:45.936Z (6 months ago)
- Topics: command-line-tool, cookiecutter, cruft, jinja2-templates, python-module, python3
- Language: Python
- Homepage:
- Size: 147 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# J2Escape
[](https://github.com/jifox/j2escape/actions/workflows/python-package.yml)
[](https://www.python.org/downloads/release/python-370/)
[](https://www.python.org/downloads/release/python-380/)
[](https://www.python.org/downloads/release/python-390/)
[](https://www.python.org/downloads/release/python-310/)
[](https://www.python.org/downloads/release/python-311/)
### Installation
```
pip install j2escape
```
### Overview
This module, written in Python, facilitates the storage of Jinja2 templates within a project managed by [Cookiecutter](https://github.com/cookiecutter/cookiecutter) or [Cruft](https://github.com/cruft/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
```bash
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:
```python
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](https://python-poetry.org/docs/#installation) and [pre-commit](https://pre-commit.com/#install) to manage the development environment.
Clone the repository and install the development dependencies:
```bash
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:
```bash
pre-commit install
```
Use pre-commit to run the hooks on all files:
```bash
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.
```bash
MY_PYPI_USERNAME='__token__'
MY_PYPI_PASSWORD='pypi-myApiToken'
# Run once:
poetry config pypi-token.pypi $MY_PYPI_PASSWORD
```
**Build and publish the package**
```bash
# Build the package
poetry build
# Publish the package
poetry publish
```