aeat.domain.attachments._models module

Strict immutable pydantic models for the attachment service.

Defines Attachment (one manifest entry) and AttachmentCatalogue (an immutable in-memory mapping of attachments keyed by attachment_id). Both models reject extra fields and freeze after validation so they can be shared safely across application code without defensive copying.

Return whether value names the link-only URI-list media type.

MIME syntax permits a parameter section (type/subtype; param=value), so the comparison is against the parsed media type — the token before any ; — not the full string. text/uri-list; charset=utf-8 is as link-only as the bare form and must be refused by every boundary that guards evidence-byte manifests.

Return type:

bool

Parameters:

value (str)

class Attachment(**data)[source]

Bases: BaseModel

Immutable attachment manifest tying bytes to transactions and invoices.

Each attachment is content-addressed: attachment_id is the SHA-256 of the stored bytes, and the model enforces that attachment_id == sha256 so the manifest cannot drift from the byte payload it references.

The manifest also records the originating channel (domain.attachments.AttachmentSource), the document kind (domain.attachments.AttachmentKind), and optional cross-references back to transaction and invoice identifiers so the evidence layer is traversable in either direction.

Variables:

  • attachment_id – 64-character lowercase hex SHA-256 digest. Equals sha256.

  • kind – Document kind. See domain.attachments.AttachmentKind.

  • source – Channel the bytes were captured from. See domain.attachments.AttachmentSource.

  • source_reference – Channel-specific reference (e.g. a Gmail message id, a Drive file id, a local path).

  • sha256 – 64-character lowercase hex SHA-256 of the stored bytes.

  • mime_type – Trimmed non-empty MIME type string.

  • bytes_size – Size in bytes of the stored payload.

  • captured_at – Timezone-aware capture timestamp.

  • linked_transaction_ids – Transaction identifiers this attachment supports.

  • linked_invoice_ids – Invoice identifiers this attachment supports.

  • bucket_id – Owning profile bucket for secure evidence attachment.

  • captured_by – Actor that captured or imported the evidence when known.

  • source_command – Backend/CLI command source that captured it when known.

  • metadata – Frozen string-to-string mapping for channel-specific metadata.

  • notes – Free-form trimmed notes; the empty string is allowed.

Parameters:

  • attachment_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])

  • kind (AttachmentKind)

  • source (AttachmentSource)

  • source_reference (str)

  • sha256 (str)

  • mime_type (str)

  • bytes_size (int)

  • captured_at (datetime)

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

  • linked_invoice_ids (tuple[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)] | None)

  • captured_by (str | None)

  • source_command (str | None)

  • metadata (Mapping[str, str])

  • notes (str)

attachment_id: AttachmentId
kind: AttachmentKind
source: AttachmentSource
source_reference: str
sha256: str
mime_type: str
bytes_size: int
captured_at: datetime
linked_transaction_ids: tuple[str, ...]
linked_invoice_ids: tuple[str, ...]
bucket_id: BucketId | None
captured_by: str | None
source_command: str | None
metadata: Mapping[str, str]
notes: str
class AttachmentCatalogue(**data)[source]

Bases: BaseModel

In-memory immutable catalogue keyed by attachment_id.

Accepts construction from either a bare mapping, an iterable of Attachment instances, or attachment payload dictionaries via from_attachments(). Every mapping key is verified to match the embedded Attachment.attachment_id so lookups cannot drift from the manifest content.

Variables:

attachments – Frozen mapping from attachment_id to Attachment.

Parameters:

attachments (Mapping[str, Attachment])

attachments: Mapping[str, Attachment]
classmethod from_attachments(attachments)[source]

Build a catalogue from an iterable, rejecting duplicates explicitly.

Parameters:

attachments (Iterable[Attachment | Mapping[str, object]]) – Attachments or attachment payloads to load.

Return type:

Self

Returns:

A validated immutable attachment catalogue.

get(attachment_id)[source]

Return one Attachment by ID if present.

Parameters:

attachment_id (str) – Stable attachment identifier (SHA-256 hex digest).

Return type:

Attachment | None

Returns:

The matching Attachment, or None when absent.

values()[source]

Iterate over catalogue attachments.

Return type:

Iterator[Attachment]

Returns:

Iterator over Attachment instances.