An event is an object broadcast by the :app:`Pyramid` framework at interesting points during the lifetime of an application. You don't need to use events in order to create most :app:`Pyramid` applications, but they can be useful when you want to perform slightly advanced operations. For example, subscribing to an event can allow you to run some code as the result of every new request.
Events in :app:`Pyramid` are always broadcast by the framework. However, they only become useful when you register a subscriber. A subscriber is a function that accepts a single argument named event:
The above is a subscriber that simply prints the event to the console when it's called.
The mere existence of a subscriber function, however, is not sufficient to arrange for it to be called. To arrange for the subscriber to be called, you'll need to use the :meth:`pyramid.config.Configurator.add_subscriber` method or you'll need to use the :func:`pyramid.events.subscriber` decorator to decorate a function found via a :term:`scan`.
Configuring an Event Listener Imperatively
You can imperatively configure a subscriber function to be called for some event type via the :meth:`~pyramid.config.Configurator.add_subscriber` method:
The first argument to :meth:`~pyramid.config.Configurator.add_subscriber` is the subscriber function (or a :term:`dotted Python name` which refers to a subscriber callable); the second argument is the event type.
Configuring an Event Listener Using a Decorator
You can configure a subscriber function to be called for some event type via the :func:`pyramid.events.subscriber` function.
Either of the above registration examples implies that every time the
:app:`Pyramid` framework emits an event object that supplies an
:class:`pyramid.events.NewRequest` interface, the
will be called with an event object.
As you can see, a subscription is made in terms of a class (such as :class:`pyramid.events.NewResponse`). The event object sent to a subscriber will always be an object that possesses an :term:`interface`. For :class:`pyramid.events.NewResponse`, that interface is :class:`pyramid.interfaces.INewResponse`. The interface documentation provides information about available attributes and methods of the event objects.
The return value of a subscriber function is ignored. Subscribers to the same event type are not guaranteed to be called in any particular order relative to each other.
If you create event listener functions in a
subscribers.py file in
your application like so:
You may configure these functions to be called at the appropriate times by adding the following code to your application's configuration startup:
Either mechanism causes the functions in
subscribers.py to be
registered as event subscribers. Under this configuration, when the
application is run, each time a new request or response is detected, a
message will be printed to the console.
Each of our subscriber functions accepts an
event object and
prints an attribute of the event object. This begs the question: how
can we know which attributes a particular event has?
We know that :class:`pyramid.events.NewRequest` event objects have a
request attribute, which is a :term:`request` object, because the
interface defined at :class:`pyramid.interfaces.INewRequest` says it must.
Likewise, we know that :class:`pyramid.interfaces.NewResponse` events have a
response attribute, which is a response object constructed by your
application, because the interface defined at
:class:`pyramid.interfaces.INewResponse` says it must
(:class:`pyramid.events.NewResponse` objects also have a
Creating Your Own Events
In addition to using the events that the Pyramid framework creates, you can create your own events for use in your application. This can be useful to decouple parts of your application.
For example, suppose your application has to do many things when a new document is created. Rather than putting all this logic in the view that creates the document, you can create the document in your view and then fire a custom event. Subscribers to the custom event can take other actions, such as indexing the document, sending email, or sending a message to a remote system.
An event is simply an object. There are no required attributes or method for your custom events. In general, your events should keep track of the information that subscribers will need. Here are some example custom event classes:
Some Pyramid applications choose to define custom events classes in an
You can subscribe to custom events in the same way that you subscribe to Pyramid events -- either imperatively or with a decorator. You can also use custom events with :ref:`subscriber predicates <subscriber_predicates>`. Here's an example of subscribing to a custom event with a decorator:
The above example assumes that the application defines a
DocCreated event class and an
To fire your custom events use the
:meth:`pyramid.registry.Registry.notify` method, which is most often
request.registry.notify. For example:
This example view will notify all subscribers to the custom
Note that when you fire an event, all subscribers are run synchronously so it's generally not a good idea to create event handlers that may take a long time to run. Although event handlers could be used as a central place to spawn tasks on your own message queues.