aeat.domain.submission._protocols module

Narrow Protocol surfaces and value types for the submission engine.

The submission engine is composed of read-only sub-systems that the test suite exercises with concrete, hand-rolled Protocol-conforming classes (no mocks, no patches). Each Protocol declares only the surface the engine actually consumes, decoupling submission from the richer surfaces of its sibling subpackages.

• AuthProviderProbe — narrow auth-provider surface for the preflight gate.

• DeadlineWindowChecker — narrow surface over aeat.domain.deadlines used by preflight.

• ModeloFinding / ModeloDraftLike / ModeloDraftLoader — narrow filing draft surfaces; aeat.application.filing.ModeloDraft structurally conforms to ModeloDraftLike.

Every record is either a strict+frozen pydantic v2 model or a runtime_checkable Protocol; no dataclasses; no bare dicts.

class AuthProviderDescriptionLike(*args, **kwargs)

Bases: Protocol

Submission-facing shape returned by an auth provider.

Variables:

• kind – Provider identifier (kept as object so the protocol does not couple submission to the auth subpackage’s enum).

• label – Human-readable provider name.

• configured – Whether the provider’s required settings are present.

• available – Whether a session can currently be established.

• subject – Subject DN (or equivalent identity string), if known.

• expires_on – Expiry date for the underlying credential, if known.

property kind: object

Provider kind identifier.

property label: str

Human-readable provider name.

property configured: bool

Whether the provider’s required settings are present.

property available: bool

Whether a session can currently be established.

property subject: str | None

Subject DN or identity string when known, else None.

property expires_on: date | None

Expiry date for the underlying credential, when known.

class AuthProviderProbe(*args, **kwargs)

Bases: Protocol

Narrow submission-facing auth-provider surface.

property kind: object

Provider kind identifier consumed by the preflight gate.

describe()

Return an AuthProviderDescriptionLike describing the active auth provider.

Return type:

AuthProviderDescriptionLike

class DeadlineWindowChecker(*args, **kwargs)

Bases: Protocol

Narrow surface over aeat.domain.deadlines for the preflight gate.

is_window_open(modelo, period, today)

Return True iff the AEAT filing window for modelo / period is open on today.

Return type:

bool

Parameters:

• modelo (str)

• period (Period)

• today (date)

class ModeloFinding(**data)

Bases: BaseModel

Minimal finding record consumed by the preflight gate.

Distinct from aeat.application.filing.ModeloValidationFinding, which carries the validator’s full provenance graph; the submission engine reads only severity to decide whether the draft is blocked.

Variables:

• severity – The finding severity; ERROR blocks submission.

• message – Multilingual finding message.

Parameters:

• severity (BaseSeverity)

• message (str)

severity: BaseSeverity

message: str

class ModeloDraftStatus(*values)

Bases: StrEnum

Lifecycle status of a modelo draft, spanning preparation and submission.

The state machine carries a draft from creation through validation, operator approval, submission, and the AEAT-side terminal states. The preflight engine consumes only APROBADO and APROBACION_CADUCADA on its happy path; the broader filing / submission stack consumes the full lifecycle. Member names and values mirror the AEAT Sede labels per ADR A7.2.

Variables:

• BORRADOR – New draft, not yet validated.

• VALIDADO – Validation rules executed without errors.

• LISTO_PARA_PRESENTAR – Draft fully prepared for an attempt.

• APROBADO – Operator-approved for submission.

• APROBACION_CADUCADA – Approval timestamp aged out.

• PRESENTADA – A submission attempt is recorded.

• ACEPTADA – AEAT acknowledged the filing.

• RECHAZADA – AEAT rejected the filing.

• ENMENDADO – Superseded by an amendment record.

• ANULADO – Operator cancelled before submission.

BORRADOR

VALIDADO

LISTO_PARA_PRESENTAR

APROBADO

APROBACION_CADUCADA

PRESENTADA

ACEPTADA

RECHAZADA

ENMENDADO

ANULADO

class ModeloDraftLike(*args, **kwargs)

Bases: Protocol

Narrow surface over a filing draft.

aeat.application.filing.ModeloDraft structurally conforms to this Protocol so the engine can accept either the real draft or any Protocol-conforming hand-rolled class in tests.

Attributes are declared as read-only properties so pyright treats them covariantly and frozen pydantic models satisfy the protocol without invariance errors.

property draft_id: str

property modelo: str

property period: Period

property profile_tax_id: SubjectTaxId

property status: object

property values: Mapping[str, str] | Iterable[object]

property findings: tuple[object, ...]

class ModeloDraftLoader(*args, **kwargs)

Bases: Protocol

Loads a ModeloDraftLike from a draft path on disk.

load(_draft_path, /)

Load and return the ModeloDraftLike at draft_path.

Return type:

ModeloDraftLike

Parameters:

_draft_path (Path)

class SubmissionRepositoryProtocol(*args, **kwargs)

Bases: Protocol

Narrow domain-facing repository contract for the submission engine.

The concrete SubmissionRepository lives in the persistence adapter and inherits from the adapter-layer SecureBoundRepository. This Protocol captures only the surface the engine consumes so the domain depends inward on this port, and the application layer constructs the concrete repository and injects it into SubmissionEngine.

load(record_id, /)

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

Return type:

ModeloPresentado | None

Parameters:

record_id (str)

iter_submissions()

Yield every persisted submission in lexicographic id order.

Return type:

Iterator[ModeloPresentado]

Returns:

Iterator over ModeloPresentado records.

list_submission_ids()

Return every submission id persisted in this repository.

Return type:

tuple[str, ...]