Classes
BlockMetadata
12
▼
Metadata about a template block, inferred from static analysis.
**All fields are conservative esti…
BlockMetadata
12
▼
Metadata about a template block, inferred from static analysis.
All fields are conservative estimates:
depends_onmay include unused paths (over-approximation)is_puredefaults to "unknown" when uncertaininferred_roleis heuristic, not semantic truth
Thread-safe: Immutable after creation.
Attributes
| Name | Type | Description |
|---|---|---|
name |
str
|
Block identifier (e.g., "nav", "content", "sidebar") |
emits_html |
bool
|
True if block produces any output. Used to detect empty blocks. |
emits_landmarks |
frozenset[str]
|
HTML5 landmark elements emitted (nav, main, header, etc.). Detected from static HTML in Data nodes. |
inferred_role |
Literal['navigation', 'content', 'sidebar', 'header', 'footer', 'unknown']
|
Heuristic classification based on name and landmarks. One of: "navigation", "content", "sidebar", "header", "footer", "unknown" |
depends_on |
frozenset[str]
|
Context paths this block may access (conservative superset). |
is_pure |
Literal['pure', 'impure', 'unknown']
|
Whether block output is deterministic for same inputs. - "pure": Deterministic, safe to cache - "impure": Uses random/shuffle/etc, must re-render - "unknown": Cannot determine, treat as potentially impure |
cache_scope |
Literal['none', 'page', 'site', 'unknown']
|
Recommended caching granularity. - "site": Cache once per site build (no page-specific deps) - "page": Cache per page (has page-specific deps) - "none": Cannot cache (impure) - "unknown": Cannot determine |
block_hash |
str
|
— |
Example |
— |
frozenset({"page.title", "site.pages", "config.theme"}) |
Methods
is_cacheable
0
bool
▼
Check if this block can be safely cached.
**Returns True if:**
- Block is pure…
is_cacheable
0
bool
▼
def is_cacheable(self) -> bool
Check if this block can be safely cached.
Returns True if:
- Block is pure (deterministic)
- Cache scope is not "none"
Returns
bool
True if block can be cached, False otherwise.
depends_on_page
0
bool
▼
Check if block depends on page-specific context.
depends_on_page
0
bool
▼
def depends_on_page(self) -> bool
Returns
bool
True if any dependency starts with common page prefixes.
depends_on_site
0
bool
▼
Check if block depends on site-wide context.
depends_on_site
0
bool
▼
def depends_on_site(self) -> bool
Returns
bool
True if any dependency starts with common site prefixes.
TemplateMetadata
9
▼
Metadata about a complete template.
Aggregates block metadata and tracks template-level informatio…
TemplateMetadata
9
▼
Metadata about a complete template.
Aggregates block metadata and tracks template-level information like inheritance and top-level dependencies.
Attributes
| Name | Type | Description |
|---|---|---|
name |
str | None
|
Template identifier (e.g., "page.html") |
extends |
str | None
|
Parent template name from {% extends %}, or None. |
blocks |
dict[str, BlockMetadata]
|
Mapping of block name → BlockMetadata. All blocks defined in this template. |
top_level_depends_on |
frozenset[str]
|
Context paths used outside blocks. Captures dependencies from: - Code before/after blocks - Dynamic extends expressions - Template-level set/let statements |
Example |
— |
"base.html" |
Methods
all_dependencies
0
frozenset[str]
▼
Return all context paths used anywhere in template.
Combines top-level depende…
all_dependencies
0
frozenset[str]
▼
def all_dependencies(self) -> frozenset[str]
Return all context paths used anywhere in template.
Combines top-level dependencies with all block dependencies.
Returns
frozenset[str]
Frozen set of all context paths.
get_block
1
BlockMetadata | None
▼
Get metadata for a specific block.
get_block
1
BlockMetadata | None
▼
def get_block(self, name: str) -> BlockMetadata | None
Parameters
| Name | Type | Description |
|---|---|---|
name |
— |
Block name to look up. |
Returns
BlockMetadata | None
BlockMetadata if found, None otherwise.
cacheable_blocks
0
list[BlockMetadata]
▼
Return all blocks that can be safely cached.
cacheable_blocks
0
list[BlockMetadata]
▼
def cacheable_blocks(self) -> list[BlockMetadata]
Returns
list[BlockMetadata]
List of BlockMetadata where is_cacheable() is True.
site_cacheable_blocks
0
list[BlockMetadata]
▼
Return blocks that can be cached site-wide.
site_cacheable_blocks
0
list[BlockMetadata]
▼
def site_cacheable_blocks(self) -> list[BlockMetadata]
Returns
list[BlockMetadata]
List of BlockMetadata where cache_scope is "site".
CallValidation
7
▼
Result of validating a single call site against a function definition.
Produced by ``BlockAnalyzer…
CallValidation
7
▼
Result of validating a single call site against a function definition.
Produced byBlockAnalyzer.validate_calls() when a FuncCalltargets
a{% def %}in the same compilation unit.
Attributes
| Name | Type | Description |
|---|---|---|
def_name |
str
|
Name of the called |
lineno |
int
|
Source line of the call site. |
col_offset |
int
|
Source column of the call site. |
unknown_params |
tuple[str, ...]
|
Keyword argument names not in the definition's parameters. |
missing_required |
tuple[str, ...]
|
Required parameters (no default) not provided by the call. |
duplicate_params |
tuple[str, ...]
|
Keyword argument names supplied more than once. |
Methods
is_valid
0
bool
▼
Return True if no issues were found.
property
is_valid
0
bool
▼
def is_valid(self) -> bool
Returns
bool
TemplateStructureManifest
5
▼
Lightweight template structure for schedulers and dependency planners.
TemplateStructureManifest
5
▼
Lightweight template structure for schedulers and dependency planners.
Attributes
| Name | Type | Description |
|---|---|---|
name |
str | None
|
Template name. |
extends |
str | None
|
Parent template name from |
block_names |
tuple[str, ...]
|
Ordered block names in this template. |
block_hashes |
dict[str, str]
|
Deterministic per-block structural hashes. |
dependencies |
frozenset[str]
|
Top-level + block context dependencies. |