Module

diagnostics

Public, surface-neutral diagnostics for Kida tooling.

The functions in this module expose the same immutable facts used by kida checkwithout inheriting CLI stream or exit-code policy. Locations use 1-based lines and 0-based columns; end positions are exclusive when present.

11Classes4Functions

Classes

DiagnosticSeverity 0 ▼
Severity assigned by the diagnostic producer.

Severity assigned by the diagnostic producer.

DiagnosticConfidence 0 ▼
How conclusively Kida can make a diagnostic claim.

How conclusively Kida can make a diagnostic claim.

SourcePosition 3 ▼
One source position using a 1-based line and optional 0-based column.

One source position using a 1-based line and optional 0-based column.

Attributes

Name Type Description
line int —
column int | None —

Methods

Internal Methods 1 ▼
__post_init__ 0 ▼
def __post_init__(self) -> None
SourceSpan 5 ▼
Logical template path and optional half-open source range.

Logical template path and optional half-open source range.

Attributes

Name Type Description
path str | None —
start SourcePosition | None —
end SourcePosition | None —

Methods

is_exact 0 bool ▼
Return whether the span is precise enough for a source edit.
property
def is_exact(self) -> bool
Returns
bool
Internal Methods 1 ▼
__post_init__ 0 ▼
def __post_init__(self) -> None
RelatedLocation 3 ▼
A labeled source location related to the primary finding.

A labeled source location related to the primary finding.

Attributes

Name Type Description
label str —
span SourceSpan —

Methods

Internal Methods 1 ▼
__post_init__ 0 ▼
def __post_init__(self) -> None
SafeEdit 4 ▼
An unambiguous replacement over an exact source span.

An unambiguous replacement over an exact source span.

Attributes

Name Type Description
span SourceSpan —
replacement str —
description str | None —

Methods

Internal Methods 1 ▼
__post_init__ 0 ▼
def __post_init__(self) -> None
DiagnosticSnippet 4 ▼
Plain source lines surrounding a diagnostic.

Plain source lines surrounding a diagnostic.

Attributes

Name Type Description
lines tuple[tuple[int, str], ...] —
error_line int —
column int | None —

Methods

Internal Methods 1 ▼
__post_init__ 0 ▼
def __post_init__(self) -> None
Diagnostic 16 ▼
One immutable Kida finding, independent of its output surface.

One immutable Kida finding, independent of its output surface.

Attributes

Name Type Description
code str —
category str —
severity DiagnosticSeverity —
message str —
span SourceSpan —
title str | None —
kind str | None —
suggestion str | None —
safe_edit SafeEdit | None —
related_locations tuple[RelatedLocation, ...] —
confidence DiagnosticConfidence —
notes tuple[str, ...] —
documentation_url str | None —
source_snippet DiagnosticSnippet | None —
metadata tuple[tuple[str, str], ...] —

Methods

Internal Methods 1 ▼
__post_init__ 0 ▼
def __post_init__(self) -> None
DiagnosticConverter 1 ▼
Pure conversion boundary from one producer record to ``Diagnostic``.

Pure conversion boundary from one producer record toDiagnostic.

Methods

Internal Methods 1 ▼
__call__ 1 Diagnostic ▼
def __call__(self, source: SourceT, /) -> Diagnostic
Parameters
Name Type Description
source —
Returns
Diagnostic
DiagnosticOptions 5 ▼
Opt-in static checks shared by source and directory diagnosis.

Opt-in static checks shared by source and directory diagnosis.

Attributes

Name Type Description
strict bool —
validate_calls bool —
a11y bool —
typed bool —
lint_fragile_paths bool —
DiagnosticReport 2 ▼
Policy-neutral result of one programmatic diagnostic request.

Policy-neutral result of one programmatic diagnostic request.

Attributes

Name Type Description
diagnostics tuple[Diagnostic, ...] —
partial bool —

Functions

diagnose_directory 2 DiagnosticReport ▼
Diagnose templates below *root* with the same collection as ``kida check``.
def diagnose_directory(root: str | PathLike[str], *, options: DiagnosticOptions = _DEFAULT_OPTIONS) -> DiagnosticReport
Parameters
Name Type Description
root str | PathLike[str]
options DiagnosticOptions Default:_DEFAULT_OPTIONS
Returns
DiagnosticReport
diagnose_source 4 DiagnosticReport ▼
Diagnose an in-memory template without adding it to environment caches. A supp…
def diagnose_source(source: str, *, name: str = '<string>', environment: Environment | None = None, options: DiagnosticOptions = _DEFAULT_OPTIONS) -> DiagnosticReport

Diagnose an in-memory template without adding it to environment caches.

A supplied environment contributes lexer/parser configuration, extensions, autoescape selection, and loader-backed imported component metadata. Kida does not mutate its registries; resolving imports may use that environment's existing thread-safe template cache.

Parameters
Name Type Description
source str
name str Default:'<string>'
environment Environment | None Default:None
options DiagnosticOptions Default:_DEFAULT_OPTIONS
Returns
DiagnosticReport
diagnostic_from_exception 2 Diagnostic ▼
Convert a Kida template or lexer exception into one public diagnostic. ``TypeE…
def diagnostic_from_exception(error: Exception, *, path: str | None = None) -> Diagnostic

Convert a Kida template or lexer exception into one public diagnostic.

TypeErroris raised for unrelated Python exceptions so framework adapters cannot accidentally relabel arbitrary application failures as Kida diagnostics.

Parameters
Name Type Description
error Exception
path str | None Default:None
Returns
Diagnostic
apply_safe_edits 3 str ▼
Apply non-overlapping, snapshot-matched safe edits for one template. Diagnosti…
def apply_safe_edits(source: str, diagnostics: Iterable[Diagnostic], *, path: str) -> str

Apply non-overlapping, snapshot-matched safe edits for one template.

Diagnostics for other paths and diagnostics without a safe edit are ignored. AValueErroris raised before any edit is applied when the current source differs from the captured source lines, a snapshot is incomplete, or two selected edits overlap.

Parameters
Name Type Description
source str
diagnostics Iterable[Diagnostic]
path str
Returns
str