aeat.application.modelo._m145_communication_records module

Modelo 145 local communication record creation and read-back.

This module owns the bucket-local record lifecycle for the Modelo 145 payer communication workflow. It validates operator-provided casilla values against the active registry revision, persists the local record, renders the official export layout, and records delivery/completion transitions without creating an AEAT filing path.

See also

modelo

Public facade that re-exports these Modelo 145 record DTOs and service functions.

build_m145_communication_service_contract()

Registry-backed ownership contract that refuses filing-like surfaces.

M145CommunicationCreateCommand

Strict create-command DTO consumed by create_m145_communication_record().

M145CommunicationRecord

Persisted bucket-local communication record handled by this module.

M145CommunicationValidationResult

Validation result returned before export and on explicit validation.

ModeloRevision

Registry revision whose casillas, legal refs, source refs, and export layouts ground every record and rendered payload.

RegistrySnapshot

Snapshot wrapper resolved before create, validate, and export work.

exception M145CommunicationServiceError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: ModeloError

Base error for Modelo 145 local communication service failures.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception M145CommunicationRecordNotFoundError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: M145CommunicationServiceError, KeyError

Raised when a Modelo 145 communication record lookup targets no record.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception M145CommunicationRecordAmbiguousError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: M145CommunicationServiceError, KeyError

Raised when a Modelo 145 communication record prefix matches multiple records.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception M145CommunicationRecordValidationError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: M145CommunicationServiceError, ValueError

Raised when a Modelo 145 communication operation is blocked by validation.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception M145CommunicationRecordExportError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: M145CommunicationServiceError, ValueError

Raised when a Modelo 145 communication export cannot be rendered.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception M145CommunicationRecordTransitionError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: M145CommunicationServiceError, ValueError

Raised when a Modelo 145 communication state transition is not allowed.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
class M145CommunicationPeriod(*values)[source]

Bases: StrEnum

Registry-backed local communication period tokens for Modelo 145.

COMMUNICATION
VARIATION
class M145CommunicationRecordState(*values)[source]

Bases: StrEnum

Creation-state vocabulary for local Modelo 145 communication records.

CREATED
DELIVERED_TO_PAYER
LOCALLY_COMPLETED
class M145CommunicationValidationIssueKind(*values)[source]

Bases: StrEnum

Closed issue vocabulary for Modelo 145 local communication validation.

REVISION_MISMATCH
SOURCE_AUTHORITY_MISMATCH
UNDECLARED_CASILLA
MISSING_REQUIRED
INVALID_VALUE
MISSING_SOURCE_AUTHORITY
UNSUPPORTED_DATA_TYPE
class M145CommunicationValidationIssue(**data)[source]

Bases: BaseModel

One registry-backed validation issue for a local communication record.

Parameters:
kind: M145CommunicationValidationIssueKind
casilla_id: CasillaId | None
data_type: str | None
message: str
legal_refs: tuple[str, ...]
source_refs: tuple[str, ...]
class M145CommunicationValidationResult(**data)[source]

Bases: BaseModel

Registry-backed validation result for one local communication record.

Parameters:

  • schema_version (str)

  • communication_record_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=64), MaxLen(max_length=64), _PydanticGeneralMetadata(pattern='^[0-9a-f]{64}$')])])

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • service_owner (str)

  • modelo (str)

  • communication_year (int)

  • period_token (M145CommunicationPeriod)

  • revision_id (str)

  • valid (bool)

  • issue_count (int)

  • issues (tuple[M145CommunicationValidationIssue, ...])

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

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

schema_version: str
communication_record_id: M145CommunicationRecordId
bucket_id: BucketId
service_owner: str
modelo: str
communication_year: int
period_token: M145CommunicationPeriod
revision_id: str
valid: bool
issue_count: int
issues: tuple[M145CommunicationValidationIssue, ...]
legal_refs: tuple[str, ...]
source_refs: tuple[str, ...]
class M145CommunicationExportResult(**data)[source]

Bases: BaseModel

Registry-layout export payload for one local communication record.

Parameters:

  • schema_version (str)

  • communication_record_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=64), MaxLen(max_length=64), _PydanticGeneralMetadata(pattern='^[0-9a-f]{64}$')])])

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • service_owner (str)

  • modelo (str)

  • communication_year (int)

  • period_token (M145CommunicationPeriod)

  • revision_id (str)

  • export_layout_id (str)

  • encoding (str)

  • record_count (int)

  • byte_length (int)

  • payload_sha256 (str)

  • payload (bytes)

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

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

schema_version: str
communication_record_id: M145CommunicationRecordId
bucket_id: BucketId
service_owner: str
modelo: str
communication_year: int
period_token: M145CommunicationPeriod
revision_id: str
export_layout_id: str
encoding: str
record_count: int
byte_length: int
payload_sha256: str
payload: bytes
legal_refs: tuple[str, ...]
source_refs: tuple[str, ...]
class M145CommunicationCreateCommand(**data)[source]

Bases: BaseModel

Operator request to create a local Modelo 145 payer communication record.

Parameters:
communication_year: int
period_token: M145CommunicationPeriod
field_values: dict[CasillaId, M145CommunicationFieldValue]
note: str | None
class M145CommunicationRecord(**data)[source]

Bases: BaseModel

Persisted bucket-local Modelo 145 communication record.

Parameters:

  • communication_record_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=64), MaxLen(max_length=64), _PydanticGeneralMetadata(pattern='^[0-9a-f]{64}$')])])

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • service_owner (str)

  • modelo (str)

  • communication_year (int)

  • period_token (M145CommunicationPeriod)

  • revision_id (str)

  • state (M145CommunicationRecordState)

  • field_values (dict[CasillaId, Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MaxLen(max_length=512)])]])

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

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

  • created_at (datetime)

  • delivered_to_payer_at (datetime | None)

  • locally_completed_at (datetime | None)

  • note (str | None)

communication_record_id: M145CommunicationRecordId
bucket_id: BucketId
service_owner: str
modelo: str
communication_year: int
period_token: M145CommunicationPeriod
revision_id: str
state: M145CommunicationRecordState
field_values: dict[CasillaId, M145CommunicationFieldValue]
legal_refs: tuple[str, ...]
source_refs: tuple[str, ...]
created_at: datetime
delivered_to_payer_at: datetime | None
locally_completed_at: datetime | None
note: str | None
property snapshot_id: str
derive_m145_communication_record_id(*, bucket_id, communication_year, period_token, revision_id, field_values)[source]

Return the content-addressed id for a Modelo 145 communication record.

Return type:

str

Parameters:

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • communication_year (int)

  • period_token (M145CommunicationPeriod | str)

  • revision_id (str)

  • field_values (Mapping[str, str])

m145_communication_record_object_key(bucket_id, communication_record_id)[source]
Return type:

str

Parameters:

  • bucket_id (str)

  • communication_record_id (str)

list_m145_communication_records(*, bucket_id)[source]

Return every local Modelo 145 communication record in one bucket.

Return type:

tuple[M145CommunicationRecord, ...]

Parameters:

bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

read_m145_communication_record(communication_record_id, *, bucket_id)[source]

Return one Modelo 145 communication record by id or unambiguous prefix.

Return type:

M145CommunicationRecord

Parameters:

  • communication_record_id (str)

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

validate_m145_communication_record(communication_record_id, *, bucket_id)[source]

Validate one persisted Modelo 145 communication record against registry authority.

Return type:

M145CommunicationValidationResult

Parameters:

  • communication_record_id (str)

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

export_m145_communication_record(communication_record_id, *, bucket_id, actor='aeat.application.modelo', bucket_event_repository=None)[source]

Render one Modelo 145 communication record through the registry export layout.

Return type:

M145CommunicationExportResult

Parameters:

  • communication_record_id (str)

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • actor (str)

  • bucket_event_repository (BucketEventHistoryRepositoryProtocol | None)

mark_m145_communication_record_delivered_to_payer(communication_record_id, *, bucket_id, actor='aeat.application.modelo', bucket_event_repository=None)[source]

Mark one valid local communication record as delivered to the payer.

Return type:

M145CommunicationRecord

Parameters:

  • communication_record_id (str)

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • actor (str)

  • bucket_event_repository (BucketEventHistoryRepositoryProtocol | None)

mark_m145_communication_record_locally_completed(communication_record_id, *, bucket_id, actor='aeat.application.modelo', bucket_event_repository=None)[source]

Mark one payer-delivered local communication record as locally completed.

Return type:

M145CommunicationRecord

Parameters:

  • communication_record_id (str)

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • actor (str)

  • bucket_event_repository (BucketEventHistoryRepositoryProtocol | None)

create_m145_communication_record(command, *, bucket_id, actor='aeat.application.modelo', bucket_event_repository=None)[source]

Persist a bucket-local Modelo 145 communication record.

Creation stores the operator-provided registry casilla values as a local payer communication record. It validates that every value is keyed by a casilla declared in the active Modelo 145 registry revision, persists the local record, and emits the communication-created bucket event.

Return type:

M145CommunicationRecord

Parameters: