aeat.application.overview._calendar_models module

Typed DTOs for the overview calendar read model.

The models separate legal obligation rows (OverviewCalendarEntry), observed local events (OverviewCalendarEvent), and filing evidence (OverviewCalendarFilingEvidence). Filing evidence keeps OverviewLocalFilingState distinct from OverviewAeatSubmissionState so local readiness, AEAT submission, and justificante verification remain auditable independent axes.

These DTOs are consumed by application.overview.build_overview_calendar() and serialized by the overview CLI payload layer. Period-bearing models hydrate serialized Period values back into typed periods so merge keys stay aligned with the registry-token authority.

class OverviewPeriodState(*values)[source]

Bases: StrEnum

Closed user-facing state derived from deadline obligation status.

DUE
LATE
FILED
UNKNOWN
class OverviewCensoEnrolmentState(*values)[source]

Bases: StrEnum

Live Modelo 036 / censo provenance state for one calendar obligation.

NOT_CHECKED
NOT_REQUIRED
UNVERIFIED
VERIFIED
class OverviewCalendarEntrySource(*values)[source]

Bases: StrEnum

Origin of one overview calendar row.

REGISTRY_DEADLINE
LOCAL_WORK_UNIT
class OverviewLocalFilingState(*values)[source]

Bases: StrEnum

Local application-side filing axis for one calendar obligation.

These values describe the application’s internal filing lifecycle only. They are intentionally separate from OverviewAeatSubmissionState so a ready or imported local record cannot imply official AEAT submission.

NOT_READY_TO_FILE
READY_TO_FILE
EXTERNAL_BASELINE_IMPORTED
class OverviewAeatSubmissionState(*values)[source]

Bases: StrEnum

Observed AEAT-side submission evidence for one calendar obligation.

OverviewAeatSubmissionState.NOT_OBSERVED is the default until already-loaded official evidence proves a submitted, accepted, or justificante-verified state. Overview calendar commands never create this evidence by contacting AEAT.

NOT_OBSERVED
SUBMITTED_OBSERVED
ACCEPTED
JUSTIFICANTE_VERIFIED
user_state_for(obligation_status)[source]

Return the OverviewPeriodState for a deadline engine status.

Return type:

OverviewPeriodState

Parameters:

obligation_status (ObligationStatus)

class OverviewCalendarRange(**data)[source]

Bases: BaseModel

Inclusive date window for the overview calendar query.

application.overview.build_overview_calendar() expands the window to the covered filing years and filters legal obligation rows back to this inclusive range.

Parameters:
from_date: date
to_date: date
covered_years()[source]
Return type:

tuple[int, ...]

covers(candidate)[source]
Return type:

bool

Parameters:

candidate (date)

class OverviewCalendarFilingEvidence(**data)[source]

Bases: BaseModel

Filing evidence attached to one legal calendar obligation.

The local fields describe the application’s filing-record axis; the AEAT fields describe observed submission evidence from persisted official sources. Validators require justificante_verified and verified_justificante_csv to agree exactly with OverviewAeatSubmissionState.JUSTIFICANTE_VERIFIED, preventing a malformed event from claiming receipt verification without CSV evidence.

Parameters:

  • modelo (str | None)

  • filing_year (int | None)

  • period (Period | None)

  • local_filing_state (OverviewLocalFilingState)

  • local_filing_record_id (str | None)

  • local_calculation_revision_id (str | None)

  • local_filed_at (datetime | None)

  • aeat_submission_state (OverviewAeatSubmissionState)

  • aeat_submitted_at (datetime | None)

  • aeat_reference_id (str | None)

  • aeat_snapshot_id (str | None)

  • aeat_evidence_kind (str | None)

  • aeat_evidence_conflict_reference_ids (tuple[str, ...])

  • verified_justificante_csv (str | None)

  • justificante_required (bool)

  • justificante_verified (bool)

  • evidence_source (str | None)

modelo: str | None
filing_year: int | None
period: _Period | None
local_filing_state: OverviewLocalFilingState
local_filing_record_id: str | None
local_calculation_revision_id: str | None
local_filed_at: datetime | None
aeat_submission_state: OverviewAeatSubmissionState
aeat_submitted_at: datetime | None
aeat_reference_id: str | None
aeat_snapshot_id: str | None
aeat_evidence_kind: str | None
aeat_evidence_conflict_reference_ids: tuple[str, ...]
verified_justificante_csv: str | None
justificante_required: bool
justificante_verified: bool
evidence_source: str | None
class OverviewCalendarEntry(**data)[source]

Bases: BaseModel

One legal (modelo, period) row in the calendar view.

The deadline fields mirror ModeloDeadline. The optional OverviewCalendarFilingEvidence row attaches local and AEAT evidence without changing the legal deadline status from the deadline engine.

Parameters:
modelo: str
period: _Period
opens_on: date
closes_on: date
adjusted_closes_on: date
shift_reason: str
holiday_refs: tuple[str, ...]
jurisdictions: tuple[_HolidayJurisdiction, ...]
payment_cutoff_on: date | None
status: _ObligationStatus
user_state: OverviewPeriodState
recovery: _Recovery | None
filing_year: int | None
censo_enrolment_state: OverviewCensoEnrolmentState
filing_evidence: OverviewCalendarFilingEvidence
source: OverviewCalendarEntrySource
local_work_unit_id: str | None
local_work_unit_name: str | None
local_work_unit_revision_id: str | None
class OverviewCalendarEventType(*values)[source]

Bases: StrEnum

Observed event categories shown alongside legal filing windows.

FILING
MESSAGE
class OverviewCalendarEvent(**data)[source]

Bases: BaseModel

One observed local event attached to an overview calendar range.

Filing events may carry OverviewAeatSubmissionState when a persisted snapshot already observed it. Messages and unverified filings remain event-only observations and do not imply OverviewCalendarFilingEvidence or receipt verification.

post_filing_kind carries the fine-grained PostFilingEventKind procedural category (requerimiento, propuesta de liquidación, diligencia de embargo, …) classified from the pulled notification / expediente, so the coarse event_type axis does not collapse a demand for documents and an informational comunicación onto the same message row.

Parameters:
event_type: OverviewCalendarEventType
post_filing_kind: _PostFilingEventKind | None
event_date: date
source: str
summary: str
reference_id: str
snapshot_id: str | None
modelo: str | None
filing_year: int | None
period: _Period | None
status: str | None
source_url: str | None
authenticated_identity: str | None
aeat_submission_state: OverviewAeatSubmissionState | None
aeat_submitted_at: datetime | None
justificante_verified: bool | None
verified_justificante_csv: str | None
class CalendarWarning(**data)[source]

Bases: BaseModel

One under-specified-profile warning attached to a calendar query.

Parameters:
code: str
message: str
fix_command: str
affected_modelos: tuple[str, ...]
class CalendarCompleteness(**data)[source]

Bases: BaseModel

Breakdown of explicit profile values versus deadline-engine defaults.

Parameters:
explicitly_set_keys: tuple[str, ...]
defaulted_keys: tuple[str, ...]
computable_modelos: tuple[str, ...]
defaulted_modelos: tuple[str, ...]
class SuppressedCalendarEntry(**data)[source]

Bases: BaseModel

One non-applicable obligation retained by --show-suppressed.

Parameters:
modelo: str
period: _Period
verdict: ApplicabilityVerdict
reason: str
class OverviewCalendar(**data)[source]

Bases: BaseModel

Result of an aeat app overview calendar query.

entries contains legal filing windows, events contains additive local observations, and suppressed_entries preserves filtered applicability rows only when the caller explicitly requests them. coverage is the always-populated reconciliation of the full registry modelo set against entries: its advised bucket names every filing obligation the surface would otherwise have silently dropped, so a machine consumer never has to infer coverage from the presence or absence of a row.

Parameters:
range: OverviewCalendarRange
entries: tuple[OverviewCalendarEntry, ...]
generated_at: datetime
warnings: tuple[CalendarWarning, ...]
completeness: CalendarCompleteness
taxpayer_model_declared: bool
incomplete_reason: str | None
suppressed_entries: tuple[SuppressedCalendarEntry, ...]
events: tuple[OverviewCalendarEvent, ...]
coverage: ObligationCoverageReport
class OverviewStatusReport(**data)[source]

Bases: BaseModel

Current active-profile readiness counters for overview status.

Produced from OperatorStateProjection by application.overview.overview_status_report_from_projection().

Parameters:

  • active_profile (str | None)

  • active_profile_name (str | None)

  • transactions (int)

  • invoices (int)

  • drafts (int)

  • work_units (int)

  • discarded_work_units (int)

  • calculation_revisions (int)

  • unreadable_rows (int)

  • filing_obligation_advisories (tuple[str, ...])

  • unsupported_work_create_modelos (tuple[str, ...])

active_profile: str | None
active_profile_name: str | None
transactions: int
invoices: int
drafts: int
work_units: int
discarded_work_units: int
calculation_revisions: int
unreadable_rows: int
filing_obligation_advisories: tuple[str, ...]
unsupported_work_create_modelos: tuple[str, ...]