aeat.locales._modelo_manager module

Typed contract for modelo schema-local locale management.

The runtime registry loader owns how schema-local translations are applied: modelo-level locale TOML is keyed by continuidad_id and revision-level locale TOML is keyed by casilla_id. This module gives the locales CLI a typed authoring contract for ModeloDefinition / ModeloRevision storage without moving those translations into the eager application YAML catalogues.

exception ModeloLocaleError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AeatError, ValueError

Raised when modelo schema-local locale management fails.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
class ModeloLocaleScope(*values)[source]

Bases: StrEnum

Registry-local file scope for modelo schema translations.

MODELO
REVISION
class ModeloLocaleFieldKind(*values)[source]

Bases: StrEnum

Supported translation tables inside registry-local locale TOML files.

LABELS
HELP
class ModeloLocaleDriftKind(*values)[source]

Bases: StrEnum

Schema-local translation drift categories reported by the manager.

MISSING
STALE
class ModeloLocaleFileTarget(**data)[source]

Bases: BaseModel

One registry-local locale TOML target.

Parameters:
locale: OutputLanguage
modelo_id: str
scope: ModeloLocaleScope
revision_id: str | None
property relative_path: Path

Return this target’s path relative to the registry modelos root.

class ModeloLocaleTranslationFile(**data)[source]

Bases: BaseModel

Parsed contents of one schema-local locale TOML file.

Parameters:
target: ModeloLocaleFileTarget
path: Path
labels: dict[str, str]
help: dict[str, str]
table(field)[source]

Return the translation table for field.

Return type:

dict[str, str]

Parameters:

field (ModeloLocaleFieldKind)

class ModeloLocaleInventoryKey(**data)[source]

Bases: BaseModel

One schema key that can be translated in a registry-local locale file.

Parameters:
modelo_id: str
revision_id: str | None
scope: ModeloLocaleScope
field: ModeloLocaleFieldKind
key: str
source_casilla_id: CasillaId
source_continuidad_id: str | None
official_label: str
class ModeloLocaleDriftRecord(**data)[source]

Bases: BaseModel

One missing or stale schema-local translation leaf.

Parameters:
target: ModeloLocaleFileTarget
field: ModeloLocaleFieldKind
key: str
kind: ModeloLocaleDriftKind
class ModeloLocaleCoverageRecord(**data)[source]

Bases: BaseModel

Coverage summary for one modelo revision and locale.

Parameters:
locale: OutputLanguage
modelo_id: str
revision_id: str
label_required: int
label_translated: int
help_required: int
help_translated: int
drift: tuple[ModeloLocaleDriftRecord, ...]
property required_total: int

Return total required translation leaves.

property translated_total: int

Return total present translation leaves.

property complete: bool

Return whether all required translation leaves are present.

class ModeloLocaleManager(registry_root=None)[source]

Bases: object

Path authority for registry-local modelo schema translation files.

Parameters:

registry_root (Path | None)

resolve_modelo_dir(modelo_id)[source]

Resolve one directory-mode modelo under the contained registry root.

Return type:

Path

Parameters:

modelo_id (str)

resolve_revision_dir(modelo_id, revision_id)[source]

Resolve one revision directory under a directory-mode modelo.

Return type:

Path

Parameters:

  • modelo_id (str)

  • revision_id (str)

load_modelo(modelo_id)[source]

Load a directory-mode ModeloDefinition without applying locale TOML files.

Return type:

ModeloDefinition

Parameters:

modelo_id (str)

revision_ids(modelo_id)[source]

Return sorted revision ids for modelo_id.

Return type:

tuple[str, ...]

Parameters:

modelo_id (str)

inventory_keys(modelo_id, revision_id=None)[source]

Return ModeloLocaleInventoryKey rows for a modelo.

Revision-local records are keyed by casilla_id. Modelo-local records are keyed by continuidad_id and deduplicated across the selected revisions because the target TOML file is modelo-wide.

Return type:

tuple[ModeloLocaleInventoryKey, ...]

Parameters:

  • modelo_id (str)

  • revision_id (str | None)

drift_records(locale, modelo_id, revision_id)[source]

Return ModeloLocaleDriftRecord rows for missing and stale schema-local leaves.

Return type:

tuple[ModeloLocaleDriftRecord, ...]

Parameters:
coverage_record(locale, modelo_id, revision_id)[source]

Return a ModeloLocaleCoverageRecord for one modelo revision.

Return type:

ModeloLocaleCoverageRecord

Parameters:
scaffold_revision(locale, modelo_id, revision_id)[source]

Align locale TOML targets for one modelo revision.

Missing leaves are inserted with the schema key as an untranslated placeholder. Existing translated values are preserved. Stale leaves are removed because they no longer point at registry-backed schema keys.

Return type:

tuple[Path, ...]

Parameters:
set_translation_value(locale, modelo_id, revision_id, field, key, value)[source]

Set one schema-local translated leaf after registry-key validation.

Return type:

Path

Parameters:
remove_translation_value(locale, modelo_id, revision_id, field, key)[source]

Remove one existing schema-local translated leaf.

Return type:

Path

Parameters:
resolve_target_path(target)[source]

Resolve a locale target to a contained TOML file path.

Return type:

Path

Parameters:

target (ModeloLocaleFileTarget)

load_translation_file(target, *, require_exists=False)[source]

Load a ModeloLocaleTranslationFile, or return an empty file model.

Return type:

ModeloLocaleTranslationFile

Parameters:
write_translation_file(translation)[source]

Write one schema-local locale TOML file with stable table ordering.

Return type:

Path

Parameters:

translation (ModeloLocaleTranslationFile)