diff options
| -rw-r--r-- | CHANGES.txt | 5 | ||||
| -rw-r--r-- | docs/narr/declarative.rst | 2 | ||||
| -rw-r--r-- | docs/narr/events.rst | 41 | ||||
| -rw-r--r-- | docs/narr/hooks.rst | 45 | ||||
| -rw-r--r-- | docs/narr/router.rst | 19 | ||||
| -rw-r--r-- | docs/narr/startup.rst | 5 | ||||
| -rw-r--r-- | docs/zcml/subscriber.rst | 13 | ||||
| -rw-r--r-- | pyramid/configuration.py | 2 | ||||
| -rw-r--r-- | pyramid/events.py | 9 | ||||
| -rw-r--r-- | pyramid/request.py | 2 |
10 files changed, 73 insertions, 70 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index f9dcee32c..67b26d378 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -101,6 +101,11 @@ Documentation (delta from BFG 1.3) - The SQL Wiki tutorial was updated to take into account changes to the ``pyramid_routesalchemy`` paster template. +- All references to events by interface + (e.g. ``pyramid.interfaces.INewRequest``) have been changed to reference + their concrete classes (e.g. ``pyramid.events.NewRequest``) in + documentation about making subscriptions. + Backwards Incompatibilities (with BFG 1.3) ------------------------------------------ diff --git a/docs/narr/declarative.rst b/docs/narr/declarative.rst index 086b6aa51..232f42751 100644 --- a/docs/narr/declarative.rst +++ b/docs/narr/declarative.rst @@ -1145,7 +1145,7 @@ which we assume lives in a ``subscribers.py`` module within your application: :linenos: <subscriber - for="pyramid.interfaces.INewRequest" + for="pyramid.events.NewRequest" handler=".subscribers.mysubscriber" /> diff --git a/docs/narr/events.rst b/docs/narr/events.rst index 0d0f96328..703b7bb88 100644 --- a/docs/narr/events.rst +++ b/docs/narr/events.rst @@ -3,6 +3,8 @@ single: subscriber single: INewRequest single: INewResponse + single: NewRequest + single: NewResponse .. _events_chapter: @@ -46,14 +48,14 @@ function found via a :term:`scan`. .. code-block:: python :linenos: - from pyramid.interfaces import INewRequest + from pyramid.events import NewRequest from subscribers import mysubscriber # "config" below is assumed to be an instance of a # pyramid.configuration.Configurator object - config.add_subscriber(mysubscriber, INewRequest) + config.add_subscriber(mysubscriber, NewRequest) The first argument to :meth:`pyramid.configuration.Configurator.add_subscriber` is the @@ -68,10 +70,10 @@ function found via a :term:`scan`. .. code-block:: python :linenos: - from pyramid.interfaces import INewRequest + from pyramid.events import NewRequest from pyramid.events import subscriber - @subscriber(INewRequest) + @subscriber(NewRequest) def mysubscriber(event): event.request.foo = 1 @@ -85,13 +87,16 @@ function found via a :term:`scan`. Either of the above registration examples implies that every time the :mod:`pyramid` framework emits an event object that supplies an -:class:`pyramid.interfaces.INewRequest` interface, the -``mysubscriber`` function will be called with an *event* object. +:class:`pyramid.events.NewRequest` interface, the ``mysubscriber`` function +will be called with an *event* object. -As you can see, a subscription is made in terms of an -:term:`interface`. The event object sent to a subscriber will always -be an object that possesses an interface. The interface itself -provides documentation of what attributes of the event are available. +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 @@ -125,9 +130,9 @@ configuration startup: # config is an instance of pyramid.configuration.Configurator config.add_subscriber('myproject.subscribers.handle_new_request', - 'pyramid.interfaces.INewRequest') + 'pyramid.events.NewRequest') config.add_subscriber('myproject.subscribers.handle_new_response', - 'pyramid.interfaces.INewResponse') + 'pyramid.events.NewResponse') Either mechanism causes the functions in ``subscribers.py`` to be registered as event subscribers. Under this configuration, when the @@ -138,14 +143,12 @@ 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.interfaces.INewRequest` 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.INewResponse` events have a +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.interfaces.INewResponse` objects also have a -``request``). +(:class:`pyramid.events.NewResponse` objects also have a ``request``). diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 701cab17c..f8d662447 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -454,18 +454,18 @@ exists in :ref:`beforerender_event`. Using The Before Render Event ----------------------------- -Subscribers to the :class:`repoze.interfaces.IBeforeRender` event may -introspect the and modify the set of :term:`renderer globals` before they are -passed to a :term:`renderer`. This event object iself has a dictionary-like -interface that can be used for this purpose. For example: +Subscribers to the :class:`pyramid.events.BeforeRender` event may introspect +the and modify the set of :term:`renderer globals` before they are passed to +a :term:`renderer`. This event object iself has a dictionary-like interface +that can be used for this purpose. For example: .. code-block:: python :linenos: - from repoze.events import subscriber - from pyramid.interfaces import IBeforeRender + from pyramid.events import subscriber + from pyramid.events import BeforeRender - @subscriber(IBeforeRender) + @subscriber(BeforeRender) def add_global(event): event['mykey'] = 'foo' @@ -478,11 +478,11 @@ If a subscriber attempts to add a key that already exist in the renderer globals dictionary, a :exc:`KeyError` is raised. This limitation is enforced because event subscribers do not possess any relative ordering. The set of keys added to the renderer globals dictionary by all -:class:`pyramid.interfaces.IBeforeRender` subscribers and renderer globals +:class:`pyramid.events.BeforeRender` subscribers and renderer globals factories must be unique. -See the API documentation for the event interface -:class:`pyramid.interfaces.IBeforeRender`. +See the API documentation for the :class:`pyramid.events.BeforeRender` event +interface at :class:`pyramid.interfaces.IBeforeRender`. Another mechanism which allows event subscribers more control when adding renderer global values exists in :ref:`adding_renderer_globals`. @@ -521,16 +521,15 @@ response callback will be an exception object instead of its default value of ``None``. Response callbacks are called in the order they're added -(first-to-most-recently-added). All response callbacks are called -*after* the :class:`pyramid.interfaces.INewResponse` event is sent. -Errors raised by response callbacks are not handled specially. They -will be propagated to the caller of the :mod:`pyramid` router -application. +(first-to-most-recently-added). All response callbacks are called *after* +the :class:`pyramid.events.NewResponse` event is sent. Errors raised by +response callbacks are not handled specially. They will be propagated to the +caller of the :mod:`pyramid` router application. -A response callback has a lifetime of a *single* request. If you want -a response callback to happen as the result of *every* request, you -must re-register the callback into every new request (perhaps within a -subscriber of a :class:`pyramid.interfaces.INewRequest` event). +A response callback has a lifetime of a *single* request. If you want a +response callback to happen as the result of *every* request, you must +re-register the callback into every new request (perhaps within a subscriber +of a :class:`pyramid.events.NewRequest` event). .. _using_finished_callbacks: @@ -587,10 +586,10 @@ Errors raised by finished callbacks are not handled specially. They will be propagated to the caller of the :mod:`pyramid` router application. -A finished callback has a lifetime of a *single* request. If you want -a finished callback to happen as the result of *every* request, you -must re-register the callback into every new request (perhaps within a -subscriber of a :class:`pyramid.interfaces.INewRequest` event). +A finished callback has a lifetime of a *single* request. If you want a +finished callback to happen as the result of *every* request, you must +re-register the callback into every new request (perhaps within a subscriber +of a :class:`pyramid.events.NewRequest` event). .. _registering_configuration_decorators: diff --git a/docs/narr/router.rst b/docs/narr/router.rst index 6bc17caf0..b585482ef 100644 --- a/docs/narr/router.rst +++ b/docs/narr/router.rst @@ -32,8 +32,8 @@ processing? :func:`pyramid.threadlocal.get_current_request` and :func:`pyramid.threadlocal.get_current_registry` to work. -#. A :class:`pyramid.interfaces.INewRequest` :term:`event` is sent - to any subscribers. +#. A :class:`pyramid.events.NewRequest` :term:`event` is sent to any + subscribers. #. If any :term:`route` has been defined within application configuration, the :mod:`pyramid` :term:`router` calls a @@ -74,7 +74,7 @@ processing? they can be accessed via e.g. ``request.context`` within :term:`view` code. -#. A :class:`pyramid.interfaces.IContextFound` :term:`event` is +#. A :class:`pyramid.events.ContextFound` :term:`event` is sent to any subscribers. #. :mod:`pyramid` looks up a :term:`view` callable using the @@ -114,14 +114,13 @@ processing? #. The following steps occur only when a :term:`response` could be successfully generated by a normal :term:`view callable` or an - :term:`exception view` callable. :mod:`pyramid` will attempt to - execute any :term:`response callback` functions attached via + :term:`exception view` callable. :mod:`pyramid` will attempt to execute + any :term:`response callback` functions attached via :meth:`pyramid.request.Request.add_response_callback`. A - :class:`pyramid.interfaces.INewResponse` :term:`event` is then - sent to any subscribers. The response object's ``app_iter``, - ``status``, and ``headerlist`` attributes are then used to generate - a WSGI response. The response is sent back to the upstream WSGI - server. + :class:`pyramid.events.NewResponse` :term:`event` is then sent to any + subscribers. The response object's ``app_iter``, ``status``, and + ``headerlist`` attributes are then used to generate a WSGI response. The + response is sent back to the upstream WSGI server. #. :mod:`pyramid` will attempt to execute any :term:`finished callback` functions attached via diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 53cbcd95c..7c4ee0897 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -121,9 +121,8 @@ press ``return`` after running ``paster serve development.ini``. configurator previously populated by other methods run against the Configurator. The router is a WSGI application. -#. A :class:`pyramid.interfaces.IApplicationCreated` event is - emitted (see :ref:`events_chapter` for more information about - events). +#. A :class:`pyramid.events.ApplicationCreated` event is emitted (see + :ref:`events_chapter` for more information about events). #. Assuming there were no errors, the ``app`` function in ``myproject`` returns the router instance created by ``make_wsgi_app`` back to diff --git a/docs/zcml/subscriber.rst b/docs/zcml/subscriber.rst index c48c89a9b..c04aecff2 100644 --- a/docs/zcml/subscriber.rst +++ b/docs/zcml/subscriber.rst @@ -11,12 +11,11 @@ Attributes ~~~~~~~~~~ ``for`` - The class or :term:`interface` that you are subscribing the - listener for, e.g. :class:`pyramid.interfaces.INewRequest`. - Registering a subscriber for a specific class or interface limits - the event types that the subscriber will receive to those specified - by the interface or class. Default: ``zope.interface.Interface`` - (implying *any* event type). + The class or :term:`interface` that you are subscribing the listener for, + e.g. :class:`pyramid.events.NewRequest`. Registering a subscriber for a + specific class or interface limits the event types that the subscriber + will receive to those specified by the interface or class. Default: + ``zope.interface.Interface`` (implying *any* event type). ``handler`` A :term:`dotted Python name` which references an event handler @@ -30,7 +29,7 @@ Examples :linenos: <subscriber - for="pyramid.interfaces.INewRequest" + for="pyramid.events.NewRequest" handler=".subscribers.handle_new_request" /> diff --git a/pyramid/configuration.py b/pyramid/configuration.py index 805894ce4..b392b2163 100644 --- a/pyramid/configuration.py +++ b/pyramid/configuration.py @@ -617,7 +617,7 @@ class Configurator(object): def make_wsgi_app(self): """ Returns a :mod:`pyramid` WSGI application representing the current configuration state and sends a - :class:`pyramid.interfaces.IApplicationCreated` + :class:`pyramid.events.ApplicationCreated` event to all listeners.""" from pyramid.router import Router # avoid circdep app = Router(self.registry) diff --git a/pyramid/events.py b/pyramid/events.py index 043631539..d6026413b 100644 --- a/pyramid/events.py +++ b/pyramid/events.py @@ -17,10 +17,10 @@ class subscriber(object): .. code-block:: python - from pyramid.interfaces import INewRequest + from pyramid.events import NewRequest from pyramid.events import subscriber - @subscriber(INewRequest) + @subscriber(NewRequest) def mysubscriber(event): event.request.foo = 1 @@ -28,10 +28,10 @@ class subscriber(object): .. code-block:: python - from pyramid.interfaces import INewRequest + from pyramid.events import NewRequest, NewResponse from pyramid.events import subscriber - @subscriber(INewRequest, INewResponse) + @subscriber(NewRequest, NewResponse) def mysubscriber(event): print event @@ -40,7 +40,6 @@ class subscriber(object): .. code-block:: python - from pyramid.interfaces import INewRequest from pyramid.events import subscriber @subscriber() diff --git a/pyramid/request.py b/pyramid/request.py index 76fff37a8..d18b07cc2 100644 --- a/pyramid/request.py +++ b/pyramid/request.py @@ -70,7 +70,7 @@ class Request(WebobRequest): response object returned by :term:`view` code is invalid. All response callbacks are called *after* the - :class:`pyramid.interfaces.INewResponse` event is sent. + :class:`pyramid.events.NewResponse` event is sent. Errors raised by callbacks are not handled specially. They will be propagated to the caller of the :mod:`pyramid` |