Explain

Explain subsystem for TypeID.

This package provides a high-level, non-breaking API and CLI support for answering the question:

"What is this TypeID?"

It is intentionally: - additive (no changes to existing TypeID semantics), - schema-optional (works fully offline), - safe by default (read-only, no side effects).

Public API

explain(id_str, schema_path=None, **options) -> Explanation

Explanation(id: str, valid: bool, parsed: ParsedTypeID, schema: Optional[TypeSchema] = None, derived: Dict[str, Any] = dict(), links: Dict[str, str] = dict(), provenance: Dict[str, Provenance] = dict(), warnings: List[str] = list(), errors: List[ParseError] = list()) dataclass

Final explanation object produced by the explain engine.

Sections: - parsed: always present (even if invalid; fields may be None) - schema: may be None if no schema found or schema loading disabled - derived: small dict for extra derived facts (extensible) - links: rendered links (from schema templates), safe for display - provenance: per-field provenance labels for transparency

to_dict() -> Dict[str, Any]

Convert to a JSON-serializable dict.

We avoid serializing complex objects directly (datetime, Enums) without conversion to keep --json output stable and easy to consume.

explain(id_str: str, *, schema_path: Optional[str | Path] = None, enable_schema: bool = True, enable_links: bool = True) -> Explanation

High-level convenience API for explaining a TypeID.

This function: - parses and validates the TypeID, - discovers and loads schema if enabled, - executes the explain engine, - never raises on normal user errors.

Parameters:

Name	Type	Description	Default
id_str	str	TypeID string to explain.	required
schema_path	Optional[str | Path]	Optional explicit path to schema file. If None, discovery rules are applied.	None
enable_schema	bool	Disable schema usage entirely if False.	True
enable_links	bool	Disable link rendering if False.	True

Returns:

Type	Description
Explanation	Explanation object.