Skip to content
Back to top
View this page

# Event system

Generic library provides `generic.event` module which helps you implement event systems in your application. By event system I mean an API for subscribing for some types of events and to handle those events so previously subscribed handlers are being executed.

## Basic usage

First you need to describe event types you want to use in your application, `generic.event` dispatches events to corresponding handlers by inspecting events’ types, so it’s natural to model those as classes:

    >>> class CommentAdded(object):
    ...   def __init__(self, post_id, comment):
    ...     self.post_id = post_id
    ...     self.comment = comment

Now you want to register handler for your event type:

    >>> from generic.event import Manager

    >>> manager = Manager()

    >>> @manager.subscriber(CommentAdded)
    ... def print_comment(ev):
    ...   print(f"Got new comment: {ev.comment}")

Then you just call `generic.event.handle` function with `CommentAdded` instance as its argument:

    >>> manager.handle(CommentAdded(167, "Hello!"))
    Got new comment: Hello!

This is how it works.

## Event inheritance

## Using per-application event API

## API reference

class generic.event.Manager

  Event manager.

  Provides API for subscribing for and firing events.

  handle(event: object) → None

    Fire `event`

    All subscribers will be executed with no determined order. If a handler raises an exceptions, an ExceptionGroup will be raised containing all raised exceptions.

  subscribe(handler: Callable[[object], None], event_type: Type[object]) → None

    Subscribe `handler` to specified `event_type`

  subscriber(event_type: Type[object]) → Callable[[Callable[[object], None]], Callable[[object], None]]

    Decorator for subscribing handlers.

    Works like this:

        >>> mymanager = Manager()
        >>> class MyEvent():
        ...     pass
        >>> @mymanager.subscriber(MyEvent)
        ... def mysubscriber(evt):
        ...     # handle event
        ...     return

        >>> mymanager.handle(MyEvent())

  unsubscribe(handler: Callable[[object], None], event_type: Type[object]) → None

    Unsubscribe `handler` from `event_type`