xtr_mailer.exception ¶
The errors the mailer raises, every one a :class:MailerError.
HttpTransportError ¶
Bases: TransportError
A provider's API answered an email with a refusal.
It carries the response, so a caller can read what the provider said beyond the message.
Attributes:
-
response(HttpResponseInterface) –What the provider answered with.
Record why the provider refused the email and what it answered.
Parameters:
-
message(str) –Why the send failed, in the provider's words where it gave any.
-
response(HttpResponseInterface) –What the provider answered with.
-
code(int, default:0) –The status the provider answered with,
0when not given.
IncompleteDsnError ¶
Bases: InvalidArgumentError
A DSN parses, but lacks a part its transport cannot work without — a user, a password.
The message names the missing part only, never the DSN, which carries credentials.
InvalidArgumentError ¶
Bases: MailerError, ValueError
A value handed to this library cannot be used: a malformed DSN, an envelope with no sender.
Also a :class:ValueError, so code that already guards against a bad value
catches it without knowing this library exists.
LogicError ¶
Bases: MailerError, RuntimeError
This library was used in a way that cannot work, whatever the email carries.
A DSN scheme no installed factory serves, a transport handed an email it was never built for: each is a mistake in the code or the configuration, so retrying it changes nothing.
MailerError ¶
Bases: Exception
Something an email could not be sent through — catch this to catch them all.
MailerRuntimeError ¶
Bases: MailerError, RuntimeError
Something an email depends on failed while it was sent — a server, a process.
The input was fine and the code is fine; the world did not cooperate. Raising one out of a message handler is what makes a message bus retry the send.
TransportError ¶
Bases: MailerRuntimeError
A server could not be reached, or refused an email.
It is the one error a round-robin or failover transport takes as a sign that a transport is down: anything else is a mistake that another transport would make too.
Attributes:
-
code(int) –The reply code the server refused with — an SMTP reply code, an HTTP status — or
0when there was none. SMTP transports tell a refusal from a dropped connection by it. -
debug(str) –The protocol transcript up to the failure, so a caller can see what was said. Authentication exchanges are kept out of it: it never carries credentials.
Record why the email could not be handed over.
Parameters:
-
message(str) –Why the transport failed.
-
code(int, default:0) –The reply code the server refused with,
0when there was none.
append_debug ¶
Add debug to the transcript.
The error is raised from deep inside a transport, which only knows its own part of the exchange; each layer it passes through appends what it saw.
UnexpectedResponseError ¶
Bases: TransportError
An SMTP server replied to a command with a code the command does not accept.
Its :attr:code is the reply code the server sent: an SMTP transport resets
the session after a refusal, but not after 421, the server closing the
connection, and authentication tries the next mechanism after one.
UnsupportedSchemeError ¶
Bases: LogicError
No factory serves a DSN's scheme.
The common cause is a provider library that is not installed, so a scheme a first-party provider library serves is answered with the command that installs it — this package's extra named after the provider, quoted so a shell does not read its brackets. Any other scheme is answered with the schemes that are supported, when the caller knows them. The message names the scheme only: never the DSN, which carries credentials — and shows it escaped and cut short, as it is whatever the application's configuration says.
Attributes:
-
scheme(str) –The scheme no factory serves.
-
name(str | None) –The mailer transport that was being built, or
None. -
supported(tuple[str, ...]) –The schemes that are supported there.
Explain why scheme has no transport.
Takes the scheme rather than the DSN, so nothing that carries credentials ever reaches an error.
Parameters:
-
scheme(str) –The scheme of the DSN no factory serves.
-
name(str | None, default:None) –The transport being built, named in the message with
supported. -
supported(Sequence[str], default:()) –The schemes that are supported there.