Skip to content

common_reports.contracts.emails.message

The email message vocabulary — pure, frozen ADTs (zero SDK).

These describe the shape of an outbound (or parsed) email; the provider adapters (emails/providers/) translate them to/from smtplib / imaplib / the Gmail API, and emails/core.py assembles them into a MIME wire message.

Law (CONTEXT.md 1.2 / 1.9): this module imports nothing but stdlib — no pydantic effects, no SDK, no rendering. Frozen dataclasses: pure data.

Vocabulary: Address a single mailbox (name + addr-spec), with str/parse helpers Attachment one part to attach (path on disk OR in-memory bytes) EmailMessage the whole message: subject, html body, recipients, attachments, extra headers — the frozen contract a client/provider consumes

Classes

Address

A single email address, optionally with a display name.

Address("a@b.com") or Address("a@b.com", "Alice"). str(addr) renders the RFC 5322 form (Alice <a@b.com> or bare a@b.com).

__init__

def __init__(addr: str, name: str = '') -> None

Fields and properties declared here; inherited members belong to the bases above.

addr

addr: str

domain

Read-only property.

domain: str

The domain part of the address (after the @).

name

name: str = ''

formatted

def formatted() -> str

RFC 5322 rendering: Name <addr> or bare addr.

parse

@classmethod
def parse(value: AddressLike) -> Address

Coerce a str / (name, addr) tuple / Address into an Address.

parse_many

@classmethod
def parse_many(value: RecipientsLike) -> tuple[Address, ...]

Coerce None / str / “a,b” / iterable into a tuple of Addresses.

Attachment

One attachment part.

Either a path on disk (read at MIME-build time) or in-memory content bytes — exactly one of the two is set. filename defaults to the basename of path; maintype/subtype default to application/octet-stream (the AlgoReports MIMEApplication default) and are honored on the wire when set.

content_id makes the part INLINE: it is referenced from the HTML body as <img src="cid:{content_id}"> and rides in a multipart/related group instead of the attachment list.

__init__

def __init__(filename: str = '', path: Path | None = None, content: bytes | None = None, maintype: str = 'application', subtype: str = 'octet-stream', content_id: str | None = None) -> None

Fields and properties declared here; inherited members belong to the bases above.

content

content: bytes | None = None

content_id

content_id: str | None = None

filename

filename: str = ''

inline

Read-only property.

inline: bool

True when the part is referenced from the body (cid:), not listed.

maintype

maintype: str = 'application'

path

path: Path | None = None

subtype

subtype: str = 'octet-stream'

coerce

@classmethod
def coerce(value: AttachmentLike) -> Attachment

Coerce a path str / Path / (filename, bytes) tuple / Attachment.

from_bytes

@classmethod
def from_bytes(filename: str, content: bytes, maintype: str = 'application', subtype: str = 'octet-stream') -> Attachment

Attach in-memory content under filename.

from_path

@classmethod
def from_path(path: str | Path, filename: str | None = None) -> Attachment

Attach a file on disk (read lazily when the MIME message is built).

inline_image

@classmethod
def inline_image(content_id: str, content: bytes, *, subtype: str = 'png', filename: str | None = None) -> Attachment

An image referenced from the HTML as cid:{content_id} (e.g. a plot PNG).

read_bytes

def read_bytes() -> bytes

The raw bytes — from memory or by reading path.

EmailMessage

An email to send — the frozen contract a client/provider consumes.

A pure value object: it carries WHAT to send (subject, html body, recipients, attachments, extra headers). It does NOT carry the From address or credentials — those come from the transport EmailContext / config at send time, so the same message can be sent from any account.

to / cc / bcc are tuples of :class:Address; use the :meth:create smart constructor to accept the looser str / list forms.

Recipient privacy: by default (disclose_recipients=False) NO To/Cc header is written — every recipient is delivered privately (SMTP envelope; a stripped Bcc on header-routed APIs), so a report sent to many people never reveals the list. disclose_recipients=True writes standard visible To/Cc headers; Bcc is never visible either way.

__init__

def __init__(subject: str = '', html: str = '', to: tuple[Address, ...] = (), cc: tuple[Address, ...] = (), bcc: tuple[Address, ...] = (), attachments: tuple[Attachment, ...] = (), headers: Mapping[str, str] = (lambda: _EMPTY_MAP)(), reply_to: Address | None = None, text: str | None = None, message_id: str | None = None, disclose_recipients: bool = False) -> None

Fields and properties declared here; inherited members belong to the bases above.

all_recipients

Read-only property.

all_recipients: tuple[Address, ...]

The flattened To + Cc + Bcc envelope recipient list.

attachments

attachments: tuple[Attachment, ...] = ()

bcc

bcc: tuple[Address, ...] = ()

cc

cc: tuple[Address, ...] = ()

disclose_recipients

disclose_recipients: bool = False

headers

headers: Mapping[str, str] = field(default_factory=(lambda: _EMPTY_MAP))

html

html: str = ''

message_id

message_id: str | None = None

reply_to

reply_to: Address | None = None

subject

subject: str = ''

text

text: str | None = None

to

to: tuple[Address, ...] = ()

create

@classmethod
def create(subject: str = '', html: str = '', to: RecipientsLike = None, cc: RecipientsLike = None, bcc: RecipientsLike = None, attachments: Iterable[AttachmentLike] | None = None, headers: Mapping[str, str] | None = None, reply_to: AddressLike | None = None, text: str | None = None, message_id: str | None = None, disclose_recipients: bool = False) -> EmailMessage

Build an EmailMessage, coercing the loose recipient/attachment forms.

recipient_addrs

def recipient_addrs() -> list[str]

The bare addr-specs of every envelope recipient (for to_addrs=).

with_headers

def with_headers(**extra: str) -> EmailMessage

Frozen replace merging additional headers.

with_recipients

def with_recipients(to: RecipientsLike) -> EmailMessage

Frozen replace of the to list (provider routing / defaults).

Types and values

AddressLike

AddressLike = Union[str, 'Address', tuple]

AttachmentLike

AttachmentLike = Union[str, Path, bytes, 'Attachment', tuple]

RecipientsLike

RecipientsLike = Union[str, 'Address', Iterable[Union[str, 'Address', tuple]], None]