AST introspection for{% def %}macros — internal.
Wrapskida.lexer + kida.parserto extract per-macro parameter
metadata without compiling the template (so no chirp-ui filter stubs are
required at manifest-build time).
Used bychirp_ui.manifestto project macro Python signatures into the
agent-groundable manifest. Seedocs/plans/done/PLAN-agent-grounding-depth.mdand
docs/decisions/manifest-signature-extraction.md.
_macro_introspect
| Name | Type | Default | Description |
|---|---|---|---|
type
|
|
— | |
qualified_name
|
|
— | |
element_type
|
|
— | |
description
|
|
— | |
source_file
|
|
— | |
line_number
|
|
— | |
is_autodoc
|
|
— | |
autodoc_element
|
|
— | |
_autodoc_template
|
|
— | |
_autodoc_url_path
|
|
— | |
_autodoc_page_type
|
|
— | |
title
|
|
— | |
doc_content_hash
|
|
— |
Symbols on this page
Single{% def %}parameter, derived from the AST.
has_defaultfollows Python's trailing-defaults convention: kida's
Def node parallels defaultsto the last N of …
Per-macro introspection result.
slots is the tuple of {% slot name %}placeholders found in the macro body, in declaration order, deduplicated (a slot…
Return{macro_name: MacroInfo} for every {% def %}in the template.
Cached. Returns{}if the template file is missing or contains no defs.…
Yield public slot names reachable fromnode without crossing a nested Def.
chirp-ui currently has no nested defs (verified at Sprint 2), so…
Returnmacro_name → yielded slot namesattributed by source line.
The installed kida AST exposesSlotplaceholders but not a public
Yieldnode, so…
Return the leading{#- chirp-ui: ... -#} doc-block text, or "".
One doc-block per file, covering the file's entire set of macros —…
ParamInfo
class
Single{% def %}parameter, derived from the AST.
has_defaultfollows Python's trailing-defaults convention: kida's
Def node parallels defaults to the last N of params.
MacroInfo
class
Per-macro introspection result.
slots is the tuple of {% slot name %}placeholders found in the
macro body, in declaration order, deduplicated (a slot rendered twice
appears once). The unnamed default slot is normalized from kida's
"default" to "" to match ComponentDescriptor.slotsconvention.
yielded_slots is the tuple of {% yield %} / {% yield name %}
caller slots accepted by composite macros and forwarded into child calls.
macros_in_template
function
def macros_in_template(template_name: str) -> dict[str, MacroInfo]Return{macro_name: MacroInfo} for every {% def %}in the template.
Cached. Returns{}if the template file is missing or contains no defs.
Template name is relative tosrc/chirp_ui/templates/chirpui/.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
template_name
|
str
|
— |
_walk_slot_names
function
def _walk_slot_names(node: Node) -> Iterator[str]Yield public slot names reachable fromnode without crossing a nested Def.
chirp-ui currently has no nested defs (verified at Sprint 2), so this is defensive only — keeps slot ownership per-macro if that ever changes.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
node
|
Node
|
— |
_yielded_slots_by_macro
function
def _yielded_slots_by_macro(source: str, defs: list[Def]) -> dict[str, tuple[str, ...]]Returnmacro_name → yielded slot namesattributed by source line.
The installed kida AST exposesSlotplaceholders but not a public
Yieldnode, so composite forwarded slots are found from the raw source
and attributed to the nearest preceding{% def %}line. chirp-ui does
not use nested defs, which keeps the ownership rule straightforward.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
source
|
str
|
— | |
defs
|
list[Def]
|
— |
description_from_template
function
def description_from_template(template_name: str) -> strReturn the leading{#- chirp-ui: ... -#} doc-block text, or "".
One doc-block per file, covering the file's entire set of macros — verified
at Sprint 4 across all 195 chirp-ui templates. The block must appear before
any{% def %} or {% from %}statement (the parser scans only the
first ~2 KB to honor that invariant cheaply).
Whitespace inside the block is preserved except for a single leading / trailing strip — so multi-line usage examples keep their shape. Inner indentation is left alone; downstream renderers (COMPONENT-OPTIONS generator, etc.) can post-process as needed.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
template_name
|
str
|
— |
View source · /home/runner/work/chirp-ui/chirp-ui/site/../src/chirp_ui/_macro_introspect.py:1