aeat.application.modelo._work_addressing module

Application-level addressing for modelo work commands.

The address facade converts visible modelo/year/period filing targets and exact work-unit ids into ModeloWorkAddress values, resolves them through the central selector contract, and returns the matching WorkUnit or CalculationRevision.

This module is the application facade over the accepted addressing policy: operators address the active bucket/profile plus modelo, filing year, and period; raw ids remain advanced exact-addressing escape hatches. Ambiguous visible targets, contradictory exact-id plus natural-key flags, and discarded default matches are handled by _selectors rather than by CLI-local string logic.

Creation flows validate the law-determined registry revision before delegating to create_work_unit(); an explicit --revision is an assertion of the selected legal revision, not a free override. Revision flows apply ModeloCalculationRevisionSelector defaults so verify, file, and export commands consume only the lifecycle states they are allowed to handle.

See also

_selectors:

The authoritative visible-target and revision-selector resolver.

_modelo:

CLI commands that project operator flags into this facade.

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

Bases: ModeloError, ValueError

Raised when a calculation-revision selector is internally inconsistent.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
class ModeloVisibleFilingTarget(modelo, filing_year, period, registry_revision_id=None, bucket_id=None)[source]

Bases: object

Operator-visible modelo filing target under one bucket/profile.

This is the normal user-facing address: bucket/profile plus modelo, filing year, and period, with an optional registry-revision assertion for disambiguation.

Parameters:

  • modelo (str)

  • filing_year (int)

  • period (Period)

  • registry_revision_id (str | None)

  • bucket_id (str | None)

modelo: str
filing_year: int
period: Period
registry_revision_id: str | None
bucket_id: str | None
to_work_address()[source]

Project the visible target into the shared ModeloWorkAddress shape.

Return type:

ModeloWorkAddress

class ModeloExactWorkUnitTarget(work_unit_id, bucket_id=None)[source]

Bases: object

Advanced exact-addressing target for one content-addressed work unit.

Use this only when the caller already has an authoritative WorkUnitId; visible filing targets remain the default operator path.

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)])

  • bucket_id (str | None)

work_unit_id: Annotated[str]
bucket_id: str | None
to_work_address()[source]

Project the exact target into the shared ModeloWorkAddress shape.

Return type:

ModeloWorkAddress

class ModeloRevisionPick(selector=ModeloCalculationRevisionSelector.CURRENT, calculation_revision_id=None, default_for=None)[source]

Bases: object

Command-specific calculation-revision pick under a resolved work target.

default_for applies the command policy owned by _selectors: verify selects a draft, file selects a verified-complete revision, and export prefers the current filed revision before falling back to an unambiguous verified revision.

Parameters:

  • selector (ModeloCalculationRevisionSelector)

  • 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)] | None)

  • default_for (ModeloCalculationRevisionDefault | None)

selector: ModeloCalculationRevisionSelector
calculation_revision_id: Optional[Annotated[str]]
default_for: TypeAliasType | None
classmethod explicit(calculation_revision_id)[source]

Create an exact calculation-revision ModeloRevisionPick.

Return type:

ModeloRevisionPick

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)])

class ModeloResolvedWorkProjection(work_unit_id, short_work_unit_id, bucket_id, modelo, filing_year, period, registry_revision_id, state, current_calculation_revision_id, filed_calculation_revision_id, current_filing_record_id, created_at, updated_at)[source]

Bases: object

Support-safe projection of a resolved modelo work target.

The projection exposes the visible filing coordinates plus short ids for support guidance without making raw ids the normal operator workflow.

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 (str)

  • modelo (str)

  • filing_year (int)

  • period (Period)

  • registry_revision_id (str)

  • state (str)

  • current_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)] | None)

  • filed_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)] | None)

  • current_filing_record_id (str | None)

  • created_at (str)

  • updated_at (str)

work_unit_id: Annotated[str]
short_work_unit_id: str
bucket_id: str
modelo: str
filing_year: int
period: Period
registry_revision_id: str
state: str
current_calculation_revision_id: Optional[Annotated[str]]
filed_calculation_revision_id: Optional[Annotated[str]]
current_filing_record_id: str | None
created_at: str
updated_at: str
classmethod from_work_unit(work_unit)[source]

Project an internal WorkUnit into a ModeloResolvedWorkProjection.

Return type:

ModeloResolvedWorkProjection

Parameters:

work_unit (WorkUnit)

class ModeloResolvedRevisionProjection(calculation_revision_id, short_calculation_revision_id, work_unit_id, short_work_unit_id, selector, state, created_at, updated_at, verified_at=None, filed_at=None)[source]

Bases: object

Support-safe projection of a resolved calculation revision.

Carries the selected revision, selector policy, lifecycle state, and short ids used by CLI guidance after a work target has been resolved.

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)])

  • short_work_unit_id (str)

  • selector (ModeloCalculationRevisionSelector)

  • state (str)

  • created_at (str)

  • updated_at (str)

  • verified_at (str | None)

  • filed_at (str | None)

calculation_revision_id: Annotated[str]
short_calculation_revision_id: str
work_unit_id: Annotated[str]
short_work_unit_id: str
selector: ModeloCalculationRevisionSelector
state: str
created_at: str
updated_at: str
verified_at: str | None
filed_at: str | None
classmethod from_revision(revision, *, selector)[source]

Project a CalculationRevision into a ModeloResolvedRevisionProjection.

Return type:

ModeloResolvedRevisionProjection

Parameters:
class ModeloWorkAddress(work_unit_id=None, modelo=None, filing_year=None, period=None, registry_revision_id=None, bucket_id=None)[source]

Bases: object

Operator-facing or exact modelo work address.

This is the shared transport shape consumed at the application facade boundary. Prefer ModeloVisibleFilingTarget for model/year/period addressing or ModeloExactWorkUnitTarget for the advanced exact-id escape hatch, then project into this shape before selector resolution.

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)] | None)

  • modelo (str | None)

  • filing_year (int | None)

  • period (Period | None)

  • registry_revision_id (str | None)

  • bucket_id (str | None)

work_unit_id: Optional[Annotated[str]]
modelo: str | None
filing_year: int | None
period: Period | None
registry_revision_id: str | None
bucket_id: str | None
classmethod from_visible_target(target)[source]

Create a ModeloWorkAddress from a natural modelo filing target.

Return type:

ModeloWorkAddress

Parameters:

target (ModeloVisibleFilingTarget)

classmethod from_exact_target(target)[source]

Create a ModeloWorkAddress from an exact work-unit target.

Return type:

ModeloWorkAddress

Parameters:

target (ModeloExactWorkUnitTarget)

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

Bases: ModeloError, LookupError

Raised when a natural modelo work address resolves no active work unit.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError, ValueError

Raised when an explicit revision diverges from the law-determined one.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception ModeloWorkPeriodTokenError(*, year, token, modelo, declared_tokens, fallback=None)[source]

Bases: ModeloError, ValueError

Raised when an operator-facing period token cannot be normalized.

Parameters:

  • year (int)

  • token (str)

  • modelo (str | None)

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

  • fallback (str | None)

Return type:

None

code: ClassVar[ErrorCode]
class ModeloWorkEnsureResult(work_unit, reused, name_applied=None)[source]

Bases: object

Result of resolving or creating a visible-target work unit.

Parameters:
work_unit: WorkUnit
reused: bool
name_applied: str | None
work_address_for_modelo_target(target)[source]

Coerce a typed modelo work target into a ModeloWorkAddress selector shape.

Return type:

ModeloWorkAddress

Parameters:

target (ModeloWorkTarget)

modelo_work_address_from_operator_target(*, work_unit_id, modelo, year, period, registry_revision_id, bucket_id=None)[source]

Build a ModeloWorkAddress from exact or visible operator input.

A complete visible target is modelo + year + typed Period. If no visible target is supplied, an exact work_unit_id is required. Period year mismatches fail here before the selector sees the request.

Return type:

ModeloWorkAddress

Parameters:

  • work_unit_id (str | None)

  • modelo (str | None)

  • year (int | None)

  • period (Period | None)

  • registry_revision_id (str | None)

  • bucket_id (str | None)

resolve_modelo_work_unit_for_operator_target(*, work_unit_id=None, modelo=None, year=None, period=None, registry_revision_id=None, bucket_id=None)[source]

Resolve exact or visible operator input to one active WorkUnit.

The result comes from the shared selector boundary, so ambiguity and exact-id/natural-key contradictions surface as typed selector errors.

Return type:

WorkUnit

Parameters:

  • work_unit_id (str | None)

  • modelo (str | None)

  • year (int | None)

  • period (Period | None)

  • registry_revision_id (str | None)

  • bucket_id (str | None)

resolve_modelo_revision_for_operator_target(*, calculation_revision_id, work_unit_id, modelo, year, period, registry_revision_id, bucket_id=None, selector=ModeloCalculationRevisionSelector.CURRENT, default_for=None)[source]

Resolve one CalculationRevision from exact or visible operator input.

An explicit calculation-revision id can stand alone as the exact escape hatch. Otherwise the work target is resolved first and the selector/default policy is applied under that work unit.

Return type:

CalculationRevision

Parameters:
resolve_modelo_work_target(target)[source]

Resolve any supported modelo target through the shared selector boundary.

Returns a ModeloWorkResolution containing the resolved work unit or typed absence/ambiguity metadata from _selectors.

Return type:

ModeloWorkResolution

Parameters:

target (ModeloWorkTarget)

resolve_modelo_work_unit_id(target)[source]

Resolve a visible or exact modelo target to the authoritative work-unit id.

Return type:

str

Parameters:

target (ModeloWorkTarget)

project_modelo_work_unit(work_unit)[source]

Project an internal work unit into the visible ModeloResolvedWorkProjection addressing contract.

Return type:

ModeloResolvedWorkProjection

Parameters:

work_unit (WorkUnit)

project_modelo_work_target(target)[source]

Resolve a target and project it back to a ModeloResolvedWorkProjection.

Return type:

ModeloResolvedWorkProjection

Parameters:

target (ModeloWorkTarget)

resolve_registry_revision_for_work_target(*, modelo, filing_year, period, registry_revision_id)[source]

Resolve and validate the registry revision for a visible filing target.

When registry_revision_id is None the law-determined revision for (modelo, filing_year, period) is returned unconditionally.

When registry_revision_id is supplied it is treated as an assertion parameter (per select_revision()): an explicit --revision is accepted only when it names exactly the revision that select_revision would pick from (filing_year, period) alone. If the supplied id diverges from the law-determined revision the call refuses with an instructive error naming both the requested and the law-determined revision and stating that the binding is fixed by law (per the CLI-boundary instructive-refusal mandate in aeat-architecture-boundaries).

--revision is thereby demoted from a free override to an idempotence/assertion handle, mirroring the operator-surface ADR’s D8 shape for preflight --revision-id.

Return type:

str

Returns:

The revision id selected by select_revision().

Raises:

ModeloWorkRegistryYearMismatchError – The supplied revision id is not the law-determined revision for the visible filing period.

Parameters:

  • modelo (str)

  • filing_year (int)

  • period (Period)

  • registry_revision_id (str | None)

ensure_modelo_work_unit_for_visible_target(*, bucket_id, modelo, filing_year, period, registry_revision_id, name=None, actor='operator', causante_ccaa=None, enforce_applicability=True)[source]

Resume or create the active work unit for one visible filing target.

The visible target is resolved first. If one active unit exists, it is reused after profile-readiness validation and optional rename. If none exists, the law-determined registry revision is selected and a work unit is created.

Return type:

ModeloWorkEnsureResult

Returns:

A ModeloWorkEnsureResult marking whether the unit was reused or newly created.

Parameters:

  • bucket_id (str)

  • modelo (str)

  • filing_year (int)

  • period (Period)

  • registry_revision_id (str | None)

  • name (str | None)

  • actor (str)

  • causante_ccaa (CCAA | None)

  • enforce_applicability (bool)

resolve_modelo_work_address(address)[source]

Resolve an operator-facing modelo work address to a required ModeloWorkResolution.

Return type:

ModeloWorkResolution

Parameters:

address (ModeloWorkAddress)

resolve_optional_modelo_work_address(address)[source]

Resolve an operator-facing modelo work address to a ModeloWorkResolution.

Return type:

ModeloWorkResolution

Parameters:

address (ModeloWorkAddress)

resolve_modelo_work_address_unit(address)[source]

Resolve an operator-facing modelo work address to one WorkUnit.

Return type:

WorkUnit

Parameters:

address (ModeloWorkAddress)

resolve_modelo_calculation_revision_address(*, address, calculation_revision_id=None, selector=ModeloCalculationRevisionSelector.CURRENT, default_for=None)[source]

Resolve a CalculationRevision by exact id or under a modelo work address.

default_for applies the command-specific selector default after the work unit is resolved. A bare exact calculation-revision id bypasses work-address resolution and loads the revision directly.

Return type:

CalculationRevision

Parameters:
resolve_modelo_revision_pick(*, target, pick=None)[source]

Resolve and project a revision selection as ModeloResolvedRevisionProjection.

Return type:

ModeloResolvedRevisionProjection

Parameters:
resolve_verifiable_modelo_calculation_revision_address(*, address, calculation_revision_id=None, selector=ModeloCalculationRevisionSelector.CURRENT)[source]

Resolve the draft CalculationRevision that work verify may consume.

Return type:

CalculationRevision

Parameters:
resolve_fileable_modelo_calculation_revision_address(*, address, calculation_revision_id=None, selector=ModeloCalculationRevisionSelector.CURRENT)[source]

Resolve the verified-complete CalculationRevision that work file may consume.

Return type:

CalculationRevision

Parameters:
resolve_exportable_modelo_calculation_revision_address(*, address, calculation_revision_id=None, selector=ModeloCalculationRevisionSelector.CURRENT)[source]

Resolve the filed or verified-complete CalculationRevision that modelo export may consume.

Return type:

CalculationRevision

Parameters: