aeat.application.workflow._protocols module

Protocol contracts for every component the workflow engine composes.

The composite workflow engine is defined against typing.Protocol surfaces — not concrete classes — for two reasons:

1. Cross-subpackage decoupling. Each Protocol lets the workflow engine integrate with an in-house subpackage without forcing a hard import dependency at the engine layer; adapters in application.workflow._adapters translate the richer real surfaces onto these narrow Protocols.

2. Protocol-shaped tests. Tests can supply narrow Protocol-conforming classes per scenario without importing the production adapters at the workflow layer.

Every Protocol here describes only the attributes the workflow engine actually reads. DeadlineEngineProtocol wraps the deadline engine’s compute method that returns a Schedule for a given TaxpayerProfile.

See also

WorkflowEngine

Orchestrates these contracts stage by stage.

application.workflow._adapters

Adapts production deadline, draft-building, submission, and live-read components to these contracts.

SubmissionEngine

Implements the read-only preflight surface described by SubmissionEngineProtocol.

WorkflowPurpose

Decides when workflow callers skip the AEAT filing-window preflight gate for local verification or local mark-as-filed paths.

class DeadlineEngineProtocol(*args, **kwargs)

Bases: Protocol

Narrow surface over domain.deadlines.DeadlineEngine.

compute(profile, year, *, today=None)

Return a Schedule for profile in year.

Parameters:

• profile (TaxpayerProfile) – The TaxpayerProfile whose filing obligations are scheduled.

• year (int) – The calendar year for which the schedule is computed.

• today (date | None) – Optional reference date for open-period classification.

Return type:

Schedule

class RegistryModeloDraftProtocol(*args, **kwargs)

Bases: ModeloDraftLike, Protocol

Workflow draft surface after registry-backed filing construction.

schema_version: str

class ModeloDraftBuilderProtocol(*args, **kwargs)

Bases: Protocol

Narrow surface over application.filing.build_draft().

build(*, modelo, period, profile, inputs, fail_on_warning=False)

Build a registry-backed filing draft for the given TaxpayerProfile.

Returns a RegistryModeloDraftProtocol.

Return type:

RegistryModeloDraftProtocol

Parameters:

• modelo (str)

• period (Period)

• profile (TaxpayerProfile)

• inputs (ModeloInputs)

• fail_on_warning (bool)

class SubmissionEngineProtocol(*args, **kwargs)

Bases: Protocol

Read-only preflight surface over SubmissionEngine.

preflight(draft, *, today, skip_deadline_window=False)

Run preflight gates against draft; raise on failure.

skip_deadline_window skips the AEAT filing-window gate. The local workflow uses this for both WorkflowPurpose.VERIFY and WorkflowPurpose.FILE: VERIFY is calendar-independent, while FILE is a local mark-as-filed path whose obligation existence has already been enforced by the deadline stage.

Return type:

None

Parameters:

• draft (RegistryModeloDraftProtocol)

• today (date)

• skip_deadline_window (bool)

class CertificateBundleProtocol(*args, **kwargs)

Bases: Protocol

Narrow contract for the auth-provider probe used by workflow preflight.

The workflow engine calls describe() once during the preflight stage to prove the configured auth provider is present and healthy. Any exception raised here is translated into application.workflow.WorkflowAbortReason.CERT_INVALID to preserve the existing workflow abort taxonomy.

describe()

Return the current auth-provider description; raise on failure.

Returns an AuthProviderDescription with the provider’s configured and available state.

Return type:

AuthProviderDescription

class ModeloInputsProviderProtocol(*args, **kwargs)

Bases: Protocol

Provides filing inputs for the draft stage.

Production adapters load inputs from bucket-scoped, secure application services rather than operator-supplied files.

load_inputs(*, modelo, period, profile)

Return the filing inputs for the draft build against the given TaxpayerProfile.

Return type:

TypeAliasType

Parameters:

• modelo (str)

• period (Period)

• profile (TaxpayerProfile)

class WorkflowExpedienteProtocol(*args, **kwargs)

Bases: Protocol

Narrow read surface for one AEAT expediente (open proceeding) entry.

An expediente is an administrative dossier AEAT associates with one modelo (e.g. "303") and one ejercicio (tax year). The workflow engine reads these two fields to decide whether an open proceeding blocks filing.

property modelo: str | None

property ejercicio: int | None

class WorkflowNotificationProtocol(*args, **kwargs)

Bases: Protocol

Narrow read surface for one AEAT inbox notification entry.

The workflow engine reads tipo, leida, certificado_id, and concepto to decide whether an unread blocking notification (typically a requerimiento) should abort the current run.

property tipo: str

property leida: bool | None

property certificado_id: str

property concepto: str

class WorkflowNotificationsSnapshotProtocol(*args, **kwargs)

Bases: Protocol

Container protocol for a point-in-time AEAT inbox snapshot.

Wraps a sequence of WorkflowNotificationProtocol rows returned by the AEAT inbox adapter. The engine iterates rows once to find blocking requerimientos.

property rows: Sequence[WorkflowNotificationProtocol]

ExpedientesSource

Async callable that fetches open expedientes for a session.

Parameters:

• arg0 – The authenticated AEAT session object.

• arg1 – Optional modelo filter; None returns all open expedientes.

Returns:

A tuple of WorkflowExpedienteProtocol entries.

alias of Callable[[object, str | None], Awaitable[tuple[WorkflowExpedienteProtocol, …]]]

NotificationsSource

Async callable that fetches the AEAT inbox snapshot for a session.

Parameters:

arg0 – The authenticated AEAT session object.

Returns:

A WorkflowNotificationsSnapshotProtocol with all current notification rows.

alias of Callable[[object], Awaitable[WorkflowNotificationsSnapshotProtocol]]