aeat.application.modelo._selectors module

Selector policy for operator-facing modelo work targets.

Visible modelo/year/period input is normalized into a ModeloWorkSelectorRequest and resolved to a ModeloWorkResolution over active aeat.domain.modelos.WorkUnit records. Revision selectors then load persisted CalculationRevision rows and return a ModeloCalculationRevisionSelection for current, latest draft, latest verified, filed, or explicit-id picks.

The selector boundary implements the accepted visible-target addressing policy: the common operator target is active bucket/profile plus modelo, filing year, and period; raw work-unit and calculation-revision ids remain exact-addressing escape hatches. An explicit work-unit id is validated against any natural-key flags supplied beside it, discarded work units are ignored by default, and an ambiguous visible target refuses with candidate guidance instead of guessing.

Command-specific revision defaults stay here rather than in CLI modules: verification selects the current draft, filing selects the current verified-complete revision, and export prefers the current filed revision before falling back to an unambiguous verified-complete revision.

class ModeloWorkSelectorState(*values)[source]

Bases: StrEnum

Resolution state for a visible modelo filing target.

ABSENT
RESOLVED
class ModeloCalculationRevisionSelector(*values)[source]

Bases: StrEnum

Closed selector set for calculation revisions under a work unit.

CURRENT
LATEST_DRAFT
LATEST_VERIFIED
FILED
EXPLICIT
class ModeloVerifySelector(*values)[source]

Bases: StrEnum

Draft-reachable selector subset accepted by modelo work verify.

verify_modelo_revision refuses any revision not in state BORRADOR, so the only selectors that can resolve to a verifiable revision are the ones that reach a draft: current (when the current revision is still a draft), latest-draft, and explicit (an explicitly-named draft revision id). The post-draft selectors latest-verified and filed on the full ModeloCalculationRevisionSelector name states verify rejects, so advertising them on the verify command is an advertised-but-impossible combination (audit 2026-06-10-cli-operator-surface-audit F5(d), decision D5). This narrowed enum is what the verify --select option advertises; other commands keep the full selector enum.

CURRENT
LATEST_DRAFT
EXPLICIT
to_calculation_revision_selector()[source]

Map a verify selector to its ModeloCalculationRevisionSelector member.

Return type:

ModeloCalculationRevisionSelector

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

Bases: ModeloError

Base error for modelo work selector refusals.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception ModeloWorkNoActiveBucketError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: ModeloWorkSelectorError

Raised when a selector requires the active bucket but none is selected.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception ModeloWorkUnitNotFoundError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: ModeloWorkSelectorError, KeyError

Raised when an explicit work-unit id does not exist.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception ModeloWorkSelectorContradictionError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: ModeloWorkSelectorError, ValueError

Raised when explicit id and natural-key flags address different work.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception ModeloWorkVisibleTargetAmbiguousError(candidates)[source]

Bases: ModeloWorkSelectorError

Raised when a visible target matches multiple active work units.

Parameters:

candidates (tuple[ModeloWorkUnitCandidate, ...])

Return type:

None

code: ClassVar[ErrorCode]
exception ModeloWorkRevisionConflictError(*, requested_revision_id, existing)[source]

Bases: ModeloWorkSelectorError

Raised when the requested registry revision conflicts with active work.

Parameters:
Return type:

None

code: ClassVar[ErrorCode]
exception ModeloCalculationRevisionSelectorError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: ModeloError

Base error for calculation-revision selector refusals.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception ModeloCalculationRevisionSelectorNotFoundError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: ModeloCalculationRevisionSelectorError, KeyError

Raised when a requested calculation revision cannot be selected.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception ModeloCalculationRevisionSelectorStateError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: ModeloCalculationRevisionSelectorError

Raised when a command-specific selector finds a revision in the wrong state.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception ModeloCalculationRevisionSelectorAmbiguousError(candidates)[source]

Bases: ModeloCalculationRevisionSelectorError

Raised when a default revision selector would have to guess.

Parameters:

candidates (tuple[ModeloCalculationRevisionCandidate, ...])

Return type:

None

code: ClassVar[ErrorCode]
class ModeloWorkSelectorRequest(**data)[source]

Bases: BaseModel

Operator-facing modelo work selector.

bucket_id is optional so callers can address the active profile bucket by default. work_unit_id is the exact-addressing escape hatch; when present, any natural-key flags supplied alongside it are validated against the loaded work unit.

Parameters:

  • modelo (ModeloCode | None)

  • filing_year (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=2000), Le(le=2099)])] | None)

  • period (Period | None)

  • revision_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)] | None)

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)] | None)

  • work_unit_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)] | None)

modelo: ModeloCode | None
filing_year: Annotated[int, Field(ge=2000, le=2099)] | None
period: Period | None
revision_id: _RevisionId | None
bucket_id: _BucketId | None
work_unit_id: WorkUnitId | None
property has_visible_target: bool

Return whether modelo/year/period were all supplied.

class ModeloWorkUnitCandidate(**data)[source]

Bases: BaseModel

Human-readable candidate metadata for selector guidance.

Parameters:

  • work_unit_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])

  • short_work_unit_id (str)

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • modelo (ModeloCode)

  • filing_year (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=2000), Le(le=2099)])])

  • period (Period)

  • revision_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • state (WorkUnitState)

  • current_calculation_revision_id (str | None)

  • filed_calculation_revision_id (str | None)

  • current_filing_record_id (str | None)

  • created_at (str)

  • updated_at (str)

work_unit_id: WorkUnitId
short_work_unit_id: str
bucket_id: _BucketId
modelo: ModeloCode
filing_year: Annotated[int, Field(ge=2000, le=2099)]
period: Period
revision_id: _RevisionId
state: WorkUnitState
current_calculation_revision_id: str | None
filed_calculation_revision_id: str | None
current_filing_record_id: str | None
created_at: str
updated_at: str
classmethod from_work_unit(unit)[source]

Project a work unit into a ModeloWorkUnitCandidate selector guidance record.

Return type:

ModeloWorkUnitCandidate

Parameters:

unit (WorkUnit)

class ModeloCalculationRevisionCandidate(**data)[source]

Bases: BaseModel

Human-readable calculation revision metadata for selector guidance.

Parameters:

  • calculation_revision_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])

  • short_calculation_revision_id (str)

  • work_unit_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])

  • state (CalculationRevisionState)

  • created_at (str)

  • updated_at (str)

  • verified_at (str | None)

  • filed_at (str | None)

calculation_revision_id: CalculationRevisionId
short_calculation_revision_id: str
work_unit_id: WorkUnitId
state: CalculationRevisionState
created_at: str
updated_at: str
verified_at: str | None
filed_at: str | None
classmethod from_revision(revision)[source]

Project a CalculationRevision into a ModeloCalculationRevisionCandidate.

Return type:

ModeloCalculationRevisionCandidate

Parameters:

revision (CalculationRevision)

class ModeloCalculationRevisionSelection(**data)[source]

Bases: BaseModel

Resolved calculation revision selection under a work unit.

Parameters:
selector: ModeloCalculationRevisionSelector
work_unit_id: WorkUnitId
revision: CalculationRevision
candidates: tuple[ModeloCalculationRevisionCandidate, ...]
class ModeloWorkResolution(**data)[source]

Bases: BaseModel

Resolved selector outcome for a visible modelo filing target.

Parameters:

  • state (ModeloWorkSelectorState)

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • modelo (ModeloCode | None)

  • filing_year (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=2000), Le(le=2099)])] | None)

  • period (Period | None)

  • requested_revision_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)] | None)

  • work_unit (WorkUnit | None)

  • candidates (tuple[ModeloWorkUnitCandidate, ...])

state: ModeloWorkSelectorState
bucket_id: _BucketId
modelo: ModeloCode | None
filing_year: Annotated[int, Field(ge=2000, le=2099)] | None
period: Period | None
requested_revision_id: _RevisionId | None
work_unit: WorkUnit | None
candidates: tuple[ModeloWorkUnitCandidate, ...]
resolve_modelo_work_bucket(request)[source]

Resolve the selector bucket from an explicit id or the active profile.

Return type:

str

Parameters:

request (ModeloWorkSelectorRequest)

visible_target_work_units(request, *, repository=None)[source]

Return active aeat.domain.modelos.WorkUnit records matching the visible target.

The visible target is bucket/modelo/filing-year/period only. Registry revision is intentionally not part of this lookup so a conflicting revision_id can be reported as a conflict against the existing active work unit instead of silently selecting or creating a second target.

Return type:

tuple[WorkUnit, ...]

Parameters:
resolve_modelo_work_unit(request, *, repository=None)[source]

Resolve one work unit and return a ModeloWorkResolution by exact id or visible target.

The visible-target path deliberately searches by bucket/modelo/year/period before registry-revision exact targeting. That prevents a command from silently creating or selecting a second active work unit for the same filing.

Return type:

ModeloWorkResolution

Parameters:
select_modelo_calculation_revision(work_unit, *, selector, calculation_revision_id=None, calculation_repository=None)[source]

Select one persisted calculation revision as ModeloCalculationRevisionSelection.

EXPLICIT requires calculation_revision_id and verifies the revision belongs to the supplied aeat.domain.modelos.WorkUnit. Non-explicit selectors resolve through the work unit’s current/filed pointers or by latest state, and refuse missing or mismatched state instead of falling back to another revision.

Return type:

ModeloCalculationRevisionSelection

Parameters:
resolve_modelo_calculation_revision_pick(work_unit, *, selector=ModeloCalculationRevisionSelector.CURRENT, calculation_revision_id=None, default_for=None, calculation_repository=None)[source]

Resolve a command-specific ModeloCalculationRevisionSelection pick under one work unit.

This is the application selector policy surface for commands that accept a natural work target plus a revision selector. It preserves the exact calculation-revision id escape hatch, while keeping command defaults explicit: verification consumes the current draft, filing consumes the current verified-complete revision, and export prefers filed/current verified revisions according to select_exportable_revision.

Return type:

ModeloCalculationRevisionSelection

Parameters:
select_current_draft_revision(work_unit, *, calculation_repository=None)[source]

Select the current draft revision as a ModeloCalculationRevisionSelection for verification.

Return type:

ModeloCalculationRevisionSelection

Parameters:
select_current_verified_revision(work_unit, *, calculation_repository=None)[source]

Select the current verified-complete revision for filing.

Returns a ModeloCalculationRevisionSelection.

Return type:

ModeloCalculationRevisionSelection

Parameters:
select_exportable_revision(work_unit, *, calculation_repository=None)[source]

Select the default exportable ModeloCalculationRevisionSelection for a work unit.

Preference order: 1. current filed pointer, when it points to a current filed revision; 2. current calculation pointer, when it is verified-complete; 3. one unambiguous verified-complete revision, only when no current draft conflicts.

Return type:

ModeloCalculationRevisionSelection

Parameters: