Classes
BlockMetadata
11
▼
Metadata about a template block, inferred from static analysis.
**All fields are conservative esti…
BlockMetadata
11
▼
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 |
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".