ramplint 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ramplint-0.1.0/.gitignore +25 -0
- ramplint-0.1.0/CHANGELOG.md +25 -0
- ramplint-0.1.0/LICENSE +21 -0
- ramplint-0.1.0/PKG-INFO +317 -0
- ramplint-0.1.0/README.md +283 -0
- ramplint-0.1.0/docs/demo.svg +138 -0
- ramplint-0.1.0/examples/README.md +27 -0
- ramplint-0.1.0/examples/templates/accounts/login.html +20 -0
- ramplint-0.1.0/examples/templates/base.html +21 -0
- ramplint-0.1.0/examples/templates/clean/tricky_but_valid.html +44 -0
- ramplint-0.1.0/examples/templates/orders/list.html +28 -0
- ramplint-0.1.0/examples/templates/orders/list_fixed.html +29 -0
- ramplint-0.1.0/examples/templates/partials/footer.html +12 -0
- ramplint-0.1.0/examples/templates/partials/navbar.html +11 -0
- ramplint-0.1.0/examples/templates/products/detail.html +30 -0
- ramplint-0.1.0/pyproject.toml +70 -0
- ramplint-0.1.0/src/ramplint/__init__.py +16 -0
- ramplint-0.1.0/src/ramplint/__main__.py +5 -0
- ramplint-0.1.0/src/ramplint/cli.py +134 -0
- ramplint-0.1.0/src/ramplint/config.py +61 -0
- ramplint-0.1.0/src/ramplint/dom.py +152 -0
- ramplint-0.1.0/src/ramplint/linter.py +115 -0
- ramplint-0.1.0/src/ramplint/py.typed +0 -0
- ramplint-0.1.0/src/ramplint/reporters.py +74 -0
- ramplint-0.1.0/src/ramplint/rules/__init__.py +38 -0
- ramplint-0.1.0/src/ramplint/rules/base.py +33 -0
- ramplint-0.1.0/src/ramplint/rules/controls.py +59 -0
- ramplint-0.1.0/src/ramplint/rules/document.py +25 -0
- ramplint-0.1.0/src/ramplint/rules/forms.py +56 -0
- ramplint-0.1.0/src/ramplint/rules/headings.py +45 -0
- ramplint-0.1.0/src/ramplint/rules/images.py +38 -0
- ramplint-0.1.0/src/ramplint/rules/names.py +50 -0
- ramplint-0.1.0/src/ramplint/rules/tables.py +58 -0
- ramplint-0.1.0/src/ramplint/template.py +149 -0
- ramplint-0.1.0/tests/conftest.py +22 -0
- ramplint-0.1.0/tests/test_cli.py +129 -0
- ramplint-0.1.0/tests/test_rules.py +282 -0
- ramplint-0.1.0/tests/test_template.py +87 -0
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*.egg-info/
|
|
5
|
+
build/
|
|
6
|
+
dist/
|
|
7
|
+
.eggs/
|
|
8
|
+
|
|
9
|
+
# Virtual environments
|
|
10
|
+
.venv/
|
|
11
|
+
venv/
|
|
12
|
+
env/
|
|
13
|
+
|
|
14
|
+
# Tooling caches
|
|
15
|
+
.pytest_cache/
|
|
16
|
+
.ruff_cache/
|
|
17
|
+
.mypy_cache/
|
|
18
|
+
.coverage
|
|
19
|
+
coverage.xml
|
|
20
|
+
htmlcov/
|
|
21
|
+
|
|
22
|
+
# IDEs / OS
|
|
23
|
+
.idea/
|
|
24
|
+
.vscode/
|
|
25
|
+
.DS_Store
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented here.
|
|
4
|
+
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
|
|
5
|
+
and the project uses [Semantic Versioning](https://semver.org/).
|
|
6
|
+
|
|
7
|
+
## [Unreleased]
|
|
8
|
+
|
|
9
|
+
## [0.1.0] - 2026-10-20
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- Template-aware parsing for Django and Jinja2 (`{{ }}`, `{% %}`, `{# #}`,
|
|
14
|
+
`{% comment %}`) with exact line/column positions.
|
|
15
|
+
- Rules: `RL101` img-alt, `RL201` table-header, `RL301` heading-order,
|
|
16
|
+
`RL302` empty-heading, `RL401` form-label, `RL501` button-name,
|
|
17
|
+
`RL502` link-name, `RL601` html-lang.
|
|
18
|
+
- Inline suppressions: `{# ramplint: ignore RL101 #}` and
|
|
19
|
+
`{# ramplint: ignore-file #}`.
|
|
20
|
+
- `text`, `json` and `github` output formats.
|
|
21
|
+
- Configuration via `[tool.ramplint]` in `pyproject.toml`.
|
|
22
|
+
- pre-commit hook.
|
|
23
|
+
|
|
24
|
+
[Unreleased]: https://github.com/iLLcruS/ramplint/compare/v0.1.0...HEAD
|
|
25
|
+
[0.1.0]: https://github.com/iLLcruS/ramplint/releases/tag/v0.1.0
|
ramplint-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Vladyslav Rostovskyi
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
ramplint-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,317 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: ramplint
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Accessibility (WCAG) linter for Django and Jinja2 templates
|
|
5
|
+
Project-URL: Homepage, https://github.com/iLLcruS/ramplint
|
|
6
|
+
Project-URL: Issues, https://github.com/iLLcruS/ramplint/issues
|
|
7
|
+
Project-URL: Changelog, https://github.com/iLLcruS/ramplint/blob/main/CHANGELOG.md
|
|
8
|
+
Project-URL: Funding, https://ko-fi.com/innerexcept
|
|
9
|
+
Author-email: Vladyslav Rostovskyi <rostovskii.1020@gmail.com>
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: a11y,accessibility,django,jinja2,linter,templates,wcag
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Environment :: Console
|
|
15
|
+
Classifier: Framework :: Django
|
|
16
|
+
Classifier: Intended Audience :: Developers
|
|
17
|
+
Classifier: Operating System :: OS Independent
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
24
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
25
|
+
Classifier: Topic :: Text Processing :: Markup :: HTML
|
|
26
|
+
Classifier: Typing :: Typed
|
|
27
|
+
Requires-Python: >=3.10
|
|
28
|
+
Requires-Dist: tomli>=1.1; python_version < '3.11'
|
|
29
|
+
Provides-Extra: dev
|
|
30
|
+
Requires-Dist: pytest-cov>=4; extra == 'dev'
|
|
31
|
+
Requires-Dist: pytest>=7; extra == 'dev'
|
|
32
|
+
Requires-Dist: ruff>=0.6; extra == 'dev'
|
|
33
|
+
Description-Content-Type: text/markdown
|
|
34
|
+
|
|
35
|
+
<h1 align="center">ramplint</h1>
|
|
36
|
+
|
|
37
|
+
<p align="center">
|
|
38
|
+
<strong>Accessibility linter for Django and Jinja2 templates.</strong><br>
|
|
39
|
+
Catch WCAG problems in your <code>.html</code> templates before they reach production.
|
|
40
|
+
</p>
|
|
41
|
+
|
|
42
|
+
<p align="center">
|
|
43
|
+
<a href="https://github.com/iLLcruS/ramplint/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/iLLcruS/ramplint/actions/workflows/ci.yml/badge.svg"></a>
|
|
44
|
+
<a href="https://pypi.org/project/ramplint/"><img alt="PyPI" src="https://img.shields.io/pypi/v/ramplint.svg"></a>
|
|
45
|
+
<img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-blue.svg">
|
|
46
|
+
<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green.svg"></a>
|
|
47
|
+
<a href="https://ko-fi.com/innerexcept"><img alt="Support on Ko-fi" src="https://img.shields.io/badge/Ko--fi-support-72a4f2?logo=ko-fi&logoColor=white"></a>
|
|
48
|
+
</p>
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
Generic HTML linters choke on `{% if %}`, `{{ variables }}` and `{% include %}`,
|
|
53
|
+
and browser-based checkers only see the pages you remember to open.
|
|
54
|
+
**ramplint** reads your templates directly, understands the template syntax,
|
|
55
|
+
and reports problems with the exact line and column in the template source:
|
|
56
|
+
|
|
57
|
+
<p align="center">
|
|
58
|
+
<img src="docs/demo.svg" alt="Terminal output of ramplint reporting six accessibility problems in a Django product page template">
|
|
59
|
+
</p>
|
|
60
|
+
|
|
61
|
+
## Try it in 30 seconds
|
|
62
|
+
|
|
63
|
+
The repository ships with a small demo shop in [`examples/`](examples/): a
|
|
64
|
+
deliberately inaccessible set of Django templates that triggers every rule,
|
|
65
|
+
plus a file full of tricky-but-valid template patterns that must stay silent.
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
git clone https://github.com/iLLcruS/ramplint.git
|
|
69
|
+
cd ramplint
|
|
70
|
+
pip install .
|
|
71
|
+
ramplint examples/
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
```console
|
|
75
|
+
examples/templates/base.html:3:1: RL601 <html> is missing a lang attribute; add e.g. lang="en" or lang="{{ LANGUAGE_CODE }}" [html-lang]
|
|
76
|
+
examples/templates/base.html:11:5: RL502 <a> link has no accessible name; add text, an aria-label, or alt text on the image inside it [link-name]
|
|
77
|
+
examples/templates/base.html:11:45: RL101 <img> is missing an alt attribute (use alt="" for decorative images) [img-alt]
|
|
78
|
+
examples/templates/accounts/login.html:9:3: RL401 <input type="text"> has no associated label; add an id and a matching <label for>, or wrap it in a <label> (a placeholder is not a label) [form-label]
|
|
79
|
+
...
|
|
80
|
+
examples/templates/products/detail.html:28:3: RL101 <input type="image"> needs a non-empty alt attribute describing the action [img-alt]
|
|
81
|
+
|
|
82
|
+
Found 26 problems in 6 of 8 files.
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
See [`examples/README.md`](examples/README.md) for what each demo template contains.
|
|
86
|
+
|
|
87
|
+
## Highlights
|
|
88
|
+
|
|
89
|
+
- **Template-aware.** Django and Jinja2 tags, variables and comments are understood, not stripped blindly.
|
|
90
|
+
- **Low noise.** If something is only known at render time (`{% include %}`, `{{ widget.attrs }}`, `{% block %}`), ramplint assumes the best and stays quiet.
|
|
91
|
+
- **Zero dependencies.** Pure Python standard library (plus `tomli` on Python < 3.11).
|
|
92
|
+
- **Made for CI.** Exit codes, JSON output, GitHub Actions annotations and a pre-commit hook.
|
|
93
|
+
- **Fast.** No browser and no rendering. A whole project is checked in well under a second.
|
|
94
|
+
|
|
95
|
+
## Installation
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
pip install ramplint
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## Usage
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
ramplint # lint every template under the current directory
|
|
105
|
+
ramplint templates/ shop/templates/base.html
|
|
106
|
+
ramplint --select RL1,RL5 # only image and control rules
|
|
107
|
+
ramplint --ignore heading-order # rules can be referenced by code or name
|
|
108
|
+
ramplint --format json # machine-readable output
|
|
109
|
+
ramplint --list-rules
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
By default ramplint looks at `.html`, `.htm`, `.jinja`, `.jinja2`, `.j2` and
|
|
113
|
+
`.djhtml` files and skips folders such as `node_modules`, `.venv`, `build` and `dist`.
|
|
114
|
+
Files passed explicitly are always checked, whatever their extension.
|
|
115
|
+
|
|
116
|
+
| Exit code | Meaning |
|
|
117
|
+
|-----------|------------------------------|
|
|
118
|
+
| `0` | No problems found |
|
|
119
|
+
| `1` | Problems found |
|
|
120
|
+
| `2` | Usage or configuration error |
|
|
121
|
+
|
|
122
|
+
## Rules
|
|
123
|
+
|
|
124
|
+
| Code | Name | What it checks | WCAG |
|
|
125
|
+
|---------|-----------------|------------------------------------------------------------------------------------------|------------------|
|
|
126
|
+
| `RL101` | `img-alt` | `<img>` has an `alt` attribute; `<input type="image">` and `<area>` have non-empty `alt` | 1.1.1 (A) |
|
|
127
|
+
| `RL201` | `table-header` | Data tables use real `<th>` header cells | 1.3.1 (A) |
|
|
128
|
+
| `RL301` | `heading-order` | Heading levels do not skip (`<h2>` → `<h4>`) | 1.3.1 (A) |
|
|
129
|
+
| `RL302` | `empty-heading` | Headings are not empty | 2.4.6 (AA) |
|
|
130
|
+
| `RL401` | `form-label` | `<input>`, `<select>` and `<textarea>` have an associated `<label>` | 1.3.1, 4.1.2 (A) |
|
|
131
|
+
| `RL501` | `button-name` | Buttons (including icon-only buttons) have an accessible name | 4.1.2 (A) |
|
|
132
|
+
| `RL502` | `link-name` | Links have an accessible name | 2.4.4, 4.1.2 (A) |
|
|
133
|
+
| `RL601` | `html-lang` | `<html>` declares the page language | 3.1.1 (A) |
|
|
134
|
+
|
|
135
|
+
<details>
|
|
136
|
+
<summary><strong>Examples for every rule</strong></summary>
|
|
137
|
+
|
|
138
|
+
#### RL101 `img-alt`
|
|
139
|
+
|
|
140
|
+
```django
|
|
141
|
+
{# ✗ #} <img src="{% static 'logo.png' %}">
|
|
142
|
+
{# ✓ #} <img src="{% static 'logo.png' %}" alt="ACME">
|
|
143
|
+
{# ✓ #} <img src="{% static 'divider.png' %}" alt=""> {# decorative #}
|
|
144
|
+
{# ✓ #} <img src="{{ product.image.url }}" alt="{{ product.name }}">
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
#### RL201 `table-header`
|
|
148
|
+
|
|
149
|
+
```django
|
|
150
|
+
{# ✗ #} <table><tr><td>Name</td><td>Price</td></tr>…</table>
|
|
151
|
+
{# ✓ #} <table><tr><th scope="col">Name</th><th scope="col">Price</th></tr>…</table>
|
|
152
|
+
{# ✓ #} <table role="presentation">…</table> {# layout table #}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
`role="columnheader"` on a `<td>` is not accepted. Use a real `<th>`.
|
|
156
|
+
Tables whose rows come from `{% include %}`, `{% block %}` or `{{ form.as_table }}`
|
|
157
|
+
are skipped because their content is not visible in the template.
|
|
158
|
+
|
|
159
|
+
#### RL301 `heading-order`
|
|
160
|
+
|
|
161
|
+
```django
|
|
162
|
+
{# ✗ #} <h2>Orders</h2> <h4>Recent</h4>
|
|
163
|
+
{# ✓ #} <h2>Orders</h2> <h3>Recent</h3>
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
The first heading in a file sets the baseline. A child template that starts at
|
|
167
|
+
`<h2>` (because `base.html` owns the `<h1>`) is fine.
|
|
168
|
+
|
|
169
|
+
#### RL302 `empty-heading`
|
|
170
|
+
|
|
171
|
+
```django
|
|
172
|
+
{# ✗ #} <h2><i class="icon-star"></i></h2>
|
|
173
|
+
{# ✓ #} <h2>{% trans "Favourites" %}</h2>
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
#### RL401 `form-label`
|
|
177
|
+
|
|
178
|
+
```django
|
|
179
|
+
{# ✗ #} <input type="email" name="email" placeholder="Email">
|
|
180
|
+
{# ✓ #} <label for="email">Email</label> <input type="email" id="email" name="email">
|
|
181
|
+
{# ✓ #} <label>Email <input type="email" name="email"></label>
|
|
182
|
+
{# ✓ #} <input type="search" name="q" aria-label="Search">
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Hidden, submit, reset, button and image inputs are not checked. Neither are
|
|
186
|
+
widgets whose attributes are rendered dynamically (`<input {{ widget.attrs }}>`).
|
|
187
|
+
|
|
188
|
+
#### RL501 `button-name`
|
|
189
|
+
|
|
190
|
+
```django
|
|
191
|
+
{# ✗ #} <button><i class="fa fa-trash"></i></button>
|
|
192
|
+
{# ✓ #} <button aria-label="{% trans 'Delete' %}"><i class="fa fa-trash" aria-hidden="true"></i></button>
|
|
193
|
+
{# ✓ #} <button><span class="visually-hidden">Delete</span><i class="fa fa-trash"></i></button>
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
#### RL502 `link-name`
|
|
197
|
+
|
|
198
|
+
```django
|
|
199
|
+
{# ✗ #} <a href="{% url 'cart' %}"><svg>…</svg></a>
|
|
200
|
+
{# ✓ #} <a href="{% url 'cart' %}"><svg><title>Cart</title>…</svg></a>
|
|
201
|
+
{# ✓ #} <a href="/"><img src="logo.png" alt="ACME home"></a>
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
#### RL601 `html-lang`
|
|
205
|
+
|
|
206
|
+
```django
|
|
207
|
+
{# ✗ #} <html>
|
|
208
|
+
{# ✓ #} <html lang="{{ LANGUAGE_CODE }}">
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
</details>
|
|
212
|
+
|
|
213
|
+
## How templates are handled
|
|
214
|
+
|
|
215
|
+
Before parsing, every template token is replaced by a placeholder of the same
|
|
216
|
+
length, so positions in the report always match your source:
|
|
217
|
+
|
|
218
|
+
| Template code | Treated as |
|
|
219
|
+
|--------------------------------------------------------------|---------------------------------|
|
|
220
|
+
| `{{ variable }}`, `{% trans %}`, `{% url %}`, `{% static %}` | Text that exists at runtime |
|
|
221
|
+
| `{% include %}`, `{% block %}`, custom tags | Unknown markup (rules back off) |
|
|
222
|
+
| `{% if %}`, `{% for %}`, `{% with %}`, ... | Nothing (control flow) |
|
|
223
|
+
| `{# ... #}`, `{% comment %}...{% endcomment %}` | Nothing |
|
|
224
|
+
|
|
225
|
+
Both branches of an `{% if %}` are checked, so a problem in either one is reported.
|
|
226
|
+
|
|
227
|
+
## Suppressing problems
|
|
228
|
+
|
|
229
|
+
```django
|
|
230
|
+
<img src="spacer.gif"> {# ramplint: ignore RL101 #}
|
|
231
|
+
|
|
232
|
+
{# ramplint: ignore img-alt, link-name #}
|
|
233
|
+
<a href="/"><img src="logo.png"></a>
|
|
234
|
+
|
|
235
|
+
{# ramplint: ignore-file #}
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
`ignore` applies to its own line and the next one. With no codes it silences
|
|
239
|
+
every rule. HTML comments work too: `<!-- ramplint: ignore RL201 -->`.
|
|
240
|
+
|
|
241
|
+
## Configuration
|
|
242
|
+
|
|
243
|
+
Add a `[tool.ramplint]` section to `pyproject.toml`. Command-line options take
|
|
244
|
+
precedence over it.
|
|
245
|
+
|
|
246
|
+
```toml
|
|
247
|
+
[tool.ramplint]
|
|
248
|
+
select = ["RL"] # default: all rules
|
|
249
|
+
ignore = ["RL301"]
|
|
250
|
+
exclude = ["*/admin/*", "templates/vendor/*"]
|
|
251
|
+
extensions = [".html", ".txt"]
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
## pre-commit
|
|
255
|
+
|
|
256
|
+
```yaml
|
|
257
|
+
# .pre-commit-config.yaml
|
|
258
|
+
repos:
|
|
259
|
+
- repo: https://github.com/iLLcruS/ramplint
|
|
260
|
+
rev: v0.1.0
|
|
261
|
+
hooks:
|
|
262
|
+
- id: ramplint
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
## GitHub Actions
|
|
266
|
+
|
|
267
|
+
When `GITHUB_ACTIONS=true`, ramplint switches to the `github` format and
|
|
268
|
+
problems appear as annotations right in the pull request diff.
|
|
269
|
+
|
|
270
|
+
```yaml
|
|
271
|
+
- run: pip install ramplint
|
|
272
|
+
- run: ramplint templates/
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
## Python API
|
|
276
|
+
|
|
277
|
+
```python
|
|
278
|
+
from ramplint import lint_source, select_rules
|
|
279
|
+
|
|
280
|
+
for problem in lint_source('<img src="a.png">', rules=select_rules(["RL1"])):
|
|
281
|
+
print(problem.line, problem.col, problem.code, problem.message)
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
## Limitations
|
|
285
|
+
|
|
286
|
+
ramplint is a static checker. It catches structural problems early and cheaply,
|
|
287
|
+
but it cannot judge colour contrast or focus order, or tell whether an `alt`
|
|
288
|
+
text is actually meaningful. Use it together with manual testing and a runtime
|
|
289
|
+
tool such as axe.
|
|
290
|
+
|
|
291
|
+
## Roadmap
|
|
292
|
+
|
|
293
|
+
- [ ] More rules: `<iframe title>`, duplicate `id`s, `autocomplete` on personal-data inputs
|
|
294
|
+
- [ ] `aria-*` attribute and role validation
|
|
295
|
+
- [ ] `--fix` for safe autofixes (e.g. `scope="col"` on header rows)
|
|
296
|
+
- [ ] SARIF output for GitHub code scanning
|
|
297
|
+
- [ ] Follow `{% extends %}` / `{% include %}` to check heading order across templates
|
|
298
|
+
|
|
299
|
+
## Contributing
|
|
300
|
+
|
|
301
|
+
Bug reports, especially about false positives, are very welcome.
|
|
302
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
303
|
+
|
|
304
|
+
## Feedback and support
|
|
305
|
+
|
|
306
|
+
Questions, ideas, or using ramplint in your project? Open an
|
|
307
|
+
[issue](https://github.com/iLLcruS/ramplint/issues) or email me at
|
|
308
|
+
[rostovskii.1020@gmail.com](mailto:rostovskii.1020@gmail.com).
|
|
309
|
+
|
|
310
|
+
ramplint is free and built in my spare time. If it saved you time, you can
|
|
311
|
+
buy me a coffee:
|
|
312
|
+
|
|
313
|
+
<a href="https://ko-fi.com/innerexcept"><img src="https://ko-fi.com/img/githubbutton_sm.svg" alt="Support me on Ko-fi" height="36"></a>
|
|
314
|
+
|
|
315
|
+
## License
|
|
316
|
+
|
|
317
|
+
[MIT](LICENSE) © Vladyslav Rostovskyi
|
ramplint-0.1.0/README.md
ADDED
|
@@ -0,0 +1,283 @@
|
|
|
1
|
+
<h1 align="center">ramplint</h1>
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<strong>Accessibility linter for Django and Jinja2 templates.</strong><br>
|
|
5
|
+
Catch WCAG problems in your <code>.html</code> templates before they reach production.
|
|
6
|
+
</p>
|
|
7
|
+
|
|
8
|
+
<p align="center">
|
|
9
|
+
<a href="https://github.com/iLLcruS/ramplint/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/iLLcruS/ramplint/actions/workflows/ci.yml/badge.svg"></a>
|
|
10
|
+
<a href="https://pypi.org/project/ramplint/"><img alt="PyPI" src="https://img.shields.io/pypi/v/ramplint.svg"></a>
|
|
11
|
+
<img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-blue.svg">
|
|
12
|
+
<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green.svg"></a>
|
|
13
|
+
<a href="https://ko-fi.com/innerexcept"><img alt="Support on Ko-fi" src="https://img.shields.io/badge/Ko--fi-support-72a4f2?logo=ko-fi&logoColor=white"></a>
|
|
14
|
+
</p>
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
Generic HTML linters choke on `{% if %}`, `{{ variables }}` and `{% include %}`,
|
|
19
|
+
and browser-based checkers only see the pages you remember to open.
|
|
20
|
+
**ramplint** reads your templates directly, understands the template syntax,
|
|
21
|
+
and reports problems with the exact line and column in the template source:
|
|
22
|
+
|
|
23
|
+
<p align="center">
|
|
24
|
+
<img src="docs/demo.svg" alt="Terminal output of ramplint reporting six accessibility problems in a Django product page template">
|
|
25
|
+
</p>
|
|
26
|
+
|
|
27
|
+
## Try it in 30 seconds
|
|
28
|
+
|
|
29
|
+
The repository ships with a small demo shop in [`examples/`](examples/): a
|
|
30
|
+
deliberately inaccessible set of Django templates that triggers every rule,
|
|
31
|
+
plus a file full of tricky-but-valid template patterns that must stay silent.
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
git clone https://github.com/iLLcruS/ramplint.git
|
|
35
|
+
cd ramplint
|
|
36
|
+
pip install .
|
|
37
|
+
ramplint examples/
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
```console
|
|
41
|
+
examples/templates/base.html:3:1: RL601 <html> is missing a lang attribute; add e.g. lang="en" or lang="{{ LANGUAGE_CODE }}" [html-lang]
|
|
42
|
+
examples/templates/base.html:11:5: RL502 <a> link has no accessible name; add text, an aria-label, or alt text on the image inside it [link-name]
|
|
43
|
+
examples/templates/base.html:11:45: RL101 <img> is missing an alt attribute (use alt="" for decorative images) [img-alt]
|
|
44
|
+
examples/templates/accounts/login.html:9:3: RL401 <input type="text"> has no associated label; add an id and a matching <label for>, or wrap it in a <label> (a placeholder is not a label) [form-label]
|
|
45
|
+
...
|
|
46
|
+
examples/templates/products/detail.html:28:3: RL101 <input type="image"> needs a non-empty alt attribute describing the action [img-alt]
|
|
47
|
+
|
|
48
|
+
Found 26 problems in 6 of 8 files.
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
See [`examples/README.md`](examples/README.md) for what each demo template contains.
|
|
52
|
+
|
|
53
|
+
## Highlights
|
|
54
|
+
|
|
55
|
+
- **Template-aware.** Django and Jinja2 tags, variables and comments are understood, not stripped blindly.
|
|
56
|
+
- **Low noise.** If something is only known at render time (`{% include %}`, `{{ widget.attrs }}`, `{% block %}`), ramplint assumes the best and stays quiet.
|
|
57
|
+
- **Zero dependencies.** Pure Python standard library (plus `tomli` on Python < 3.11).
|
|
58
|
+
- **Made for CI.** Exit codes, JSON output, GitHub Actions annotations and a pre-commit hook.
|
|
59
|
+
- **Fast.** No browser and no rendering. A whole project is checked in well under a second.
|
|
60
|
+
|
|
61
|
+
## Installation
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
pip install ramplint
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Usage
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
ramplint # lint every template under the current directory
|
|
71
|
+
ramplint templates/ shop/templates/base.html
|
|
72
|
+
ramplint --select RL1,RL5 # only image and control rules
|
|
73
|
+
ramplint --ignore heading-order # rules can be referenced by code or name
|
|
74
|
+
ramplint --format json # machine-readable output
|
|
75
|
+
ramplint --list-rules
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
By default ramplint looks at `.html`, `.htm`, `.jinja`, `.jinja2`, `.j2` and
|
|
79
|
+
`.djhtml` files and skips folders such as `node_modules`, `.venv`, `build` and `dist`.
|
|
80
|
+
Files passed explicitly are always checked, whatever their extension.
|
|
81
|
+
|
|
82
|
+
| Exit code | Meaning |
|
|
83
|
+
|-----------|------------------------------|
|
|
84
|
+
| `0` | No problems found |
|
|
85
|
+
| `1` | Problems found |
|
|
86
|
+
| `2` | Usage or configuration error |
|
|
87
|
+
|
|
88
|
+
## Rules
|
|
89
|
+
|
|
90
|
+
| Code | Name | What it checks | WCAG |
|
|
91
|
+
|---------|-----------------|------------------------------------------------------------------------------------------|------------------|
|
|
92
|
+
| `RL101` | `img-alt` | `<img>` has an `alt` attribute; `<input type="image">` and `<area>` have non-empty `alt` | 1.1.1 (A) |
|
|
93
|
+
| `RL201` | `table-header` | Data tables use real `<th>` header cells | 1.3.1 (A) |
|
|
94
|
+
| `RL301` | `heading-order` | Heading levels do not skip (`<h2>` → `<h4>`) | 1.3.1 (A) |
|
|
95
|
+
| `RL302` | `empty-heading` | Headings are not empty | 2.4.6 (AA) |
|
|
96
|
+
| `RL401` | `form-label` | `<input>`, `<select>` and `<textarea>` have an associated `<label>` | 1.3.1, 4.1.2 (A) |
|
|
97
|
+
| `RL501` | `button-name` | Buttons (including icon-only buttons) have an accessible name | 4.1.2 (A) |
|
|
98
|
+
| `RL502` | `link-name` | Links have an accessible name | 2.4.4, 4.1.2 (A) |
|
|
99
|
+
| `RL601` | `html-lang` | `<html>` declares the page language | 3.1.1 (A) |
|
|
100
|
+
|
|
101
|
+
<details>
|
|
102
|
+
<summary><strong>Examples for every rule</strong></summary>
|
|
103
|
+
|
|
104
|
+
#### RL101 `img-alt`
|
|
105
|
+
|
|
106
|
+
```django
|
|
107
|
+
{# ✗ #} <img src="{% static 'logo.png' %}">
|
|
108
|
+
{# ✓ #} <img src="{% static 'logo.png' %}" alt="ACME">
|
|
109
|
+
{# ✓ #} <img src="{% static 'divider.png' %}" alt=""> {# decorative #}
|
|
110
|
+
{# ✓ #} <img src="{{ product.image.url }}" alt="{{ product.name }}">
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
#### RL201 `table-header`
|
|
114
|
+
|
|
115
|
+
```django
|
|
116
|
+
{# ✗ #} <table><tr><td>Name</td><td>Price</td></tr>…</table>
|
|
117
|
+
{# ✓ #} <table><tr><th scope="col">Name</th><th scope="col">Price</th></tr>…</table>
|
|
118
|
+
{# ✓ #} <table role="presentation">…</table> {# layout table #}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
`role="columnheader"` on a `<td>` is not accepted. Use a real `<th>`.
|
|
122
|
+
Tables whose rows come from `{% include %}`, `{% block %}` or `{{ form.as_table }}`
|
|
123
|
+
are skipped because their content is not visible in the template.
|
|
124
|
+
|
|
125
|
+
#### RL301 `heading-order`
|
|
126
|
+
|
|
127
|
+
```django
|
|
128
|
+
{# ✗ #} <h2>Orders</h2> <h4>Recent</h4>
|
|
129
|
+
{# ✓ #} <h2>Orders</h2> <h3>Recent</h3>
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
The first heading in a file sets the baseline. A child template that starts at
|
|
133
|
+
`<h2>` (because `base.html` owns the `<h1>`) is fine.
|
|
134
|
+
|
|
135
|
+
#### RL302 `empty-heading`
|
|
136
|
+
|
|
137
|
+
```django
|
|
138
|
+
{# ✗ #} <h2><i class="icon-star"></i></h2>
|
|
139
|
+
{# ✓ #} <h2>{% trans "Favourites" %}</h2>
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
#### RL401 `form-label`
|
|
143
|
+
|
|
144
|
+
```django
|
|
145
|
+
{# ✗ #} <input type="email" name="email" placeholder="Email">
|
|
146
|
+
{# ✓ #} <label for="email">Email</label> <input type="email" id="email" name="email">
|
|
147
|
+
{# ✓ #} <label>Email <input type="email" name="email"></label>
|
|
148
|
+
{# ✓ #} <input type="search" name="q" aria-label="Search">
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Hidden, submit, reset, button and image inputs are not checked. Neither are
|
|
152
|
+
widgets whose attributes are rendered dynamically (`<input {{ widget.attrs }}>`).
|
|
153
|
+
|
|
154
|
+
#### RL501 `button-name`
|
|
155
|
+
|
|
156
|
+
```django
|
|
157
|
+
{# ✗ #} <button><i class="fa fa-trash"></i></button>
|
|
158
|
+
{# ✓ #} <button aria-label="{% trans 'Delete' %}"><i class="fa fa-trash" aria-hidden="true"></i></button>
|
|
159
|
+
{# ✓ #} <button><span class="visually-hidden">Delete</span><i class="fa fa-trash"></i></button>
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
#### RL502 `link-name`
|
|
163
|
+
|
|
164
|
+
```django
|
|
165
|
+
{# ✗ #} <a href="{% url 'cart' %}"><svg>…</svg></a>
|
|
166
|
+
{# ✓ #} <a href="{% url 'cart' %}"><svg><title>Cart</title>…</svg></a>
|
|
167
|
+
{# ✓ #} <a href="/"><img src="logo.png" alt="ACME home"></a>
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
#### RL601 `html-lang`
|
|
171
|
+
|
|
172
|
+
```django
|
|
173
|
+
{# ✗ #} <html>
|
|
174
|
+
{# ✓ #} <html lang="{{ LANGUAGE_CODE }}">
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
</details>
|
|
178
|
+
|
|
179
|
+
## How templates are handled
|
|
180
|
+
|
|
181
|
+
Before parsing, every template token is replaced by a placeholder of the same
|
|
182
|
+
length, so positions in the report always match your source:
|
|
183
|
+
|
|
184
|
+
| Template code | Treated as |
|
|
185
|
+
|--------------------------------------------------------------|---------------------------------|
|
|
186
|
+
| `{{ variable }}`, `{% trans %}`, `{% url %}`, `{% static %}` | Text that exists at runtime |
|
|
187
|
+
| `{% include %}`, `{% block %}`, custom tags | Unknown markup (rules back off) |
|
|
188
|
+
| `{% if %}`, `{% for %}`, `{% with %}`, ... | Nothing (control flow) |
|
|
189
|
+
| `{# ... #}`, `{% comment %}...{% endcomment %}` | Nothing |
|
|
190
|
+
|
|
191
|
+
Both branches of an `{% if %}` are checked, so a problem in either one is reported.
|
|
192
|
+
|
|
193
|
+
## Suppressing problems
|
|
194
|
+
|
|
195
|
+
```django
|
|
196
|
+
<img src="spacer.gif"> {# ramplint: ignore RL101 #}
|
|
197
|
+
|
|
198
|
+
{# ramplint: ignore img-alt, link-name #}
|
|
199
|
+
<a href="/"><img src="logo.png"></a>
|
|
200
|
+
|
|
201
|
+
{# ramplint: ignore-file #}
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
`ignore` applies to its own line and the next one. With no codes it silences
|
|
205
|
+
every rule. HTML comments work too: `<!-- ramplint: ignore RL201 -->`.
|
|
206
|
+
|
|
207
|
+
## Configuration
|
|
208
|
+
|
|
209
|
+
Add a `[tool.ramplint]` section to `pyproject.toml`. Command-line options take
|
|
210
|
+
precedence over it.
|
|
211
|
+
|
|
212
|
+
```toml
|
|
213
|
+
[tool.ramplint]
|
|
214
|
+
select = ["RL"] # default: all rules
|
|
215
|
+
ignore = ["RL301"]
|
|
216
|
+
exclude = ["*/admin/*", "templates/vendor/*"]
|
|
217
|
+
extensions = [".html", ".txt"]
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
## pre-commit
|
|
221
|
+
|
|
222
|
+
```yaml
|
|
223
|
+
# .pre-commit-config.yaml
|
|
224
|
+
repos:
|
|
225
|
+
- repo: https://github.com/iLLcruS/ramplint
|
|
226
|
+
rev: v0.1.0
|
|
227
|
+
hooks:
|
|
228
|
+
- id: ramplint
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
## GitHub Actions
|
|
232
|
+
|
|
233
|
+
When `GITHUB_ACTIONS=true`, ramplint switches to the `github` format and
|
|
234
|
+
problems appear as annotations right in the pull request diff.
|
|
235
|
+
|
|
236
|
+
```yaml
|
|
237
|
+
- run: pip install ramplint
|
|
238
|
+
- run: ramplint templates/
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
## Python API
|
|
242
|
+
|
|
243
|
+
```python
|
|
244
|
+
from ramplint import lint_source, select_rules
|
|
245
|
+
|
|
246
|
+
for problem in lint_source('<img src="a.png">', rules=select_rules(["RL1"])):
|
|
247
|
+
print(problem.line, problem.col, problem.code, problem.message)
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
## Limitations
|
|
251
|
+
|
|
252
|
+
ramplint is a static checker. It catches structural problems early and cheaply,
|
|
253
|
+
but it cannot judge colour contrast or focus order, or tell whether an `alt`
|
|
254
|
+
text is actually meaningful. Use it together with manual testing and a runtime
|
|
255
|
+
tool such as axe.
|
|
256
|
+
|
|
257
|
+
## Roadmap
|
|
258
|
+
|
|
259
|
+
- [ ] More rules: `<iframe title>`, duplicate `id`s, `autocomplete` on personal-data inputs
|
|
260
|
+
- [ ] `aria-*` attribute and role validation
|
|
261
|
+
- [ ] `--fix` for safe autofixes (e.g. `scope="col"` on header rows)
|
|
262
|
+
- [ ] SARIF output for GitHub code scanning
|
|
263
|
+
- [ ] Follow `{% extends %}` / `{% include %}` to check heading order across templates
|
|
264
|
+
|
|
265
|
+
## Contributing
|
|
266
|
+
|
|
267
|
+
Bug reports, especially about false positives, are very welcome.
|
|
268
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
269
|
+
|
|
270
|
+
## Feedback and support
|
|
271
|
+
|
|
272
|
+
Questions, ideas, or using ramplint in your project? Open an
|
|
273
|
+
[issue](https://github.com/iLLcruS/ramplint/issues) or email me at
|
|
274
|
+
[rostovskii.1020@gmail.com](mailto:rostovskii.1020@gmail.com).
|
|
275
|
+
|
|
276
|
+
ramplint is free and built in my spare time. If it saved you time, you can
|
|
277
|
+
buy me a coffee:
|
|
278
|
+
|
|
279
|
+
<a href="https://ko-fi.com/innerexcept"><img src="https://ko-fi.com/img/githubbutton_sm.svg" alt="Support me on Ko-fi" height="36"></a>
|
|
280
|
+
|
|
281
|
+
## License
|
|
282
|
+
|
|
283
|
+
[MIT](LICENSE) © Vladyslav Rostovskyi
|