aeat.core.topics package

Conceptual topic catalogue for aeat app registry citations.

A tax-naive operator hitting the CLI for the first time needs plain-language explanations of concepts (iva-regime, casilla, pago-fraccionado …) without having to leave the terminal. The CLI exposes:

• aeat app registry citations -> list every registered slug + one-line summary.

• aeat app registry citations <slug> -> render the topic body + see_also pointers + legal references.

Topics live as TOML files under registry/aeat/topics/<slug>.toml; title and body text live in the i18n catalogue under topic.<slug>.* so translations follow the project’s locale pipeline rather than hardcoded multiline strings.

The Topic records are core-level resources: they depend only on core primitives and the bundled registry path. They are loaded into a TopicCatalogue by load_topic_catalogue() and consumed through the core.resources._repos.topics.TopicCatalogueRepository singleton, keeping core free of any import into the application layer.

exception TopicNotFoundError(message=None, *, context=None, suggestion=None, translated_message=None)

Bases: AeatError

Raised when a requested slug is absent from a TopicCatalogue.

Parameters:

• message (str | None)

• context (dict[str, object] | None)

• suggestion (str | None)

• translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]

class Topic(**data)

Bases: BaseModel

One conceptual topic.

Variables:

• slug – Stable kebab-case identifier (iva-regime).

• title_key – i18n key resolving to the topic’s human-readable title. Convention: topic.<slug>.title.

• body_key – i18n key resolving to the topic body. Convention: topic.<slug>.body.

• see_also – Slugs of related topics for cross-referencing.

• legal_refs – Stable corpus references (ley-58-2003:art-27.2, rd-439-2007:art-110) the topic anchors against.

Parameters:

• slug (str)

• title_key (str)

• body_key (str)

• see_also (tuple[str, ...])

• legal_refs (tuple[str, ...])

slug: str

title_key: str

body_key: str

see_also: tuple[str, ...]

legal_refs: tuple[str, ...]

class TopicCatalogue(**data)

Bases: BaseModel

Closed catalogue of registered Topic records.

Parameters:

topics (tuple[Topic, ...])

topics: tuple[Topic, ...]

topic(slug)

Return the Topic for slug or raise.

Parameters:

slug (str) – Kebab-case topic identifier.

Return type:

Topic

Returns:

The matching Topic.

Raises:

TopicNotFoundError – When slug is not in the catalogue.

slugs()

Return every registered slug sorted alphabetically.

Return type:

tuple[str, ...]

load_topic_catalogue(root=None)

Load every registry/aeat/topics/<slug>.toml into one catalogue.

Parameters:

root (Path | None) – Override directory (defaults to the canonical project registry path).

Return type:

TopicCatalogue

Returns:

A TopicCatalogue carrying one Topic per TOML.