Features

This section describes all features that are shipped with this package.

Scenario Features

class balderhub.smtp.lib.scenario_features.SmtpServerConfig(**kwargs)

Bases: Feature

Configuration feature exposing the SMTP server’s network coordinates.

The default values point to a local SMTP server on the standard port. Subclasses can override host and port to target a different server.

property host: Return the hostname or IP address of the SMTP server.

property port: Return the TCP port the SMTP server is listening on.

SMTP Server

class balderhub.smtp.lib.scenario_features.SmtpServerFeature(**kwargs)

Bases: Feature

Abstract scenario feature describing an SMTP server used during a test.

Concrete setup features (e.g. AiosmtpdServerFeature) must implement the lifecycle methods (start(), shutdown(), is_running()) as well as the outbox-related methods (get_outbox(), clear_outbox()).

is_running() → bool: Return True if the SMTP server is currently running and reachable.

shutdown(): Shut the SMTP server down and release any held resources.

start(): Start the SMTP server so that it can accept incoming connections.

class balderhub.smtp.lib.scenario_features.SmtpReadableServerFeature(**kwargs)

Bases: SmtpServerFeature

Provides functionality for managing an SMTP server where it is possible to read the outgoing mails.

This class is an extension of the balderhub.smtp.lib.scenario_features.SmtpServerFeature and provides additional methods to interact with emails received by the server, allowing the retrieval and management of its outbox. It also includes utility methods for restarting and clearing the server’s state.

class Message(mail: EmailDataMessage, received_timestamp: datetime)

Bases: object

Bundle of an EmailDataMessage together with the timestamp it was received.

clear_outbox(): Remove all received messages from the server’s outbox.

fixt_reboot_and_clear_outbox(): Balder fixture that reboots the SMTP server and clears its outbox

get_outbox(for_mail_address: str | None = None) → list[balderhub.smtp.lib.scenario_features.smtp_readable_server_feature.SmtpReadableServerFeature.Message]

Return all emails received by the server.

Parameters:: for_mail_address – If provided, only messages addressed to this email address (matched against the To header) are returned.
Returns:: A list of Message objects representing the received mails.

SMTP Client

class balderhub.smtp.lib.scenario_features.SmtpClientFeature(**kwargs)

Bases: Feature

Abstract scenario feature describing an SMTP client capable of sending emails.

Concrete setup features (e.g. SmtplibClientFeature) have to provide an actual implementation of send_mail().

send_mail(message: EmailDataMessage, mail_from: str | None = None, mail_to: list[str] | None = None)

Send the given EmailDataMessage via SMTP.

Parameters:

message – The fully prepared email to be sent.
mail_from – Optional envelope sender address. If None, the address of message.from_address is used by the underlying implementation.
mail_to – Optional list of envelope recipient addresses. If None, the recipients are derived from the To/Cc/Bcc headers of message.

Setup Features

Server Implementations

class balderhub.smtp.lib.setup_features.AiosmtpdServerFeature(**kwargs)

Bases: SmtpReadableServerFeature

SMTP server setup feature backed by the aiosmtpd library.

The feature spins up a local aiosmtpd.controller.Controller that listens on the host/port provided through SmtpServerConfig. Every received message is parsed into an EmailDataMessage and stored in an in-memory outbox that can be inspected from tests.

clear_outbox(): Remove all received messages from the server’s outbox.

get_outbox(for_mail_address: str | None = None) → list[balderhub.smtp.lib.scenario_features.smtp_readable_server_feature.SmtpReadableServerFeature.Message]

Return all emails received by the server.

Parameters:: for_mail_address – If provided, only messages addressed to this email address (matched against the To header) are returned.
Returns:: A list of Message objects representing the received mails.

property hostname: str

Returns:: configured host name within the aiosmtpd server controller

is_running() → bool: Return True if the SMTP server is currently running and reachable.

property port: int

Returns:: configured port within the aiosmtpd server controller

property ready_timeout_sec

Returns:: configured timeout within the aiosmtpd server controller

shutdown(): Shut the SMTP server down and release any held resources.

start(): Start the SMTP server so that it can accept incoming connections.

Client Implementations

class balderhub.smtp.lib.setup_features.SmtplibClientFeature(**kwargs)

Bases: SmtpClientFeature

SMTP client setup feature implemented on top of the standard smtplib module.

The feature requires a connected SmtpServer balder.VDevice exposing a SmtpServerConfig, which provides the host/port the client should connect to.

class SmtpServer

Bases: VDevice

VDevice representing the SMTP server the client connects to.

send_mail(message: EmailDataMessage, mail_from: str | None = None, mail_to: list[str] | None = None)

Send the given EmailDataMessage via SMTP.

Parameters:

message – The fully prepared email to be sent.
mail_from – Optional envelope sender address. If None, the address of message.from_address is used by the underlying implementation.
mail_to – Optional list of envelope recipient addresses. If None, the recipients are derived from the To/Cc/Bcc headers of message.

SMTP-Server Message Reader

The following features are implementation of the balderhub.email.lib.scenario_features.EmailReaderFeature.

class balderhub.smtp.lib.setup_features.LocalSmtpReader(**kwargs)

Bases: EmailReaderFeature

Handles reading emails from a local SMTP servers’ outbox.

This class provides functionality to connect to a local SMTP server and retrieve emails from its outbox. It relies on the SmtpServerFeature to interact with the SMTP server.

get_mails() → list[balderhub.email.lib.utils.email_data_message.EmailDataMessage]

Returns:: returns all existing emails

server = <balderhub.smtp.lib.scenario_features.smtp_readable_server_feature.SmtpReadableServerFeature object>: feature reference to readable smtp server

class balderhub.smtp.lib.setup_features.ProxySmtpReader(**kwargs)

Bases: EmailReaderFeature

Represents a proxy SMTP reader, that can be used if the readbale-smtp server does not belong to this device and is part of a remote device.

class SmtpServer

Bases: VDevice

VDevice representing SMTP server

server = <balderhub.smtp.lib.scenario_features.smtp_readable_server_feature.SmtpReadableServerFeature object>: the readable server feature of the smtp server

get_mails() → list[balderhub.email.lib.utils.email_data_message.EmailDataMessage]

Returns:: returns all existing emails