Skip to content

xtr_event_dispatcher.exception

Every error this library raises.

All of them derive from :class:EventDispatcherError, so one except catches anything dispatching can go wrong with, and a narrower one handles a single cause. An exception raised by a listener is not one of them: it reaches the code that dispatched the event unchanged.

ArgumentNotFoundError

ArgumentNotFoundError(key: str)

Bases: EventDispatcherError, KeyError

A :class:~xtr_event_dispatcher.generic_event.GenericEvent has no such argument.

Also a :class:KeyError, since a generic event is read like a mapping: event["name"] raising it is what any mapping would do.

Attributes:

  • key (str) –

    The argument that was asked for.

Record which argument was asked for.

BadMethodCallError

BadMethodCallError(method: str)

Bases: EventDispatcherError, RuntimeError

A dispatcher was asked to add or remove a listener, and it cannot be changed.

Raised by :class:~xtr_event_dispatcher.immutable_event_dispatcher.ImmutableEventDispatcher, which hands its dispatcher out for dispatching only. A listener that must live for a while only belongs on a :class:~xtr_event_dispatcher.scoped_event_dispatcher.ScopedEventDispatcher wrapping it.

Attributes:

  • method (str) –

    The method that was called.

Record which method was called.

EventDispatcherError

Bases: Exception

Base class for every error raised by this library.

Catch this to handle anything dispatching 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.

InvalidArgumentError

InvalidArgumentError(reason: str)

Bases: EventDispatcherError, ValueError

A dispatcher, or its configuration, was given an argument it cannot work with.

Also a :class:ValueError, so code already guarding its configuration with except ValueError keeps working.

Attributes:

  • reason (str) –

    What is wrong with the argument.

Record what is wrong with the argument.

InvalidListenerError

InvalidListenerError(listener: str, reason: str)

Bases: EventDispatcherError, ValueError

A listener declared with @as_event_listener, or tagged by hand, cannot be registered.

Raised while the container is built, never on the first event: an event that cannot be told from the listener's signature, a method the class does not have, a dispatcher nobody configured, ordering constraints that contradict each other.

Attributes:

  • listener (str) –

    The listener, as "module:Qualified.name".

  • reason (str) –

    What is wrong with it.

Record which listener is wrong, and why.

InvalidSubscriberError

InvalidSubscriberError(subscriber: str, event_name: str | None, reason: str)

Bases: EventDispatcherError, ValueError

A subscriber's get_subscribed_events() cannot be registered as it stands.

Raised when the subscriber is added, before any of its listeners is: a declaration of an unknown shape, a method the subscriber does not have, or ordering constraints a dispatcher on its own cannot honour.

Attributes:

  • subscriber (str) –

    The subscriber's qualified class name.

  • event_name (str | None) –

    The event whose declaration is wrong; None when what is wrong is not about one event.

  • reason (str) –

    What is wrong with it.

Record which declaration is wrong, and why.

ListenerSignatureError

ListenerSignatureError(listener: str, signature: str)

Bases: EventDispatcherError, TypeError

A callable cannot be called with an event, its name and the dispatcher.

A dispatcher passes at most those three arguments, by position, so a listener may take up to three positional parameters and requires nothing else. Raised when the listener is added — or, for a lazy one, when it is first built — rather than when the event it waits for arrives.

Attributes:

  • listener (str) –

    The listener's qualified name.

  • signature (str) –

    Its parameters, as written.

Record which listener cannot be called, and its parameters.