From 9d0643063615ef7ce54fe062461c5dbf92cde3b4 Mon Sep 17 00:00:00 2001 From: Amos Latteier Date: Mon, 12 Aug 2013 16:04:00 -0400 Subject: Add documentation for creating and firing custom events. See issue #982. --- docs/narr/events.rst | 79 ++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 77 insertions(+), 2 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/events.rst b/docs/narr/events.rst index 929208083..6065b67fd 100644 --- a/docs/narr/events.rst +++ b/docs/narr/events.rst @@ -53,7 +53,7 @@ method (see also :term:`Configurator`): from subscribers import mysubscriber - # "config" below is assumed to be an instance of a + # "config" below is assumed to be an instance of a # pyramid.config.Configurator object config.add_subscriber(mysubscriber, NewRequest) @@ -113,7 +113,7 @@ your application like so: :linenos: def handle_new_request(event): - print 'request', event.request + print 'request', event.request def handle_new_response(event): print 'response', event.response @@ -150,3 +150,78 @@ application, because the interface defined at :class:`pyramid.interfaces.INewResponse` says it must (:class:`pyramid.events.NewResponse` objects also have a ``request``). +.. _custom_events: + +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: + +.. code-block:: python + :linenos: + + class DocCreated(object): + def __init__(self, doc, request): + self.doc = doc + self.request = request + + class UserEvent(object): + def __init__(self, user): + self.user = user + + class UserLoggedIn(UserEvent): + pass + +Some Pyramid applications choose to define custom events classes in an +``events`` module. + +You can subscribe to custom events in the same way what you subscribe +to Pyramid events -- either imperatively or with a decorator. Here's +an example of subscribing to a custom event with a decorator: + +.. code-block:: python + :linenos: + + from pyramid.events import subscriber + from .events import DocCreated + from .index import index_doc + + @subscriber(DocCreated) + def index_doc(event): + # index the document using our application's index_doc function + index_doc(event.doc, event.request) + +The above example assumes that the application defines a +``DocCreated`` event class and an ``index_doc`` function. + +To fire your custom events use the +:meth:`pyramid.registry.Registry.notify` method, which is most often +accessed as ``request.registry.notify``. For example: + +.. code-block:: python + :linenos: + + from .events import DocCreated + + def new_doc_view(request): + doc = MyDoc() + event = DocCreated(doc, request) + request.registry.notify(event) + return {'document': doc} + +This example view will notify all subscribers to the custom +``DocCreated`` event. -- cgit v1.2.3 From 387051c91d5a3844db5fa0938a19c19f5881e056 Mon Sep 17 00:00:00 2001 From: Amos Latteier Date: Mon, 12 Aug 2013 16:27:41 -0400 Subject: Fix tab/space snafu. --- docs/narr/events.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/events.rst b/docs/narr/events.rst index 6065b67fd..702618843 100644 --- a/docs/narr/events.rst +++ b/docs/narr/events.rst @@ -177,7 +177,7 @@ example custom event classes: class DocCreated(object): def __init__(self, doc, request): self.doc = doc - self.request = request + self.request = request class UserEvent(object): def __init__(self, user): @@ -219,9 +219,9 @@ accessed as ``request.registry.notify``. For example: def new_doc_view(request): doc = MyDoc() - event = DocCreated(doc, request) - request.registry.notify(event) - return {'document': doc} + event = DocCreated(doc, request) + request.registry.notify(event) + return {'document': doc} This example view will notify all subscribers to the custom ``DocCreated`` event. -- cgit v1.2.3 From 29ab2b964164844daa012c3e80d276f49ccbe217 Mon Sep 17 00:00:00 2001 From: Amos Latteier Date: Mon, 12 Aug 2013 16:45:11 -0400 Subject: Minor fixes suggested by @tshepang and @mmerickel thanks! --- docs/narr/events.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/events.rst b/docs/narr/events.rst index 702618843..485247afc 100644 --- a/docs/narr/events.rst +++ b/docs/narr/events.rst @@ -77,7 +77,7 @@ type via the :func:`pyramid.events.subscriber` function. @subscriber(NewRequest) def mysubscriber(event): - event.request.foo = 1 + event.request.foo = 1 When the :func:`~pyramid.events.subscriber` decorator is used a :term:`scan` must be performed against the package containing the @@ -189,7 +189,7 @@ example custom event classes: Some Pyramid applications choose to define custom events classes in an ``events`` module. -You can subscribe to custom events in the same way what you subscribe +You can subscribe to custom events in the same way that you subscribe to Pyramid events -- either imperatively or with a decorator. Here's an example of subscribing to a custom event with a decorator: @@ -225,3 +225,7 @@ accessed as ``request.registry.notify``. For example: This example view will notify all subscribers to the custom ``DocCreated`` event. + +Note that when you fire an event, all subscribers are run +synchronously on the current thread. So it's generally not a good idea +to create event handlers that may take a long time to run. -- cgit v1.2.3 From 970dfae46bb398e862f57d89c3f6efe10c45e715 Mon Sep 17 00:00:00 2001 From: Amos Latteier Date: Mon, 12 Aug 2013 17:00:29 -0400 Subject: Mention subscriber predicates. --- docs/narr/events.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/events.rst b/docs/narr/events.rst index 485247afc..5004a1787 100644 --- a/docs/narr/events.rst +++ b/docs/narr/events.rst @@ -190,8 +190,10 @@ Some Pyramid applications choose to define custom events classes in an ``events`` module. You can subscribe to custom events in the same way that you subscribe -to Pyramid events -- either imperatively or with a decorator. Here's -an example of subscribing to a custom event with a decorator: +to Pyramid events -- either imperatively or with a decorator. You can +also use custom events with :ref:`subscriber predicates +`. Here's an example of subscribing to a custom +event with a decorator: .. code-block:: python :linenos: -- cgit v1.2.3 From 8339cd1095be5e49fe41662e3618b8da6055a4f0 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 12 Aug 2013 16:28:57 -0500 Subject: remove the "thread" reference --- docs/narr/events.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/events.rst b/docs/narr/events.rst index 5004a1787..11af89ca6 100644 --- a/docs/narr/events.rst +++ b/docs/narr/events.rst @@ -229,5 +229,7 @@ This example view will notify all subscribers to the custom ``DocCreated`` event. Note that when you fire an event, all subscribers are run -synchronously on the current thread. So it's generally not a good idea -to create event handlers that may take a long time to 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. -- cgit v1.2.3