cadrumo.domain.submission.protocols module

Narrow Protocol ports 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 cadrumo.domain.deadlines used by preflight.

• ModeloFindingLike / ModeloDraftLike — narrow filing draft surfaces; domain.filing.schema.ModeloDraft structurally conforms to ModeloDraftLike.

• SubmissionRepositoryProtocol — the read-side persistence port.

Every declaration here is a runtime_checkable Protocol. The record types these ports carry — ModeloDraftStatus among them — live beside the other submission records in cadrumo.domain.submission.models. Finding entries are typed structurally through ModeloFindingLike; the implementation is cadrumo.domain.filing.schema.ModeloValidationFinding.

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 the active provider’s core.auth_provider.AuthProviderDescription.

Return type:

AuthProviderDescription

class DeadlineWindowChecker(*args, **kwargs)

Bases: Protocol

Narrow surface over cadrumo.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 ModeloFindingLike(*args, **kwargs)

Bases: Protocol

Narrow structural port over one draft.findings entry.

The implementation declares severity as a REQUIRED field with no default: cadrumo.domain.filing.schema.ModeloValidationFinding. Typing ModeloDraftLike.findings through this Protocol (rather than tuple[object, ...]) lets the preflight gate read .severity directly instead of through a getattr(..., None) guess – a field rename now fails loud instead of silently excluding every finding from the error-severity gate.

property severity: BaseSeverity

Return the severity the preflight error-findings gate reads.

class ModeloDraftLike(*args, **kwargs)

Bases: Protocol

Narrow surface over a filing draft.

domain.filing.schema.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 pyrefly treats them covariantly and frozen pydantic models satisfy the protocol without invariance errors.

property draft_id: str

Return the draft’s stable identifier.

property modelo: str

Return the AEAT modelo this draft files.

property period: Period

Return the filing period the draft covers.

property profile_tax_id: SubjectTaxId

Return the NIF / NIE of the taxpayer the draft is built for.

property status: object

Return the draft’s lifecycle status.

Declared as object so any draft implementation satisfies the Protocol; the preflight gate compares against cadrumo.domain.submission.models.ModeloDraftStatus.

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

Return the draft’s casilla values, keyed or iterable by implementation.

property findings: tuple[ModeloFindingLike, ...]

Return the validation findings the error-severity gate reads.

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, ...]