ORIONIS API REFERENCE

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

class documentation

Build independent chains; every fluent call returns a new operation.

A chain never builds a Mailable, renders, reads attachments, or resolves a transport: those steps belong to the asynchronous terminals. Deriving a chain copies its immutable options, so concurrent branches never share recipients.

Method __init__ Bind an immutable declaration to the manager's delivery pipeline.
Method _derive Detach a configurator's current snapshot into a new chain.
Async Method _sendDirect Invoke one callback, freeze its declaration, and deliver.
Async Method _sendMailable Merge reusable declarations with explicit fluent options.
Method attach Append a deferred storage attachment on an independent chain.
Method bcc Append hidden recipients on an independent chain.
Method cc Append carbon-copy recipients on an independent chain.
Method fromAddress Replace the sender on a new independent chain.
Async Method html Send literal HTML through the shared preparation pipeline.
Method mailer Select a mailer on an independent derived chain.
Async Method raw Send literal plain text through the shared preparation pipeline.
Method replyTo Append Reply-To mailboxes on an independent chain.
Async Method send Send a reusable Mailable, an HTML view, or explicit Content.
Method subject Replace the subject on an independent chain.
Method to Append visible recipients on an independent chain.
Class Variable __slots__ Declare the instance attribute slots reserved by this class.
Instance Variable _delivery Shared preparation and transport entry point.
Instance Variable _mailable_builder Optional application-container resolver for Mailable classes.
Instance Variable _options Immutable explicit options for this chain.
def __init__(self, delivery: Delivery, options: MailOptions | None = None, mailable_builder: Callable[[type[Mailable]], Awaitable[Mailable]] | None = None): (source)

Bind an immutable declaration to the manager's delivery pipeline.

Parameters
delivery:orionis.mail.types.DeliveryShared preparation and transport entry point.
options:orionis.mail.entities.MailOptions | NoneImmutable explicit options for this chain.
mailable_builder:Callable[[type[Mailable]], Awaitable[Mailable]] | NoneOptional application-container resolver for Mailable classes.
Returns
NoneInitialize a chain without performing I/O.
def _derive(self, message: Message) -> PendingMail: (source)

Detach a configurator's current snapshot into a new chain.

Parameters
message:orionis.mail.MessageTemporary synchronous configurator.
Returns
orionis.mail.PendingMailIndependent operation with no render or transport side effects.
async def _sendDirect(self, content: Content, callback: object) -> MailResult: (source)

Invoke one callback, freeze its declaration, and deliver.

Parameters
content:orionis.mail.entities.ContentAlready validated content declaration.
callback:objectConfigurator invoked exactly once and awaited when needed.
Returns
orionis.mail.entities.MailResultShared delivery outcome.
Raises
orionis.mail.exceptions.MailCompositionExceptionIf a callback fails or returns anything other than None or itself.
async def _sendMailable(self, mailable: Mailable) -> MailResult: (source)

Merge reusable declarations with explicit fluent options.

Parameters
mailable:orionis.mail.MailableReusable synchronous declaration, never modified by sending.
Returns
orionis.mail.entities.MailResultShared delivery outcome.
Raises
orionis.mail.exceptions.MailCompositionExceptionIf declaration methods fail or do not return their contracted types.
def attach(self, attachment: Attachment) -> PendingMail: (source)

Append a deferred storage attachment on an independent chain.

Parameters
attachment:orionis.mail.entities.AttachmentStorage attachment declaration.
Returns
orionis.mail.PendingMailDerived operation retaining previous attachments.
def bcc(self, addresses: Recipients, name: str | None = None) -> PendingMail: (source)

Append hidden recipients on an independent chain.

Parameters
addresses:orionis.mail.types.RecipientsOne mailbox or a list/tuple of mailboxes.
name:str | NoneOptional name for a single string mailbox only.
Returns
orionis.mail.PendingMailDerived operation retaining previous recipients.
def cc(self, addresses: Recipients, name: str | None = None) -> PendingMail: (source)

Append carbon-copy recipients on an independent chain.

Parameters
addresses:orionis.mail.types.RecipientsOne mailbox or a list/tuple of mailboxes.
name:str | NoneOptional name for a single string mailbox only.
Returns
orionis.mail.PendingMailDerived operation retaining previous recipients.
def fromAddress(self, address: str | Address, name: str | None = None) -> PendingMail: (source)

Replace the sender on a new independent chain.

Parameters
address:str | orionis.mail.entities.AddressExactly one sender mailbox.
name:str | NoneOptional name for a string mailbox only.
Returns
orionis.mail.PendingMailDerived operation with an explicit From and transport sender.
async def html(self, html: str, callback: MessageCallback | None = None) -> MailResult: (source)

Send literal HTML through the shared preparation pipeline.

Parameters
html:strLiteral HTML, never rendered as a template.
callback:orionis.mail.types.MessageCallback | NoneOptional sync or async operation-local configurator.
Returns
orionis.mail.entities.MailResultTransport outcome.
Raises
orionis.mail.exceptions.MailCompositionExceptionIf the body, callback, or resulting envelope is invalid.
orionis.mail.exceptions.MailExceptionIf preparation or transport fails.
def mailer(self, name: str) -> PendingMail: (source)

Select a mailer on an independent derived chain.

Parameters
name:strCentral configuration name, not a driver name.
Returns
orionis.mail.PendingMailA new operation; resolution remains deferred until sending.
Raises
orionis.mail.exceptions.MailConfigurationExceptionIf the name is not a non-empty string.
async def raw(self, text: str, callback: MessageCallback | None = None) -> MailResult: (source)

Send literal plain text through the shared preparation pipeline.

Parameters
text:strLiteral text, never rendered as a template.
callback:orionis.mail.types.MessageCallback | NoneOptional sync or async operation-local configurator.
Returns
orionis.mail.entities.MailResultTransport outcome.
Raises
orionis.mail.exceptions.MailCompositionExceptionIf the body, callback, or resulting envelope is invalid.
orionis.mail.exceptions.MailExceptionIf preparation or transport fails.
def replyTo(self, addresses: Recipients, name: str | None = None) -> PendingMail: (source)

Append Reply-To mailboxes on an independent chain.

Parameters
addresses:orionis.mail.types.RecipientsOne mailbox or a list/tuple of mailboxes.
name:str | NoneOptional name for a single string mailbox only.
Returns
orionis.mail.PendingMailDerived operation retaining previous reply destinations.
@overload
async def send(self, mailable: Mailable | type[Mailable], /) -> MailResult:
@overload
async def send(self, view: str, /, data: Mapping[str, object] | None = None, callback: MessageCallback | None = None) -> MailResult:
@overload
async def send(self, content: Content, /, *, callback: MessageCallback | None = None) -> MailResult:
(source)

Send a reusable Mailable, an HTML view, or explicit Content.

Parameters
value:Mailable | type[Mailable] | str | ContentDeclaration, resolvable Mailable class, or HTML view identifier.
data:collections.abc.Mapping[str, object] | NoneView context, accepted only when value is a string.
callback:orionis.mail.types.MessageCallback | NoneOperation-local configurator, not accepted for a Mailable.
Returns
orionis.mail.entities.MailResultConfirmed SMTP acceptance or file publication result.
Raises
orionis.mail.exceptions.MailCompositionExceptionIf arguments, container resolution, declarations, callbacks, or content are invalid.
orionis.mail.exceptions.MailExceptionIf preparation or transport fails.
def subject(self, value: str) -> PendingMail: (source)

Replace the subject on an independent chain.

Parameters
value:strLiteral subject, possibly empty.
Returns
orionis.mail.PendingMailDerived operation with an explicit subject.
def to(self, addresses: Recipients, name: str | None = None) -> PendingMail: (source)

Append visible recipients on an independent chain.

Parameters
addresses:orionis.mail.types.RecipientsOne mailbox or a list/tuple of mailboxes.
name:str | NoneOptional name for a single string mailbox only.
Returns
orionis.mail.PendingMailDerived operation retaining previous recipients.
__slots__: tuple[str, ...] = (source)

Declare the instance attribute slots reserved by this class.

_delivery = (source)

Shared preparation and transport entry point.

_mailable_builder = (source)

Optional application-container resolver for Mailable classes.

_options = (source)

Immutable explicit options for this chain.