AVD Ecosystem - Jinja2 Linter
Build a Jinja2 linter that will provide the following capabilities:
- Validate syntax according to AVD style guide.
- Capability to run as part of a CI pipeline to enforce j2lint rules.
- Develop an extension that works with VSCode and potentially other IDEs i.e PyCharm.
Code | Short Description | Description |
---|---|---|
S0 | jinja-syntax-error |
Jinja2 syntax should be correct |
S1 | single-space-decorator |
A single space shall be added between Jinja2 curly brackets and a variable's name |
S2 | operator-enclosed-by-spaces |
When variables are used in combination with an operator, the operator shall be enclosed by space |
S3 | jinja-statements-indentation |
Nested jinja code block shall follow next rules: - All J2 statements must be enclosed by 1 space - All J2 statements must be indented by 4 more spaces within jinja delimiter - To close a control, end tag must have same indentation level |
S4 | jinja-statements-single-space |
Jinja statement should have a single space before and after |
S5 | jinja-statements-no-tabs |
Indentation are 4 spaces and NOT tabulation |
S6 | jinja-statements-delimiter |
Jinja statements should not have {%- or {%+ or -%} as delimiters |
S7 | single-statement-per-line |
Jinja statements should be on separate lines |
V1 | jinja-variable-lower-case |
All variables shall use lower case |
V2 | jinja-variable-format |
If variable is multi-words, underscore _ shall be used as a separator |
Python version 3.8+
To get started, you can use Python pip to install j2lint:
Install the latest stable version:
pip3 install j2lint
Install the latest development version:
pip3 install git+https://github.com/aristanetworks/j2lint.git
-
Create a virtual environment and activate it
python3 -m venv myenv source myenv/bin/activate
-
Install pip, jinja2 and jinja2-linter
sudo apt-get install python3-pip pip3 install jinja2 git clone https://github.com/aristanetworks/j2lint cd j2lint python setup.py install
j2lint <path-to-directory-of-templates>
j2lint <path-to-directory-of-templates>/template.j2
j2lint --list
j2lint <path-to-directory-of-templates> --verbose
j2lint <path-to-directory-of-templates> --log
To enable debug logs, use both options:
j2lint <path-to-directory-of-templates> --log --debug
j2lint <path-to-directory-of-templates> --json
-
The --ignore option can have one or more of these values: syntax-error, single-space-decorator, filter-enclosed-by-spaces, jinja-statement-single-space, jinja-statements-indentation, no-tabs, single-statement-per-line, jinja-delimiter, jinja-variable-lower-case, jinja-variable-format.
-
If multiple rules are to be ignored, use the --ignore option along with rule descriptions separated by space.
j2lint <path-to-directory-of-templates> --ignore <rule_description1> <rule_desc>
-
If one or more linting rules are to be ignored only for a specific jinja template file, add a Jinja comment at the top of the file. The rule can be disabled using the short description of the rule or the id of the rule.
{# j2lint: disable=S6} # OR {# j2lint: disable=jinja-delimiter #}
-
Disabling multiple rules
{# j2lint: disable=jinja-delimiter j2lint: disable=S1 #}
-
Create a new rules directory under j2lint folder.
-
Add custom rule classes which are similar to classes in j2lint/rules directory: The file name of rules should be in snake_case and the class name should be the PascalCase version of the file name. For example:
- File name:
jinja_operator_has_spaces_rule.py
- Class name:
JinjaOperatorHasSpacesRule
- File name:
-
Run the jinja2 linter using --rules-dir option
j2lint <path-to-directory-of-templates> --rules_dir <custom-rules-directory>
Note This runs the custom linting rules in addition to the default linting rules.
j2lint --help
j2lint --stdin
-
Add j2lint pre-commit hook inside your repository in .pre-commit-config.yaml.
- repo: https://github.com/aristanetworks/j2lint.git rev: <release_tag/sha> hooks: - id: j2lint
-
Run pre-commit ->
pre-commit run --all-files