| Name | j2lint JSON |
| Version |
1.1.0
JSON |
| download |
| home_page | |
| Summary | Command-line utility that validates jinja2 syntax according to Arista's AVD style guide. |
| upload_time | 2023-07-11 09:23:51 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2021 Arista Networks Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
j2lint
linter
jinja
lint
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://github.com/aristanetworks/j2lint/blob/devel/LICENSE)
[](https://pypi.python.org/pypi/j2lint/)
[](https://pypi.python.org/pypi/j2lint/)
[](https://pypi.python.org/pypi/j2lint/)
[](https://github.com/aristanetworks/j2lint/graphs/commit-activity)
# Jinja2-Linter
AVD Ecosystem - Jinja2 Linter
## Project Goals
Build a Jinja2 linter that will provide the following capabilities:
- Validate syntax according to [AVD style guide](https://avd.sh/en/stable/docs/contribution/style-guide.html).
- 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.
## Syntax and code style issues
| Code | Short Description | Description |
|------|-------------------|-------------|
| S0 | `jinja-syntax-error` | Jinja2 syntax should be correct |
| S1 | `single-space-decorator` | A single space should 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 should follow next rules:<br>- All J2 statements must be enclosed by 1 space<br>- All J2 statements must be indented by 4 more spaces within jinja delimiter<br>- To close a control, end tag must have same indentation level |
| S4 | `jinja-statements-single-space` | Jinja statement should have at least a single space after '{%' and a single space before '%}' |
| S5 | `jinja-statements-no-tabs` | Indentation should not use tabulation but 4 spaces |
| 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 should use lower case |
| V2 | `jinja-variable-format` | If variable is multi-words, underscore `_` should be used as a separator |
## Getting Started
### Requirements
Python version 3.8+
### Install with pip
To get started, you can use Python pip to install j2lint:
**Install the latest stable version:**
```bash
pip3 install j2lint
```
**Install the latest development version:**
```bash
pip3 install git+https://github.com/aristanetworks/j2lint.git
```
## Running the linter
```bash
j2lint <path-to-directory-of-templates>
```
### Running the linter on a specific file
```bash
j2lint <path-to-directory-of-templates>/template.j2
```
### Listing linting rules
```bash
j2lint --list
```
### Running the linter with verbose linter error output
```bash
j2lint <path-to-directory-of-templates> --verbose
```
### Running the linter with logs enabled. Logs saved in jinja2-linter.log in the current directory
```bash
j2lint <path-to-directory-of-templates> --log
```
To enable debug logs, use both options:
```bash
j2lint <path-to-directory-of-templates> --log --debug
```
### Running the linter with JSON format for linter error output
```bash
j2lint <path-to-directory-of-templates> --json
```
### Ignoring rules
1. 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.
2. If multiple rules are to be ignored, use the --ignore option along with rule descriptions separated by space.
```bash
j2lint <path-to-directory-of-templates> --ignore <rule_description1> <rule_desc>
```
> **Note**
> This runs the custom linting rules in addition to the default linting rules.
> When using the `-i/--ignore` or `-w/--warn` options, the arguments MUST either:
> * Be entered at the end of the CLI as in the example above
> * Be entered as the last options before the `<path-to-directory-of-templates>`
> with `--` separator. e.g.
> ```bash
> j2lint --ignore <rule_description1> <rule_desc> -- <path-to-directory-of-templates>
> ```
3. 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.
```jinja2
{# j2lint: disable=S6}
# OR
{# j2lint: disable=jinja-delimiter #}
```
4. Disabling multiple rules
```jinja2
{# j2lint: disable=jinja-delimiter j2lint: disable=S1 #}
```
### Adding custom rules
1. Create a new rules directory under j2lint folder.
2. 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`
3. Run the jinja2 linter using --rules-dir option
```bash
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.
### Running jinja2 linter help command
```bash
j2lint --help
```
### Running jinja2 linter on STDIN template. This option can be used with VS Code.
```bash
j2lint --stdin
```
### Using j2lint as a pre-commit-hook
1. Add j2lint pre-commit hook inside your repository in .pre-commit-config.yaml.
```bash
- repo: https://github.com/aristanetworks/j2lint.git
rev: <release_tag/sha>
hooks:
- id: j2lint
```
2. Run pre-commit -> `pre-commit run --all-files`
> **Note**
> When using `-i/--ignore` or `-w/--warn` argument in pre-commit, use the
> following syntax
>
> ```bash
> - repo: https://github.com/aristanetworks/j2lint.git
> rev: <release_tag/sha>
> hooks:
> - id: j2lint
> # Using -- to separate the end of ignore from the positional arguments
> # passed to j2lint
> args: [--ignore, S3, jinja-statements-single-space, --]
> ```
## Acknowledgments
This project is based on [salt-lint](https://github.com/warpnet/salt-lint) and [jinjalint](https://github.com/motet-a/jinjalint)
Raw data
{
"_id": null,
"home_page": "",
"name": "j2lint",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "j2lint,linter,jinja,lint",
"author": "",
"author_email": "Arista Ansible Team <ansible@arista.com>",
"download_url": "https://files.pythonhosted.org/packages/f1/bb/e91a64a47ee2203839c3113b9b64500a55e33a80f170077e8945218b955e/j2lint-1.1.0.tar.gz",
"platform": null,
"description": "[](https://github.com/aristanetworks/j2lint/blob/devel/LICENSE)\n[](https://pypi.python.org/pypi/j2lint/)\n[](https://pypi.python.org/pypi/j2lint/)\n[](https://pypi.python.org/pypi/j2lint/)\n[](https://github.com/aristanetworks/j2lint/graphs/commit-activity)\n\n# Jinja2-Linter\n\nAVD Ecosystem - Jinja2 Linter\n\n## Project Goals\n\nBuild a Jinja2 linter that will provide the following capabilities:\n\n- Validate syntax according to [AVD style guide](https://avd.sh/en/stable/docs/contribution/style-guide.html).\n- Capability to run as part of a CI pipeline to enforce j2lint rules.\n- Develop an extension that works with VSCode and potentially other IDEs i.e PyCharm.\n\n## Syntax and code style issues\n\n| Code | Short Description | Description |\n|------|-------------------|-------------|\n| S0 | `jinja-syntax-error` | Jinja2 syntax should be correct |\n| S1 | `single-space-decorator` | A single space should be added between Jinja2 curly brackets and a variable's name |\n| S2 | `operator-enclosed-by-spaces` | When variables are used in combination with an operator, the operator shall be enclosed by space |\n| S3 | `jinja-statements-indentation` | Nested jinja code block should follow next rules:<br>- All J2 statements must be enclosed by 1 space<br>- All J2 statements must be indented by 4 more spaces within jinja delimiter<br>- To close a control, end tag must have same indentation level |\n| S4 | `jinja-statements-single-space` | Jinja statement should have at least a single space after '{%' and a single space before '%}' |\n| S5 | `jinja-statements-no-tabs` | Indentation should not use tabulation but 4 spaces |\n| S6 | `jinja-statements-delimiter` | Jinja statements should not have {%- or {%+ or -%} as delimiters |\n| S7 | `single-statement-per-line` | Jinja statements should be on separate lines |\n| V1 | `jinja-variable-lower-case` | All variables should use lower case |\n| V2 | `jinja-variable-format` | If variable is multi-words, underscore `_` should be used as a separator |\n\n## Getting Started\n\n### Requirements\n\nPython version 3.8+\n\n### Install with pip\n\nTo get started, you can use Python pip to install j2lint:\n\n**Install the latest stable version:**\n\n```bash\npip3 install j2lint\n```\n\n**Install the latest development version:**\n\n```bash\npip3 install git+https://github.com/aristanetworks/j2lint.git\n```\n\n## Running the linter\n\n```bash\nj2lint <path-to-directory-of-templates>\n```\n\n### Running the linter on a specific file\n\n```bash\nj2lint <path-to-directory-of-templates>/template.j2\n```\n\n### Listing linting rules\n\n```bash\nj2lint --list\n```\n\n### Running the linter with verbose linter error output\n\n```bash\nj2lint <path-to-directory-of-templates> --verbose\n```\n\n### Running the linter with logs enabled. Logs saved in jinja2-linter.log in the current directory\n\n```bash\nj2lint <path-to-directory-of-templates> --log\n```\n\nTo enable debug logs, use both options:\n\n```bash\nj2lint <path-to-directory-of-templates> --log --debug\n```\n\n### Running the linter with JSON format for linter error output\n\n```bash\nj2lint <path-to-directory-of-templates> --json\n```\n\n### Ignoring rules\n\n1. 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.\n\n2. If multiple rules are to be ignored, use the --ignore option along with rule descriptions separated by space.\n\n ```bash\n j2lint <path-to-directory-of-templates> --ignore <rule_description1> <rule_desc>\n ```\n\n> **Note**\n> This runs the custom linting rules in addition to the default linting rules.\n> When using the `-i/--ignore` or `-w/--warn` options, the arguments MUST either:\n> * Be entered at the end of the CLI as in the example above\n> * Be entered as the last options before the `<path-to-directory-of-templates>`\n> with `--` separator. e.g.\n> ```bash\n> j2lint --ignore <rule_description1> <rule_desc> -- <path-to-directory-of-templates>\n> ```\n\n3. 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.\n\n ```jinja2\n {# j2lint: disable=S6}\n\n # OR\n {# j2lint: disable=jinja-delimiter #}\n ```\n\n4. Disabling multiple rules\n\n ```jinja2\n {# j2lint: disable=jinja-delimiter j2lint: disable=S1 #}\n ```\n\n### Adding custom rules\n\n1. Create a new rules directory under j2lint folder.\n2. Add custom rule classes which are similar to classes in j2lint/rules directory:\n 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:\n - File name: `jinja_operator_has_spaces_rule.py`\n - Class name: `JinjaOperatorHasSpacesRule`\n\n3. Run the jinja2 linter using --rules-dir option\n\n ```bash\n j2lint <path-to-directory-of-templates> --rules-dir <custom-rules-directory>\n ```\n\n> **Note**\n> This runs the custom linting rules in addition to the default linting rules.\n\n### Running jinja2 linter help command\n\n```bash\nj2lint --help\n```\n\n### Running jinja2 linter on STDIN template. This option can be used with VS Code.\n\n```bash\nj2lint --stdin\n```\n\n### Using j2lint as a pre-commit-hook\n\n1. Add j2lint pre-commit hook inside your repository in .pre-commit-config.yaml.\n\n ```bash\n - repo: https://github.com/aristanetworks/j2lint.git\n rev: <release_tag/sha>\n hooks:\n - id: j2lint\n ```\n\n2. Run pre-commit -> `pre-commit run --all-files`\n\n> **Note**\n> When using `-i/--ignore` or `-w/--warn` argument in pre-commit, use the\n> following syntax\n>\n> ```bash\n> - repo: https://github.com/aristanetworks/j2lint.git\n> rev: <release_tag/sha>\n> hooks:\n> - id: j2lint\n> # Using -- to separate the end of ignore from the positional arguments\n> # passed to j2lint\n> args: [--ignore, S3, jinja-statements-single-space, --]\n> ```\n\n## Acknowledgments\n\nThis project is based on [salt-lint](https://github.com/warpnet/salt-lint) and [jinjalint](https://github.com/motet-a/jinjalint)\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2021 Arista Networks Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Command-line utility that validates jinja2 syntax according to Arista's AVD style guide.",
"version": "1.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/aristanetworks/j2lint/issues",
"Homepage": "https://github.com/aristanetworks/j2lint.git"
},
"split_keywords": [
"j2lint",
"linter",
"jinja",
"lint"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0d0934fc0358503fb49a16e86a660a8b550cbadd8fa593142c2d53855a74bb95",
"md5": "92a4f2987b508f29f1fccfd35c2f342b",
"sha256": "f1e51f8858c96a1bfa190d6d96b1273f0748f58854a3d570c8d24dccaa170fa0"
},
"downloads": -1,
"filename": "j2lint-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "92a4f2987b508f29f1fccfd35c2f342b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 30932,
"upload_time": "2023-07-11T09:23:49",
"upload_time_iso_8601": "2023-07-11T09:23:49.692006Z",
"url": "https://files.pythonhosted.org/packages/0d/09/34fc0358503fb49a16e86a660a8b550cbadd8fa593142c2d53855a74bb95/j2lint-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f1bbe91a64a47ee2203839c3113b9b64500a55e33a80f170077e8945218b955e",
"md5": "f9969538f2b28c62f183053988c058c0",
"sha256": "719c114d5702f67a9fcc0c65c63eb2959c97caf5e8befb90548c61c8265cd88e"
},
"downloads": -1,
"filename": "j2lint-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "f9969538f2b28c62f183053988c058c0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 28719,
"upload_time": "2023-07-11T09:23:51",
"upload_time_iso_8601": "2023-07-11T09:23:51.201975Z",
"url": "https://files.pythonhosted.org/packages/f1/bb/e91a64a47ee2203839c3113b9b64500a55e33a80f170077e8945218b955e/j2lint-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-11 09:23:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aristanetworks",
"github_project": "j2lint",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "j2lint"
}
