danhanson/tree-sitter-django
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add static

Browse Source
This commit is contained in:
danhanson committed 2026-09-07 14:55:05 -05:00
1 parent eb81b73104
commit c0e7b4697d
8 files changed
+24033 -21222
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

CLAUDE.md
+31 -1
View File
@@ -95,6 +95,28 @@ identifier and reached the fallback, losing the arity check for all 20 filters t
`FILTERS_WITHOUT_ARGUMENT` / `FILTERS_WITH_ARGUMENT` / `FILTERS_WITH_OPTIONAL_ARGUMENT` carry that arity,
which Django itself enforces while it parses the template ("add requires 2 arguments, 1 provided").
### First-party libraries
Django ships `i18n`, `l10n`, `static`, `cache` and `tz` as libraries rather than builtins. Their tags are
modelled as ordinary tags (so far: `static`), and the grammar **never requires the `{% load %}`**, because
an engine can preload a library through `OPTIONS: {"builtins": [...]}`, which makes `{% static "a" %}` valid
with no load at all.
Whether a load is present is a question about the order of nodes, not about how the template parses, so it
belongs in a tool. `queries/libraries.scm` supplies the halves — `@library.<name>` on each tag, and
`@load.library` / `@load.name` on the loads — and the tool does the join, because tree-sitter queries have
no ordering predicate to express it. What such a tool needs to know about Django's behaviour:
- Loading is **positional**: `{% trans "x" %}{% load i18n %}` is an error, because the parser adds to its
tag dict as it walks tokens.
- Loading is **per file**: a `{% load %}` does not reach a template that `{% extends %}` or `{% include %}`
this one.
- `{% load trans from i18n %}` makes only `trans` available, not the rest of the library.
Modelling a library name makes it keyword-extracted, so it no longer reaches `custom_tag`. A project that
registers its own tag under one of these names and a different signature therefore gets a parse error. That
is accepted: these names are common enough that shadowing them is the mistake.
### External scanner (`src/scanner.c`)
Nine external tokens, for the constraints a context-free grammar cannot express:
@@ -117,7 +139,8 @@ do not, and belong in a linter instead.
`queries/highlights.scm` lists tag and filter names explicitly, so adding either to the grammar means
adding it there too; filter names appear there without their colon. A name the grammar does not know is
captured through its field instead (`(filter name: (identifier))`, `(custom_tag tag: (identifier))`). `queries/locals.scm` relies on the `variable:` field to tell a binding from a
captured through its field instead (`(filter name: (identifier))`, `(custom_tag tag: (identifier))`). `queries/libraries.scm` is not a query editors run themselves; it is data for a linter, and every tag
or filter added from a library belongs in it. `queries/locals.scm` relies on the `variable:` field to tell a binding from a
reference — another reason to keep `asVariable` uniform.
## Testing
@@ -141,6 +164,9 @@ documentation or memory. Both checks are worth repeating whenever tags, filters
`register.filters` against `grammar.js`. For filters also compare argument arity via
`inspect.signature`, ignoring the framework-injected `autoescape` parameter, which is never written in a
template. Note `querystring` and `csp_nonce_attr` register as `simple_tag`, not `@register.tag`.
- **Library contents** — `django.templatetags.<name>.register` gives a library's `tags` and `filters`.
All of them are registered with `@register.tag`, so `inspect.signature` only reports `(parser, token)`
and a signature has to come from the differential below or from reading the compile function.
- **Syntax differential** — run candidate snippets through `django.template.Template()` and through
`tree-sitter parse`, and compare accept/reject. This is how the `simple_tag` argument rules, the `_()`
literal, and the filter-pipe spacing were pinned down.
@@ -164,5 +190,9 @@ documentation or memory. Both checks are worth repeating whenever tags, filters
token and may parse anything, so `{% mytag <<>> %}` is rejected here and not by Django.
- A library may override a builtin (`Parser.add_library` is `self.filters.update(...)`), so a project that
redefines `length` with a different arity gets a false error here.
- Django's `static` tags ignore what follows their argument: `StaticNode.handle_token` looks for `as` two
bits from the end, so `{% static "a" junk %}` and `{% static "a" as u v %}` are accepted there and
rejected here, and `PrefixNode.handle_token` raises `IndexError` rather than `TemplateSyntaxError` on
`{% get_static_prefix as %}`.
- `partial`/`partialdef` are Django builtins as of Django 6; `elif`/`else`/`empty` are modelled as parts of
their enclosing tag rather than as separate tags.
grammar.js
+8
View File
@@ -347,6 +347,8 @@ const django = grammar({
$.filter_group,
$.firstof,
$.for_group,
$.get_media_prefix,
$.get_static_prefix,
$.if_group,
$.ifchanged_group,
$.include,
@@ -359,6 +361,7 @@ const django = grammar({
$.regroup,
$.reset_cycle,
$.spaceless_group,
$.static,
$.template_tag_block,
$.url_block,
$.verbatim_group,
@@ -477,6 +480,9 @@ const django = grammar({
optional(seq(block("empty"), optional($.template))),
block("endfor"),
),
get_media_prefix: ($) => block("get_media_prefix", optional(asVariable($))),
get_static_prefix: ($) =>
block("get_static_prefix", optional(asVariable($))),
if_group: ($) =>
seq(
block("if", part($.predicate)),
@@ -529,6 +535,8 @@ const django = grammar({
reset_cycle: ($) => block("resetcycle", optional(part($.identifier))),
spaceless_group: ($) =>
seq(block("spaceless"), optional($.template), block("endspaceless")),
static: ($) =>
block("static", part($.filtered_value), optional(asVariable($))),
template_tag_block: ($) =>
block(
"templatetag",
queries/highlights.scm
+3
View File
@@ -66,6 +66,8 @@ tag: [
("for")
("empty")
("endfor")
("get_media_prefix")
("get_static_prefix")
("if")
("elif")
("else")
@@ -84,6 +86,7 @@ tag: [
("resetcycle")
("spaceless")
("endspaceless")
("static")
("templatetag")
("url")
("verbatim")
queries/libraries.scm
+25
View File
@@ -0,0 +1,25 @@
; Which library a tag or filter is registered in.
;
; The grammar accepts these whether or not a "{% load %}" precedes them: an
; engine may preload a library through its "builtins" option, and Django
; resolves a name against the libraries loaded *so far*, which is a question
; about the order of nodes rather than about how the template parses. A tool
; that wants to report a missing load can run this query and compare positions
; itself, and should skip the check for a library the engine preloads.
;
; Loading is per file and positional: "{% load %}" does not reach a template
; that extends or includes this one, and a tag written before the load is an
; error even though the load is in the same file.
[
(static)
(get_static_prefix)
(get_media_prefix)] @library.static
; "{% load static %}" makes every name in the library available; "{% load
; static from staticfiles %}" makes only the names listed available.
(load
(library) @load.library)
(load
(identifier) @load.name)
src/grammar.json
+274
View File
@@ -582,6 +582,14 @@
"type": "SYMBOL",
"name": "for_group"
},
{
"type": "SYMBOL",
"name": "get_media_prefix"
},
{
"type": "SYMBOL",
"name": "get_static_prefix"
},
{
"type": "SYMBOL",
"name": "if_group"
@@ -630,6 +638,10 @@
"type": "SYMBOL",
"name": "spaceless_group"
},
{
"type": "SYMBOL",
"name": "static"
},
{
"type": "SYMBOL",
"name": "template_tag_block"
@@ -2413,6 +2425,172 @@
}
]
},
"get_media_prefix": {
"type": "SEQ",
"members": [
{
"type": "STRING",
"value": "{%"
},
{
"type": "CHOICE",
"members": [
{
"type": "PATTERN",
"value": "[ \\t\\r\\n]+"
},
{
"type": "BLANK"
}
]
},
{
"type": "FIELD",
"name": "tag",
"content": {
"type": "STRING",
"value": "get_media_prefix"
}
},
{
"type": "CHOICE",
"members": [
{
"type": "SEQ",
"members": [
{
"type": "PATTERN",
"value": "[ \\t\\r\\n]+"
},
{
"type": "SEQ",
"members": [
{
"type": "STRING",
"value": "as"
},
{
"type": "PATTERN",
"value": "[ \\t\\r\\n]+"
},
{
"type": "FIELD",
"name": "variable",
"content": {
"type": "SYMBOL",
"name": "identifier"
}
}
]
}
]
},
{
"type": "BLANK"
}
]
},
{
"type": "CHOICE",
"members": [
{
"type": "PATTERN",
"value": "[ \\t\\r\\n]+"
},
{
"type": "BLANK"
}
]
},
{
"type": "STRING",
"value": "%}"
}
]
},
"get_static_prefix": {
"type": "SEQ",
"members": [
{
"type": "STRING",
"value": "{%"
},
{
"type": "CHOICE",
"members": [
{
"type": "PATTERN",
"value": "[ \\t\\r\\n]+"
},
{
"type": "BLANK"
}
]
},
{
"type": "FIELD",
"name": "tag",
"content": {
"type": "STRING",
"value": "get_static_prefix"
}
},
{
"type": "CHOICE",
"members": [
{
"type": "SEQ",
"members": [
{
"type": "PATTERN",
"value": "[ \\t\\r\\n]+"
},
{
"type": "SEQ",
"members": [
{
"type": "STRING",
"value": "as"
},
{
"type": "PATTERN",
"value": "[ \\t\\r\\n]+"
},
{
"type": "FIELD",
"name": "variable",
"content": {
"type": "SYMBOL",
"name": "identifier"
}
}
]
}
]
},
{
"type": "BLANK"
}
]
},
{
"type": "CHOICE",
"members": [
{
"type": "PATTERN",
"value": "[ \\t\\r\\n]+"
},
{
"type": "BLANK"
}
]
},
{
"type": "STRING",
"value": "%}"
}
]
},
"if_group": {
"type": "SEQ",
"members": [
@@ -3823,6 +4001,102 @@
}
]
},
"static": {
"type": "SEQ",
"members": [
{
"type": "STRING",
"value": "{%"
},
{
"type": "CHOICE",
"members": [
{
"type": "PATTERN",
"value": "[ \\t\\r\\n]+"
},
{
"type": "BLANK"
}
]
},
{
"type": "FIELD",
"name": "tag",
"content": {
"type": "STRING",
"value": "static"
}
},
{
"type": "SEQ",
"members": [
{
"type": "PATTERN",
"value": "[ \\t\\r\\n]+"
},
{
"type": "SYMBOL",
"name": "filtered_value"
}
]
},
{
"type": "CHOICE",
"members": [
{
"type": "SEQ",
"members": [
{
"type": "PATTERN",
"value": "[ \\t\\r\\n]+"
},
{
"type": "SEQ",
"members": [
{
"type": "STRING",
"value": "as"
},
{
"type": "PATTERN",
"value": "[ \\t\\r\\n]+"
},
{
"type": "FIELD",
"name": "variable",
"content": {
"type": "SYMBOL",
"name": "identifier"
}
}
]
}
]
},
{
"type": "BLANK"
}
]
},
{
"type": "CHOICE",
"members": [
{
"type": "PATTERN",
"value": "[ \\t\\r\\n]+"
},
{
"type": "BLANK"
}
]
},
{
"type": "STRING",
"value": "%}"
}
]
},
"template_tag_block": {
"type": "SEQ",
"members": [
src/node-types.json
+112
View File
@@ -51,6 +51,14 @@
"type": "for_group",
"named": true
},
{
"type": "get_media_prefix",
"named": true
},
{
"type": "get_static_prefix",
"named": true
},
{
"type": "if_group",
"named": true
@@ -99,6 +107,10 @@
"type": "spaceless_group",
"named": true
},
{
"type": "static",
"named": true
},
{
"type": "template_tag_block",
"named": true
@@ -854,6 +866,58 @@
]
}
},
{
"type": "get_media_prefix",
"named": true,
"fields": {
"tag": {
"multiple": false,
"required": true,
"types": [
{
"type": "get_media_prefix",
"named": false
}
]
},
"variable": {
"multiple": false,
"required": false,
"types": [
{
"type": "identifier",
"named": true
}
]
}
}
},
{
"type": "get_static_prefix",
"named": true,
"fields": {
"tag": {
"multiple": false,
"required": true,
"types": [
{
"type": "get_static_prefix",
"named": false
}
]
},
"variable": {
"multiple": false,
"required": false,
"types": [
{
"type": "identifier",
"named": true
}
]
}
}
},
{
"type": "if_group",
"named": true,
@@ -1305,6 +1369,42 @@
]
}
},
{
"type": "static",
"named": true,
"fields": {
"tag": {
"multiple": false,
"required": true,
"types": [
{
"type": "static",
"named": false
}
]
},
"variable": {
"multiple": false,
"required": false,
"types": [
{
"type": "identifier",
"named": true
}
]
}
},
"children": {
"multiple": false,
"required": true,
"types": [
{
"type": "filtered_value",
"named": true
}
]
}
},
{
"type": "template",
"named": true,
@@ -1856,6 +1956,14 @@
"type": "get_digit",
"named": false
},
{
"type": "get_media_prefix",
"named": false
},
{
"type": "get_static_prefix",
"named": false
},
{
"type": "identifier",
"named": true
@@ -2072,6 +2180,10 @@
"type": "spaceless",
"named": false
},
{
"type": "static",
"named": false
},
{
"type": "string",
"named": true
src/parser.c
+23399 -21221
View File
File diff suppressed because it is too large. Load diff
test/corpus/static.txt
+181
View File
@@ -0,0 +1,181 @@
==================
Static
==================
{% static "a.css" %}
---
(template
(content)
(static
(filtered_value
(value
(literal
(string)))))
(content))
==================
Static With A Variable Path
==================
{% static path %}
---
(template
(content)
(static
(filtered_value
(value
(variable_attribute
(identifier)))))
(content))
==================
Static With A Filtered Path
==================
{% static "a.css"|upper %}
---
(template
(content)
(static
(filtered_value
(value
(literal
(string)))
(filter_expression
(filter))))
(content))
==================
Static With As
==================
{% static "a.css" as url %}
---
(template
(content)
(static
(filtered_value
(value
(literal
(string))))
variable: (identifier))
(content))
==================
Static Without A Path
:error
==================
{% static %}
---
==================
Static With A Second Path
:error
==================
{% static "a.css" "b.css" %}
---
==================
Static With Anything After As
:error
==================
{% static "a.css" as url junk %}
---
==================
Get Static Prefix
==================
{% get_static_prefix %}
---
(template
(content)
(get_static_prefix)
(content))
==================
Get Static Prefix With As
==================
{% get_static_prefix as prefix %}
---
(template
(content)
(get_static_prefix
variable: (identifier))
(content))
==================
Get Media Prefix With As
==================
{% get_media_prefix as prefix %}
---
(template
(content)
(get_media_prefix
variable: (identifier))
(content))
==================
Get Static Prefix Without As
:error
==================
{% get_static_prefix prefix %}
---
==================
Get Static Prefix Without A Variable
:error
==================
{% get_static_prefix as %}
---
==================
Load Names The Library, Not The Tag
==================
{% load static %}{% static "a.css" %}
---
(template
(content)
(load
(library
(identifier)))
(static
(filtered_value
(value
(literal
(string)))))
(content))