cadrumo.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)[source]

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.

  • constraints – Complete registry-owned numeric and text constraint contract, or None when the casilla is unconstrained.

  • 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 constraints: CasillaConstraints | None

Return the complete registry-owned constraint contract, if any.

property default: object | None

Return the default value used when no input is supplied.

class CasillaCollection(*args, **kwargs)[source]

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

Return the CasillaSchema for casilla_id, or None.

Return type:

CasillaSchema | None

Parameters:

casilla_id (CasillaId)

all()[source]

Return every casilla schema in the collection.

Return type:

Sequence[CasillaSchema]

Returns:

Sequence of every CasillaSchema in the collection.

class CasillaSchemaProvider(*args, **kwargs)[source]

Bases: Protocol

Resolves a casilla collection for a given modelo.

get_collection(modelo)[source]

Return the casilla collection for modelo.

Return type:

CasillaCollection

Returns:

The CasillaCollection for the given modelo code.

Parameters:

modelo (str)

class DeadlineStatus(*args, **kwargs)[source]

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

Bases: Protocol

Checks the filing deadline for a typed modelo period.

check(modelo, period)[source]

Return the DeadlineStatus for modelo and period.

Return type:

DeadlineStatus

Parameters:
class ModeloProfile(*args, **kwargs)[source]

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.