Template analysis

A zero-based line and UTF-16 character position used by LSP clients.

Attributes

• line int - Zero-based source line.
• character int - Zero-based UTF-16 code-unit offset on that line.

line: int

character: int

A half-open LSP range in a source document.

Attributes

• start LspPosition - Inclusive start position.
• end LspPosition - Exclusive end position.

start: LspPosition

end: LspPosition

Conservative direct literal and static file component assets.

regions: tuple[PythonComponentAssetRegion, ...]

files: tuple[PythonComponentAssetFile, ...]

notices: tuple[PythonComponentAssetNotice, ...]

valid_python: bool

One statically proven direct component asset-file declaration.

component_name: str

kind: PythonComponentAssetKind

path: str

One validated, atomic Python component-asset formatting result.

Attributes

• source str - Complete formatted Python source.
• changed_component_assets tuple[tuple[str, PythonComponentAssetKind], ...] - Changed (component_name, kind) pairs.
• notices tuple[PythonComponentAssetNotice, ...] - Assets left unchanged with an explicit reason.
• providers tuple[str, ...] - Sorted provider identities reported by accepted results.

source: str

changed_component_assets: tuple[tuple[str, PythonComponentAssetKind], ...]

notices: tuple[PythonComponentAssetNotice, ...]

providers: tuple[str, ...]

A direct Citry component asset selected for formatting.

A component-specific reason why one asset was skipped or unchanged.

component_name: str

kind: PythonComponentAssetKind

code: str

message: str

request_id: str | None

An immutable Python-source plan awaiting JavaScript and CSS providers.

A plan is bound to the complete source passed to prepare_python_component_assets. Provider work may happen asynchronously before the caller passes every reply to finish_python_component_assets.

Attributes

• id str - Stable source and selection identity echoed by provider results.
• source str - Complete original Python source.
• requests tuple[PythonComponentAssetRequest, ...] - Standalone JavaScript and CSS provider requests.
• notices tuple[PythonComponentAssetNotice, ...] - Non-fatal embedded regions that could not be delegated.

id: str

source: str

requests: tuple[PythonComponentAssetRequest, ...]

notices: tuple[PythonComponentAssetNotice, ...]

One definite direct literal asset on a Citry component class.

Attributes

• component_name str - Name of the declaring component class.
• kind PythonComponentAssetKind - Component attribute represented by this region.
• source_map PythonTemplateSourceMap - Mapping between the decoded asset and its Python literal.

component_name: str

kind: PythonComponentAssetKind

source_map: PythonTemplateSourceMap

One standalone JavaScript or CSS document offered to a provider.

Attributes

• plan_id str - Identity of the source-bound Python formatting plan.
• id str - Identity of this request within the plan.
• component_name str - Name of the declaring component class.
• asset_kind PythonComponentAssetKind - Component asset containing this provider region.
• language EmbeddedLanguage - Standalone language expected by the provider.
• region_kind EmbeddedRegionKind | None - Template body kind, or None for a direct js or css literal.
• source str - Decoded provider-owned source.
• virtual_source str - Standalone source to send to the provider.

plan_id: str

id: str

component_name: str

asset_kind: PythonComponentAssetKind

language: EmbeddedLanguage

region_kind: EmbeddedRegionKind | None

source: str

virtual_source: str

Conservative inline template regions and non-parser notices.

regions: tuple[PythonTemplateRegion, ...]

notices: tuple[PythonTemplateNotice, ...]

valid_python: bool

A formatting refusal that never exposes a partial Python candidate.

Attributes

• code str - Stable formatter failure code.
• notices tuple[PythonTemplateNotice, ...] - Component-specific reasons relevant to the refusal.
• range tuple[int, int] | None - Optional absolute half-open Python string-offset range.
• diagnostic object | None - Optional nested parser diagnostic. Template parser diagnostic offsets remain relative to the decoded template.

code: str

notices: tuple[PythonTemplateNotice, ...]

range: tuple[int, int] | None

diagnostic: object | None

One validated, atomic Python template-formatting result.

source: str

changed_component_names: tuple[str, ...]

notices: tuple[PythonTemplateNotice, ...]

One definite component template skipped for an explicit reason.

component_name: str

message: str

One definite direct literal template on a Citry component class.

component_name: str

source_map: PythonTemplateSourceMap

Map Citry parser byte ranges back into an authored Python document.

The map decodes plain, raw, and Unicode string literals, including implicit literal concatenation. Parser indices address the decoded template as UTF-8 bytes. Returned positions address the Python document with the zero-based UTF-16 coordinates required by LSP.

Build a map with from_ast for valid Python or from_coordinates for a literal region found by a conservative lexical scanner.

Attributes

• template_source str - Decoded, common-indent-normalized Citry template text passed to the parser.

template_source: str

from_ast(host_source: str, node: Constant) -> PythonTemplateSourceMap

from_coordinates(host_source: str, lineno: int, col_offset: int, end_lineno: int | None = None, end_col_offset: int | None = None, accept_incomplete: bool = False) -> PythonTemplateSourceMap

map_range(start_index: int, end_index: int) -> LspRange

range_is_unambiguous(start_index: int, end_index: int) -> bool

parser_index_at(position: LspPosition) -> int | None

A complete, immutable snapshot of one Citry component registry.

Attributes

• component_names frozenset[str] - Normalized registered names without the c- tag prefix. The set includes aliases and built-in component names.
• lint TemplateLintInfo - Application lint settings and known global variables.
• component_lint Mapping[str, TemplateLintInfo] - Effective lint settings and known variables keyed by stable component definition ID.

component_names: frozenset[str]

lint: TemplateLintInfo

component_lint: Mapping[str, TemplateLintInfo]

parse_template(source: str) -> Template

to_dict() -> dict[str, object]

from_dict(value: object) -> TemplateAnalysis

Describe one proven component namespace used by a physical template.

Attributes

• known_names frozenset[str] - Root names available to this component's template.
• namespace_policy Literal['closed', 'allow-extra', 'unknown'] - Whether those names exhaust normalized template data.
• rule_unknown_template_variable Literal['ignore', 'warning', 'error'] - Configured severity for undeclared free roots.

known_names: frozenset[str]

namespace_policy: Literal['closed', 'allow-extra', 'unknown']

rule_unknown_template_variable: Literal['ignore', 'warning', 'error']

Report one parser-proven free root missing from a known namespace.

name: str

message: str

code: str

severity: Literal['warning', 'error']

start_index: int

end_index: int

line: int

column: int

Carry one component's effective lint rule and known global variables.

rule_unknown_template_variable: LintSeverity

template_variables: tuple[TemplateVariableInfo, ...]

rule_i18n_missing_param_type: LintSeverity

rule_unknown_alpine_variable: LintSeverity

alpine_variables: tuple[AlpineVariableInfo, ...]

rule_unknown_component_js_variable: LintSeverity

component_js_globals: tuple[AlpineVariableInfo, ...]

allows_extra_variables: bool

to_dict() -> dict[str, object]

from_dict(value: object) -> TemplateLintInfo

Describe one known template variable using detached portable text.

name: str

type_display: str | None

type_fidelity: Literal['normalized', 'unavailable']

description: str | None

source: VariableSource

to_dict() -> dict[str, object]

from_dict(value: object) -> TemplateVariableInfo

Discover direct literal and static file assets on proven components.

Discovery recognizes direct template, js, and css literals, plus constant template_file, js_file, and css_file paths. It never imports the module or evaluates a computed declaration.

Parameters

• source str - Complete Python module source.

Returns

PythonComponentAssetDiscovery: Definite inline regions, file declarations, and explicit notices.

Raises

• SyntaxError - If source is not a complete valid Python module.
• TypeError - If source is not a string.

Discover direct literal templates on provable Citry component classes.

Normal batch tooling leaves recover_incomplete false and receives the original Python SyntaxError. An interactive editor may opt into the narrow recovery of one unfinished direct triple-quoted template literal.

Validate provider replies and atomically finish one Python source plan.

Every selected literal is rewritten only after every provider reply, Python parse, asset rediscovery, and decoded-value check succeeds. A failure raises without exposing a partial source candidate.

Parameters

• plan PythonComponentAssetPlan - Exact plan returned by prepare_python_component_assets.
• results Sequence[EmbeddedFormatResult] - One source-bound reply for every request in plan.
• require_providers bool - Reject unavailable providers and embedded regions that could not be delegated.

Returns

PythonComponentAssetFormatResult: The complete formatted Python source and provider metadata.

Raises

• PythonTemplateFormatError - If replies are missing, stale, duplicated, unavailable when required, invalid, or unsafe to rewrite.
• TypeError - If plan, results, or require_providers has the wrong type.

Format selected direct component assets in one atomic Python-file edit.

This synchronous convenience function prepares a plan, invokes provider once per JavaScript or CSS request, then validates and finishes the plan. Call the two-pass prepare and finish functions directly when provider work must be asynchronous. With no provider, M2 template formatting still runs while JavaScript and CSS requests remain unchanged with notices.

Parameters

• source str - Complete Python module source.
• kinds Collection[PythonComponentAssetKind | str] - Explicit template, js, and css kinds to select.
• host_offset int | None - Optional zero-based Python string offset selecting only the containing direct asset.
• provider Callable[[PythonComponentAssetRequest], EmbeddedFormatResult] | None - Optional synchronous JavaScript/CSS formatting callback.
• require_providers bool - Reject the complete operation when any selected embedded region has no provider.

Returns

PythonComponentAssetFormatResult: The validated complete source, changed asset identities, notices, and

Raises

• PythonTemplateFormatError - If discovery, formatting, a provider, or final validation fails. No partial candidate is exposed.
• TypeError - If an argument or provider reply has the wrong type.
• ValueError - If host_offset or a selected kind is invalid.

Format proven direct Citry template literals in complete Python source.

With no offset, every definite inline template is one atomic operation. A host offset selects only the literal content containing that Python string position. The result preserves string prefixes, delimiters, and all host text outside the exact decoded-template rewrite hunks.

Parameters

• source str - Complete Python module source.
• host_offset int | None - Optional zero-based Python string offset inside one template literal body.

Returns

PythonTemplateFormatResult: The validated source, changed component names, and discovery notices.

Raises

• PythonTemplateFormatError - If Python or Citry syntax is invalid, a selected literal is not safely rewriteable, or validation fails.
• TypeError - If source or host_offset has the wrong type.
• ValueError - If host_offset is outside source.

Prepare one atomic Python component-asset formatting operation.

Templates first receive Citry structure and Python-expression formatting. Safe script and style bodies, plus direct js and css literals, become standalone provider requests. The returned plan makes no source edit, so callers may resolve those requests asynchronously.

Parameters

• source str - Complete Python module source.
• kinds Collection[PythonComponentAssetKind | str] - Explicit component asset kinds selected for this operation.
• host_offset int | None - Optional zero-based Python string offset. When supplied, only the containing selected direct asset is prepared.

Returns

PythonComponentAssetPlan: A source-bound plan and its provider requests.

Raises

• PythonTemplateFormatError - If Python or selected asset syntax is invalid, or a selected literal cannot be rewritten safely.
• TypeError - If an argument has the wrong type.
• ValueError - If host_offset is outside source or a kind is unknown.

Diagnose free roots missing from at least one proven component namespace.

Parameters

• template object - Parsed Citry template AST. Its parser-reported free variables already exclude lexical and Python-local bindings.
• consumers Sequence[TemplateLintConsumer] - Every proven component that consumes this physical template.

Returns

TemplateLintFinding: Findings in the parser's stable free-variable order. No consumer means

Raises

• TypeError - If the parsed object lacks Citry free-variable records.