xtr_messenger.exception ¶
Every error this library raises.
All of them derive from :class:MessageBusError, so one except catches
anything the bus can go wrong with, and a narrower one handles a single
cause. Each carries the data a caller needs as typed attributes rather than
forcing a message to be parsed.
DelayedMessageHandlingError ¶
Bases: MessageBusError
One or more messages held back with a DispatchAfterCurrentBusStamp failed.
The message being handled succeeded — what it did stands — and then the messages its handling held back were dispatched, each in turn, every one tried even when an earlier one failed. The first failure is the cause.
Attributes:
-
envelope(Envelope) –The message whose handling held them back, as its handling left it.
-
failures(tuple[tuple[Envelope, Exception], ...]) –Each held-back message that failed, with what its dispatch raised, in the order dispatched.
-
errors(tuple[Exception, ...]) –What each failed dispatch raised, in the same order.
Record the message that succeeded and each held-back message that then failed.
HandlerSignatureError ¶
Bases: MessageBusError
A handler's parameters are not a shape the bus can call.
Record the handler and the parameters it declared.
HandlersFailedError ¶
Bases: MessageBusError
One or more handlers of a message raised, after every handler had its turn.
One failing handler does not keep the others from running: each is independent, and an unrelated one — an audit trail, a metric — must not go quiet because another broke. What every handler that failed raised is kept, by handler name, and the first of them is the cause.
Attributes:
-
envelope(Envelope) –The message as handling left it, with a :class:
~xtr_messenger.stamp.HandledStampfor every handler that succeeded. -
errors(Mapping[str, Exception]) –What each failed handler raised, by handler name, in the order the handlers ran; a name another failed handler already took is told apart as
name#2,name#3….
Record the envelope handling left and what each failed handler raised.
IncompatibleReceiversError ¶
Bases: MessageBusError
A transport that brings its own worker was asked to share it with receivers.
A broker that runs its own consume loop — taskiq does — cannot also drive a receiver registered with the application, and the library's own loop cannot drive the broker. Run them as separate workers.
Record the transports with their own worker, and the receivers asked alongside.
InvalidDsnError ¶
Bases: MessageBusError
A DSN that cannot be read into a transport selection.
The message shows the DSN redacted, never as written — an invalid DSN is exactly the kind whose credentials end up somewhere unexpected.
Record the DSN that could not be read, and why.
Without reason, the DSN is missing the scheme that selects its
transport — the commonest way one goes wrong.
InvalidMiddlewareArgumentsError ¶
Bases: MessageBusError
The configuration gives middleware arguments it does not take.
A configuration entry {name: {argument: value}} naming an argument
the middleware's builder does not take, or written in another shape, is
refused. With a container, an argument naming no constructor parameter
fails the build like any definition argument.
Attributes:
Record which middleware was misconfigured, and how.
InvalidTransportOptionError ¶
Bases: MessageBusError
A transport setting holds a value its adapter cannot use.
The setting may have come from the DSN's query string or from
options — both reach an adapter the same way, so neither is named.
Record the setting, the value it held, and what it should hold.
MessageBusError ¶
Bases: Exception
Base class for every error raised by this library.
Catch this to handle anything the bus can go wrong with; catch a subclass to handle one cause. Every subclass carries the data a caller needs as typed attributes and composes its own message from them.
MessageDecodingFailedError ¶
Bases: MessageBusError
An encoded envelope could not be turned back into a typed message.
Deliberately loud: a silently mis-decoded payload reaches the handler as the wrong shape and fails far from its cause.
Record why decoding failed, and for which message when known.
MessageEncodingFailedError ¶
Bases: MessageBusError
A message could not be turned into something a transport can carry.
Raised on the producer's side, before anything is sent — a message or a stamp holding a value the serializer cannot write, or would not read back exactly.
Record why encoding failed, and for which message.
MissingSerializerError ¶
Bases: MessageBusError
A transport has to write its messages, and was given nothing to write them with.
Raised where the transport is built, never when the application boots: a
process speaking only sync:// has no messages to write and needs no
serializer, so its absence only matters once a transport would use it.
Record which scheme needed the serializer, and where to give it one.
MixedDsnError ¶
Bases: MessageBusError
A worker was asked to serve transports that live on different brokers.
Record the conflicting DSNs, redacted — an attribute leaks as easily as a message.
NoFailureTransportError ¶
Bases: MessageBusError
No failure transport was named, and the configuration has no default one.
Record the failure transports there are to choose from.
NoHandlerForMessageError ¶
Bases: MessageBusError
No handler is registered for a message that reached handling.
In a worker this almost always means the module declaring the handler was never imported, so the registration decorator never ran. Failing is the safe reading: the alternative is acknowledging the message and losing it silently.
Record the unhandled type alongside the types that do have handlers.
NoSenderForMessageError ¶
Bases: MessageBusError
No transport is routed for a dispatched message type.
Raised before any transport is touched, so nothing was enqueued when it surfaces.
Record the unrouted type alongside the types that are routed.
NotConsumableError ¶
Bases: MessageBusError
A transport sends but cannot be consumed, and brings no worker either.
Reaching this means an adapter implements only the sending half and does
not implement
:class:~xtr_messenger.worker_providing_interface.WorkerProvidingInterface,
so there is nothing to run and no way to build it.
Record which transports were asked for, and their scheme.
UnknownMessageNameError ¶
Bases: MessageBusError
A wire message name could not be resolved back to a Python type.
Record the unresolvable name.
UnknownMiddlewareError ¶
Bases: MessageBusError
The configuration names middleware this process has nothing registered for.
Record what was named, and what a name may actually be.
UnknownTransportError ¶
Bases: MessageBusError
A route or a worker names a transport the configuration does not define.
Record what was asked for, and what is actually configured.
UnknownTransportOptionError ¶
Bases: MessageBusError
A transport DSN carries an option its adapter does not recognise.
Raised rather than ignored because an unrecognised option is always a mistake in configuration someone wrote by hand — a typo, or a setting meant for a different scheme. Dropping it silently leaves the transport running on defaults that nobody chose, which is the failure this exists to prevent.
Record the scheme, what it did not recognise, and what it accepts.
UnsupportedDsnError ¶
Bases: MessageBusError
No factory recognised a transport's DSN.
Record which transport could not be built, and from what.
UnsupportedStampError ¶
Bases: MessageBusError
A transport was handed a stamp it cannot act on.
A stamp a transport ignores is a silent failure: the caller asked for behaviour — a delay, say — and the message went out immediately with no sign the request was dropped. Raising names the stamp and the transport so the mismatch surfaces where it is made, not as a message that never behaved as asked.
Record which stamp could not be honoured, and by which transport.
UnsupportedTransportOperationError ¶
Bases: MessageBusError
A transport cannot list, count, find or receive, and was asked to.
What a transport can do beyond sending is what it implements: listing and
finding messages is
:class:~xtr_messenger.transport.receiver.ListableReceiverInterface,
receiving is
:class:~xtr_messenger.transport.receiver.ReceiverInterface.
Record the transport and what it was asked to do — "list messages", say.