aeat.domain.filing._protocols module

Cross-module Protocols consumed by application.filing.

Every upstream collaborator (modelo identity, casilla schemas, deadline engine) is represented by a typing.Protocol so the filing application package does not take a hard import on any sibling subpackage. Concrete implementations are wired at runtime by the entrypoint.

These Protocols are intentionally minimal: they describe only the attributes application.filing actually consumes. They do not attempt to model the full surface of the upstream subpackages.

class CasillaSchema(*args, **kwargs)

Bases: Protocol

The minimal casilla schema surface consumed by builders.

Variables:

• casilla_id – Stable canonical casilla.id (e.g. "01").

• value_type – One of "decimal", "int", "str", "bool", "date".

• required – Whether the casilla must be present in a valid draft.

• formula – ID of the formula declared on this casilla, or None for literal casillas.

• formula_input_casilla_ids – Tuple of casilla IDs this casilla depends on. Empty for literal casillas.

• legal_refs – Regulatory citations grounding this casilla’s definition (BOE / AEAT permalinks).

• source_refs – Source-material citations backing this casilla.

• max_value (min_value /) – Inclusive Decimal bounds for numeric casillas; None if unbounded.

• default – Default value used when the casilla is required and no input was supplied.

property casilla_id: CasillaId

Return the canonical casilla.id identifier.

property value_type: str

Return the casilla value-type tag.

property required: bool

Return whether the casilla must be present in a valid draft.

property formula: FormulaId | None

Return the formula ID, or None if this is a literal casilla.

property formula_input_casilla_ids: tuple[CasillaId, ...]

Return the casilla IDs this casilla’s formula depends on.

property legal_refs: tuple[LegalRefId, ...]

Return the regulatory citation IDs grounding this casilla.

property source_refs: tuple[SourceRefId, ...]

Return the source-material citation IDs for this casilla.

property min_value: Decimal | None

Return the inclusive lower bound, if any.

property max_value: Decimal | None

Return the inclusive upper bound, if any.

property default: object | None

Return the default value used when no input is supplied.

class CasillaCollection(*args, **kwargs)

Bases: Protocol

A collection of casilla schemas keyed by ID.

property schema_version: str

Return the version of the underlying casilla DB.

get(casilla_id)

Return the CasillaSchema for casilla_id, or None.

Return type:

CasillaSchema | None

Parameters:

casilla_id (CasillaId)

all()

Return every casilla schema in the collection.

Return type:

Sequence[CasillaSchema]

Returns:

Sequence of every CasillaSchema in the collection.

class CasillaSchemaProvider(*args, **kwargs)

Bases: Protocol

Resolves a casilla collection for a given modelo.

get_collection(modelo)

Return the casilla collection for modelo.

Return type:

CasillaCollection

Returns:

The CasillaCollection for the given modelo code.

Parameters:

modelo (str)

class DeadlineStatus(*args, **kwargs)

Bases: Protocol

Result of a deadline check for a (modelo, period) tuple.

property due_date: date

Return the AEAT-published due date.

property is_overdue: bool

Return True when the reference date is past due_date.

class DeadlineChecker(*args, **kwargs)

Bases: Protocol

Checks the filing deadline for a typed modelo period.

check(modelo, period)

Return the DeadlineStatus for modelo and period.

Return type:

DeadlineStatus

Parameters:

• modelo (str)

• period (Period)

class ModeloProfile(*args, **kwargs)

Bases: Protocol

The taxpayer profile a draft is built for.

Only the attributes application.filing actually consumes are declared here; downstream callers may use richer profile objects as long as they expose these attributes.

property tax_id: SubjectTaxId

Return the taxpayer’s NIF / NIE.

property display_name: str

Return a short human-readable label for the taxpayer.

class ModeloDraftRepositoryProtocol(*args, **kwargs)

Bases: Protocol

Narrow domain-facing contract for the filing-draft repository.

ModeloDraftRepository structurally conforms to this Protocol; domain service code that only needs to load or save drafts should depend inward on this port.

property bucket_id: str | None

Return the profile bucket id when this repository resolved one.

load(record_id)

Load a persisted draft by id, or return None if absent.

Return type:

object

Parameters:

record_id (str)

save(payload)

Persist payload in the encrypted object store.

Return type:

None

Parameters:

payload (object)

list_draft_ids()

Return every draft id persisted in this repository.

Return type:

tuple[str, ...]

class ModeloAmendmentRepositoryProtocol(*args, **kwargs)

Bases: Protocol

Narrow domain-facing contract for the filing-amendment repository.

ModeloAmendmentRepository structurally conforms to this Protocol; domain service code that only needs to load, save, or list amendments should depend inward on this port.

property bucket_id: str | None

Return the profile bucket id when this repository resolved one.

load(amendment_id)

Load a persisted amendment by id, or return None if absent.

Return type:

object | None

Parameters:

amendment_id (str)

save(amendment)

Persist amendment in the encrypted object store.

Return type:

None

Parameters:

amendment (object)

list_amendment_ids()

Return every amendment id persisted in this repository.

Return type:

tuple[str, ...]