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 = '') -> NoneFields and properties declared here; inherited members belong to the bases above.
addr
addr: strdomain
Read-only property.
domain: strThe domain part of the address (after the @).
name
name: str = ''formatted
def formatted() -> strRFC 5322 rendering: Name <addr> or bare addr.
parse
@classmethoddef parse(value: AddressLike) -> AddressCoerce a str / (name, addr) tuple / Address into an Address.
parse_many
@classmethoddef 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) -> NoneFields and properties declared here; inherited members belong to the bases above.
content
content: bytes | None = Nonecontent_id
content_id: str | None = Nonefilename
filename: str = ''inline
Read-only property.
inline: boolTrue when the part is referenced from the body (cid:), not listed.
maintype
maintype: str = 'application'path
path: Path | None = Nonesubtype
subtype: str = 'octet-stream'coerce
@classmethoddef coerce(value: AttachmentLike) -> AttachmentCoerce a path str / Path / (filename, bytes) tuple / Attachment.
from_bytes
@classmethoddef from_bytes(filename: str, content: bytes, maintype: str = 'application', subtype: str = 'octet-stream') -> AttachmentAttach in-memory content under filename.
from_path
@classmethoddef from_path(path: str | Path, filename: str | None = None) -> AttachmentAttach a file on disk (read lazily when the MIME message is built).
inline_image
@classmethoddef inline_image(content_id: str, content: bytes, *, subtype: str = 'png', filename: str | None = None) -> AttachmentAn image referenced from the HTML as cid:{content_id} (e.g. a plot PNG).
read_bytes
def read_bytes() -> bytesThe 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) -> NoneFields 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 = Falseheaders
headers: Mapping[str, str] = field(default_factory=(lambda: _EMPTY_MAP))html
html: str = ''message_id
message_id: str | None = Nonereply_to
reply_to: Address | None = Nonesubject
subject: str = ''text
text: str | None = Noneto
to: tuple[Address, ...] = ()create
@classmethoddef 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) -> EmailMessageBuild 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) -> EmailMessageFrozen replace merging additional headers.
with_recipients
def with_recipients(to: RecipientsLike) -> EmailMessageFrozen 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]