From e1a7e0679759da628676f3c73c34875e9b2b6a43 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 26 Dec 2010 01:13:26 -0500 Subject: - Move ZCML usage in Hooks chapter to Declarative Configuration chapter. --- docs/narr/hooks.rst | 470 ++++++++++++++++++++++------------------------------ 1 file changed, 201 insertions(+), 269 deletions(-) (limited to 'docs/narr/hooks.rst') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 006f5d5cb..381da0d39 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -3,8 +3,8 @@ Using Hooks =========== -"Hooks" can be used to influence the behavior of the :app:`Pyramid` -framework in various ways. +"Hooks" can be used to influence the behavior of the :app:`Pyramid` framework +in various ways. .. index:: single: not found view @@ -14,61 +14,38 @@ framework in various ways. Changing the Not Found View --------------------------- -When :app:`Pyramid` can't map a URL to view code, it invokes a -:term:`not found view`, which is a :term:`view callable`. A default -notfound view exists. The default not found view can be overridden -through application configuration. This override can be done via -:term:`imperative configuration` or :term:`ZCML`. +When :app:`Pyramid` can't map a URL to view code, it invokes a :term:`not +found view`, which is a :term:`view callable`. A default notfound view +exists. The default not found view can be overridden through application +configuration. -The :term:`not found view` callable is a view callable like any other. -The :term:`view configuration` which causes it to be a "not found" -view consists only of naming the :exc:`pyramid.exceptions.NotFound` -class as the ``context`` of the view configuration. +The :term:`not found view` callable is a view callable like any other. The +:term:`view configuration` which causes it to be a "not found" view consists +only of naming the :exc:`pyramid.exceptions.NotFound` class as the +``context`` of the view configuration. -.. topic:: Using Imperative Configuration +If your application uses :term:`imperative configuration`, you can replace +the Not Found view by using the :meth:`pyramid.config.Configurator.add_view` +method to register an "exception view": - If your application uses :term:`imperative configuration`, you can - replace the Not Found view by using the - :meth:`pyramid.config.Configurator.add_view` method to - register an "exception view": - - .. code-block:: python - :linenos: - - from pyramid.exceptions import NotFound - from helloworld.views import notfound_view - config.add_view(notfound_view, context=NotFound) - - Replace ``helloworld.views.notfound_view`` with a reference to the - Python :term:`view callable` you want to use to represent the Not - Found view. - -.. topic:: Using ZCML - - If your application uses :term:`ZCML`, you can replace the Not Found - view by placing something like the following ZCML in your - ``configure.zcml`` file. - - .. code-block:: xml - :linenos: +.. code-block:: python + :linenos: - + from pyramid.exceptions import NotFound + from helloworld.views import notfound_view + config.add_view(notfound_view, context=NotFound) - Replace ``helloworld.views.notfound_view`` with the Python dotted name - to the notfound view you want to use. +Replace ``helloworld.views.notfound_view`` with a reference to the +:term:`view callable` you want to use to represent the Not Found view. -Like any other view, the notfound view must accept at least a -``request`` parameter, or both ``context`` and ``request``. The -``request`` is the current :term:`request` representing the denied -action. The ``context`` (if used in the call signature) will be the -instance of the :exc:`pyramid.exceptions.NotFound` exception that -caused the view to be called. +Like any other view, the notfound view must accept at least a ``request`` +parameter, or both ``context`` and ``request``. The ``request`` is the +current :term:`request` representing the denied action. The ``context`` (if +used in the call signature) will be the instance of the +:exc:`pyramid.exceptions.NotFound` exception that caused the view to be +called. -Here's some sample code that implements a minimal NotFound view -callable: +Here's some sample code that implements a minimal NotFound view callable: .. code-block:: python :linenos: @@ -93,6 +70,9 @@ callable: :exc:`pyramid.exceptions.NotFound` exception instance. If available, the resource context will still be available as ``request.context``. +For information about how to configure a not found view via :term:`ZCML`, see +:ref:`notfound_zcml`. + .. index:: single: forbidden view @@ -101,59 +81,36 @@ callable: Changing the Forbidden View --------------------------- -When :app:`Pyramid` can't authorize execution of a view based on -the :term:`authorization policy` in use, it invokes a :term:`forbidden -view`. The default forbidden response has a 401 status code and is -very plain, but the view which generates it can be overridden as -necessary using either :term:`imperative configuration` or -:term:`ZCML`. - -The :term:`forbidden view` callable is a view callable like any other. -The :term:`view configuration` which causes it to be a "not found" -view consists only of naming the :exc:`pyramid.exceptions.Forbidden` -class as the ``context`` of the view configuration. +When :app:`Pyramid` can't authorize execution of a view based on the +:term:`authorization policy` in use, it invokes a :term:`forbidden view`. +The default forbidden response has a 401 status code and is very plain, but +the view which generates it can be overridden as necessary. -.. topic:: Using Imperative Configuration +The :term:`forbidden view` callable is a view callable like any other. The +:term:`view configuration` which causes it to be a "not found" view consists +only of naming the :exc:`pyramid.exceptions.Forbidden` class as the +``context`` of the view configuration. - If your application uses :term:`imperative configuration`, you can - replace the Forbidden view by using the - :meth:`pyramid.config.Configurator.add_view` method to - register an "exception view": +You can replace the forbidden view by using the +:meth:`pyramid.config.Configurator.add_view` method to register an "exception +view": - .. code-block:: python - :linenos: - - from helloworld.views import forbidden_view - from pyramid.exceptions import Forbidden - config.add_view(forbidden_view, context=Forbidden) - - Replace ``helloworld.views.forbidden_view`` with a reference to the - Python :term:`view callable` you want to use to represent the - Forbidden view. - -.. topic:: Using ZCML - - If your application uses :term:`ZCML`, you can replace the - Forbidden view by placing something like the following ZCML in your - ``configure.zcml`` file. - - .. code-block:: xml - :linenos: +.. code-block:: python + :linenos: - + from helloworld.views import forbidden_view + from pyramid.exceptions import Forbidden + config.add_view(forbidden_view, context=Forbidden) - Replace ``helloworld.views.forbidden_view`` with the Python - dotted name to the forbidden view you want to use. +Replace ``helloworld.views.forbidden_view`` with a reference to the Python +:term:`view callable` you want to use to represent the Forbidden view. -Like any other view, the forbidden view must accept at least a -``request`` parameter, or both ``context`` and ``request``. The -``context`` (available as ``request.context`` if you're using the -request-only view argument pattern) is the context found by the router -when the view invocation was denied. The ``request`` is the current -:term:`request` representing the denied action. +Like any other view, the forbidden view must accept at least a ``request`` +parameter, or both ``context`` and ``request``. The ``context`` (available +as ``request.context`` if you're using the request-only view argument +pattern) is the context found by the router when the view invocation was +denied. The ``request`` is the current :term:`request` representing the +denied action. Here's some sample code that implements a minimal forbidden view: @@ -161,10 +118,10 @@ Here's some sample code that implements a minimal forbidden view: :linenos: from pyramid.views import view_config + from pyramid.response import Response - @view_config(renderer='templates/login_form.pt') def forbidden_view(request): - return {} + return Response('forbidden') .. note:: When a forbidden view callable is invoked, it is passed a :term:`request`. The ``exception`` attribute of the request will @@ -181,6 +138,9 @@ Here's some sample code that implements a minimal forbidden view: an alternate forbidden view. For example, it would make sense to return a response with a ``403 Forbidden`` status code. +For information about how to configure a forbidden view via :term:`ZCML`, see +:ref:`forbidden_zcml`. + .. index:: single: traverser @@ -189,25 +149,22 @@ Here's some sample code that implements a minimal forbidden view: Changing the Traverser ---------------------- -The default :term:`traversal` algorithm that :app:`Pyramid` uses is -explained in :ref:`traversal_algorithm`. Though it is rarely -necessary, this default algorithm can be swapped out selectively for a -different traversal pattern via configuration. +The default :term:`traversal` algorithm that :app:`Pyramid` uses is explained +in :ref:`traversal_algorithm`. Though it is rarely necessary, this default +algorithm can be swapped out selectively for a different traversal pattern +via configuration. -Use an ``adapter`` stanza in your application's ``configure.zcml`` to -change the default traverser: - -.. code-block:: xml +.. code-block:: python :linenos: - + from pyramid.interfaces import ITraverser + from zope.interface import Interface + from myapp.traversal import Traverser -In the example above, ``myapp.traversal.Traverser`` is assumed to be -a class that implements the following interface: + config.registry.registerAdapter(Traverser, (Interface,), ITraverser) + +In the example above, ``myapp.traversal.Traverser`` is assumed to be a class +that implements the following interface: .. code-block:: python :linenos: @@ -241,31 +198,36 @@ a class that implements the following interface: """ More than one traversal algorithm can be active at the same time. For -instance, if your :term:`root factory` returns more than one type of -object conditionally, you could claim that an alternate traverser -adapter is ``for`` only one particular class or interface. When the -root factory returned an object that implemented that class or -interface, a custom traverser would be used. Otherwise, the default -traverser would be used. For example: - -.. code-block:: xml +instance, if your :term:`root factory` returns more than one type of object +conditionally, you could claim that an alternate traverser adapter is ``for`` +only one particular class or interface. When the root factory returned an +object that implemented that class or interface, a custom traverser would be +used. Otherwise, the default traverser would be used. For example: + +.. code-block:: python :linenos: - + from pyramid.interfaces import ITraverser + from zope.interface import Interface + from myapp.traversal import Traverser + from myapp.resources import MyRoot -If the above stanza was added to a ``configure.zcml`` file, -:app:`Pyramid` would use the ``myapp.traversal.Traverser`` only + config.registry.registerAdapter(Traverser, (MyRoot,), ITraverser) + +If the above stanza was added to a Pyramid ``__init__.py`` file's ``main`` +function, :app:`Pyramid` would use the ``myapp.traversal.Traverser`` only when the application :term:`root factory` returned an instance of the ``myapp.resources.MyRoot`` object. Otherwise it would use the default :app:`Pyramid` traverser to do traversal. +For information about how to configure an alternate traverser via +:term:`ZCML`, see :ref:`changing_traverser_zcml`. + .. index:: single: url generator +.. _changing_resource_url: + Changing How :mod:`pyramid.url.resource_url` Generates a URL ------------------------------------------------------------ @@ -276,25 +238,27 @@ generates by default may be incorrect. If you've added a traverser, you can change how :func:`pyramid.url.resource_url` generates a URL for a specific type of -resource by adding an adapter stanza for -:class:`pyramid.interfaces.IContextURL` to your application's -``configure.zcml``: +resource by adding a registerAdapter call for +:class:`pyramid.interfaces.IContextURL` to your application: -.. code-block:: xml +.. code-block:: python :linenos: - + from pyramid.interfaces import ITraverser + from zope.interface import Interface + from myapp.traversal import URLGenerator + from myapp.resources import MyRoot + + config.registry.registerAdapter(URLGenerator, (MyRoot, Interface), + IContextURL) -In the above example, the ``myapp.traversal.URLGenerator`` class will -be used to provide services to :func:`pyramid.url.resource_url` any -time the :term:`context` passed to ``resource_url`` is of class -``myapp.resources.MyRoot``. The asterisk following represents the type -of interface that must be possessed by the :term:`request` (in this -case, any interface, represented by asterisk). +In the above example, the ``myapp.traversal.URLGenerator`` class will be used +to provide services to :func:`pyramid.url.resource_url` any time the +:term:`context` passed to ``resource_url`` is of class +``myapp.resources.MyRoot``. The second argument in the ``(MyRoot, +Interface)`` tuple represents the type of interface that must be possessed by +the :term:`request` (in this case, any interface, represented by +``zope.interface.Interface``). The API that must be implemented by a class that provides :class:`pyramid.interfaces.IContextURL` is as follows: @@ -317,28 +281,25 @@ The API that must be implemented by a class that provides def __call__(self): """ Return a URL that points to the context """ -The default context URL generator is available for perusal as the -class :class:`pyramid.traversal.TraversalContextURL` in the -`traversal module -`_ of -the :term:`Pylons` GitHub Pyramid repository. +The default context URL generator is available for perusal as the class +:class:`pyramid.traversal.TraversalContextURL` in the `traversal module +`_ of the +:term:`Pylons` GitHub Pyramid repository. .. _changing_the_request_factory: Changing the Request Factory ---------------------------- -Whenever :app:`Pyramid` handles a :term:`WSGI` request, it creates -a :term:`request` object based on the WSGI environment it has been -passed. By default, an instance of the -:class:`pyramid.request.Request` class is created to represent the -request object. +Whenever :app:`Pyramid` handles a :term:`WSGI` request, it creates a +:term:`request` object based on the WSGI environment it has been passed. By +default, an instance of the :class:`pyramid.request.Request` class is created +to represent the request object. -The class (aka "factory") that :app:`Pyramid` uses to create a -request object instance can be changed by passing a -``request_factory`` argument to the constructor of the -:term:`configurator`. This argument can be either a callable or a -:term:`dotted Python name` representing a callable. +The class (aka "factory") that :app:`Pyramid` uses to create a request object +instance can be changed by passing a ``request_factory`` argument to the +constructor of the :term:`configurator`. This argument can be either a +callable or a :term:`dotted Python name` representing a callable. .. code-block:: python :linenos: @@ -350,24 +311,9 @@ request object instance can be changed by passing a config = Configurator(request_factory=MyRequest) -The same ``MyRequest`` class can alternately be registered via ZCML as -a request factory through the use of the ZCML ``utility`` directive. -In the below, we assume it lives in a package named -``mypackage.mymodule``. - -.. code-block:: xml - :linenos: - - - -Lastly, if you're doing imperative configuration, and you'd rather do -it after you've already constructed a :term:`configurator` it can also -be registered via the -:meth:`pyramid.config.Configurator.set_request_factory` -method: +If you're doing imperative configuration, and you'd rather do it after you've +already constructed a :term:`configurator` it can also be registered via the +:meth:`pyramid.config.Configurator.set_request_factory` method: .. code-block:: python :linenos: @@ -381,26 +327,26 @@ method: config = Configurator() config.set_request_factory(MyRequest) +To use ZCML for the same purpose, see :ref:`changing_request_factory_zcml`. + .. _adding_renderer_globals: Adding Renderer Globals ----------------------- -Whenever :app:`Pyramid` handles a request to perform a rendering -(after a view with a ``renderer=`` configuration attribute is invoked, -or when the any of the methods beginning with ``render`` within the -:mod:`pyramid.renderers` module are called), *renderer globals* can -be injected into the *system* values sent to the renderer. By -default, no renderer globals are injected, and the "bare" system -values (such as ``request``, ``context``, and ``renderer_name``) are -the only values present in the system dictionary passed to every -renderer. - -A callback that :app:`Pyramid` will call every time a renderer is -invoked can be added by passing a ``renderer_globals_factory`` -argument to the constructor of the :term:`configurator`. This -callback can either be a callable object or a :term:`dotted Python -name` representing such a callable. +Whenever :app:`Pyramid` handles a request to perform a rendering (after a +view with a ``renderer=`` configuration attribute is invoked, or when the any +of the methods beginning with ``render`` within the :mod:`pyramid.renderers` +module are called), *renderer globals* can be injected into the *system* +values sent to the renderer. By default, no renderer globals are injected, +and the "bare" system values (such as ``request``, ``context``, and +``renderer_name``) are the only values present in the system dictionary +passed to every renderer. + +A callback that :app:`Pyramid` will call every time a renderer is invoked can +be added by passing a ``renderer_globals_factory`` argument to the +constructor of the :term:`configurator`. This callback can either be a +callable object or a :term:`dotted Python name` representing such a callable. .. code-block:: python :linenos: @@ -411,30 +357,15 @@ name` representing such a callable. config = Configurator( renderer_globals_factory=renderer_globals_factory) -Such a callback must accept a single positional argument (notionally -named ``system``) which will contain the original system values. It -must return a dictionary of values that will be merged into the system -dictionary. See :ref:`renderer_system_values` for discription of the -values present in the system dictionary. +Such a callback must accept a single positional argument (notionally named +``system``) which will contain the original system values. It must return a +dictionary of values that will be merged into the system dictionary. See +:ref:`renderer_system_values` for discription of the values present in the +system dictionary. -A renderer globals factory can alternately be registered via ZCML as a -through the use of the ZCML ``utility`` directive. In the below, we -assume a ``renderers_globals_factory`` function lives in a package -named ``mypackage.mymodule``. - -.. code-block:: xml - :linenos: - - - -Lastly, if you're doing imperative configuration, and you'd rather do -it after you've already constructed a :term:`configurator` it can also -be registered via the -:meth:`pyramid.config.Configurator.set_renderer_globals_factory` -method: +If you're doing imperative configuration, and you'd rather do it after you've +already constructed a :term:`configurator` it can also be registered via the +:meth:`pyramid.config.Configurator.set_renderer_globals_factory` method: .. code-block:: python :linenos: @@ -450,6 +381,9 @@ method: Another mechanism which allows event subscribers to add renderer global values exists in :ref:`beforerender_event`. +If you'd rather ZCML to register a renderer globals factory, see +:ref:`adding_renderer_globals_zcml`. + .. _beforerender_event: Using The Before Render Event @@ -472,8 +406,8 @@ that can be used for this purpose. For example: An object of this type is sent as an event just before a :term:`renderer` is invoked (but *after* the application-level renderer globals factory added via -:class:`pyramid.config.Configurator.set_renderer_globals_factory`, if -any, has injected its own keys into the renderer globals dictionary). +:class:`pyramid.config.Configurator.set_renderer_globals_factory`, if any, +has injected its own keys into the renderer globals dictionary). 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 @@ -493,16 +427,16 @@ renderer global values exists in :ref:`adding_renderer_globals`. Using Response Callbacks ------------------------ -Unlike many other web frameworks, :app:`Pyramid` does not eagerly -create a global response object. Adding a :term:`response callback` -allows an application to register an action to be performed against a -response object once it is created, usually in order to mutate it. +Unlike many other web frameworks, :app:`Pyramid` does not eagerly create a +global response object. Adding a :term:`response callback` allows an +application to register an action to be performed against a response object +once it is created, usually in order to mutate it. -The :meth:`pyramid.request.Request.add_response_callback` method is -used to register a response callback. +The :meth:`pyramid.request.Request.add_response_callback` method is used to +register a response callback. -A response callback is a callable which accepts two positional -parameters: ``request`` and ``response``. For example: +A response callback is a callable which accepts two positional parameters: +``request`` and ``response``. For example: .. code-block:: python :linenos: @@ -515,11 +449,11 @@ parameters: ``request`` and ``response``. For example: No response callback is called if an unhandled exception happens in application code, or if the response object returned by a :term:`view -callable` is invalid. Response callbacks *are*, however, invoked when -a :term:`exception view` is rendered successfully: in such a case, the -:attr:`request.exception` attribute of the request when it enters a -response callback will be an exception object instead of its default -value of ``None``. +callable` is invalid. Response callbacks *are*, however, invoked when a +:term:`exception view` is rendered successfully: in such a case, the +:attr:`request.exception` attribute of the request when it enters a 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* @@ -537,13 +471,13 @@ of a :class:`pyramid.events.NewRequest` event). Using Finished Callbacks ------------------------ -A :term:`finished callback` is a function that will be called -unconditionally by the :app:`Pyramid` :term:`router` at the very -end of request processing. A finished callback can be used to perform -an action at the end of a request unconditionally. +A :term:`finished callback` is a function that will be called unconditionally +by the :app:`Pyramid` :term:`router` at the very end of request processing. +A finished callback can be used to perform an action at the end of a request +unconditionally. -The :meth:`pyramid.request.Request.add_finished_callback` method is -used to register a finished callback. +The :meth:`pyramid.request.Request.add_finished_callback` method is used to +register a finished callback. A finished callback is a callable which accepts a single positional parameter: ``request``. For example: @@ -563,25 +497,24 @@ parameter: ``request``. For example: Finished callbacks are called in the order they're added ( first- to most-recently- added). Finished callbacks (unlike a :term:`response -callback`) are *always* called, even if an exception happens in -application code that prevents a response from being generated. - -The set of finished callbacks associated with a request are called -*very late* in the processing of that request; they are essentially -the very last thing called by the :term:`router` before a request -"ends". They are called after response processing has already occurred -in a top-level ``finally:`` block within the router request processing -code. As a result, mutations performed to the ``request`` provided to -a finished callback will have no meaningful effect, because response -processing will have already occurred, and the request's scope will -expire almost immediately after all finished callbacks have been -processed. +callback`) are *always* called, even if an exception happens in application +code that prevents a response from being generated. + +The set of finished callbacks associated with a request are called *very +late* in the processing of that request; they are essentially the very last +thing called by the :term:`router` before a request "ends". They are called +after response processing has already occurred in a top-level ``finally:`` +block within the router request processing code. As a result, mutations +performed to the ``request`` provided to a finished callback will have no +meaningful effect, because response processing will have already occurred, +and the request's scope will expire almost immediately after all finished +callbacks have been processed. It is often necessary to tell whether an exception occurred within -:term:`view callable` code from within a finished callback: in such a -case, the :attr:`request.exception` attribute of the request when it -enters a response callback will be an exception object instead of its -default value of ``None``. +:term:`view callable` code from within a finished callback: in such a case, +the :attr:`request.exception` attribute of the request when it enters a +response callback will be an exception object instead of its default value of +``None``. Errors raised by finished callbacks are not handled specially. They will be propagated to the caller of the :app:`Pyramid` router @@ -598,22 +531,21 @@ Registering Configuration Decorators ------------------------------------ Decorators such as :class:`pyramid.view.view_config` don't change the -behavior of the functions or classes they're decorating. Instead, -when a :term:`scan` is performed, a modified version of the function -or class is registered with :app:`Pyramid`. - -You may wish to have your own decorators that offer such -behaviour. This is possible by using the :term:`Venusian` package in -the same way that it is used by :app:`Pyramid`. - -By way of example, let's suppose you want to write a decorator that -registers the function it wraps with a :term:`Zope Component -Architecture` "utility" within the :term:`application registry` -provided by :app:`Pyramid`. The application registry and the -utility inside the registry is likely only to be available once your -application's configuration is at least partially completed. A normal -decorator would fail as it would be executed before the configuration -had even begun. +behavior of the functions or classes they're decorating. Instead, when a +:term:`scan` is performed, a modified version of the function or class is +registered with :app:`Pyramid`. + +You may wish to have your own decorators that offer such behaviour. This is +possible by using the :term:`Venusian` package in the same way that it is +used by :app:`Pyramid`. + +By way of example, let's suppose you want to write a decorator that registers +the function it wraps with a :term:`Zope Component Architecture` "utility" +within the :term:`application registry` provided by :app:`Pyramid`. The +application registry and the utility inside the registry is likely only to be +available once your application's configuration is at least partially +completed. A normal decorator would fail as it would be executed before the +configuration had even begun. However, using :term:`Venusian`, the decorator could be written as follows: -- cgit v1.2.3 From 74abc0fa8c4f63db0f2fef238e9ef8af16f3c8d3 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 26 Dec 2010 01:46:33 -0500 Subject: reorder chapter --- docs/narr/hooks.rst | 304 ++++++++++++++++++++++++++++------------------------ 1 file changed, 161 insertions(+), 143 deletions(-) (limited to 'docs/narr/hooks.rst') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 381da0d39..238ac8328 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -142,149 +142,7 @@ For information about how to configure a forbidden view via :term:`ZCML`, see :ref:`forbidden_zcml`. .. index:: - single: traverser - -.. _changing_the_traverser: - -Changing the Traverser ----------------------- - -The default :term:`traversal` algorithm that :app:`Pyramid` uses is explained -in :ref:`traversal_algorithm`. Though it is rarely necessary, this default -algorithm can be swapped out selectively for a different traversal pattern -via configuration. - -.. code-block:: python - :linenos: - - from pyramid.interfaces import ITraverser - from zope.interface import Interface - from myapp.traversal import Traverser - - config.registry.registerAdapter(Traverser, (Interface,), ITraverser) - -In the example above, ``myapp.traversal.Traverser`` is assumed to be a class -that implements the following interface: - -.. code-block:: python - :linenos: - - class Traverser(object): - def __init__(self, root): - """ Accept the root object returned from the root factory """ - - def __call__(self, request): - """ Return a dictionary with (at least) the keys ``root``, - ``context``, ``view_name``, ``subpath``, ``traversed``, - ``virtual_root``, and ``virtual_root_path``. These values are - typically the result of a resource tree traversal. ``root`` - is the physical root object, ``context`` will be a resource - object, ``view_name`` will be the view name used (a Unicode - name), ``subpath`` will be a sequence of Unicode names that - followed the view name but were not traversed, ``traversed`` - will be a sequence of Unicode names that were traversed - (including the virtual root path, if any) ``virtual_root`` - will be a resource object representing the virtual root (or the - physical root if traversal was not performed), and - ``virtual_root_path`` will be a sequence representing the - virtual root path (a sequence of Unicode names) or None if - traversal was not performed. - - Extra keys for special purpose functionality can be added as - necessary. - - All values returned in the dictionary will be made available - as attributes of the ``request`` object. - """ - -More than one traversal algorithm can be active at the same time. For -instance, if your :term:`root factory` returns more than one type of object -conditionally, you could claim that an alternate traverser adapter is ``for`` -only one particular class or interface. When the root factory returned an -object that implemented that class or interface, a custom traverser would be -used. Otherwise, the default traverser would be used. For example: - -.. code-block:: python - :linenos: - - from pyramid.interfaces import ITraverser - from zope.interface import Interface - from myapp.traversal import Traverser - from myapp.resources import MyRoot - - config.registry.registerAdapter(Traverser, (MyRoot,), ITraverser) - -If the above stanza was added to a Pyramid ``__init__.py`` file's ``main`` -function, :app:`Pyramid` would use the ``myapp.traversal.Traverser`` only -when the application :term:`root factory` returned an instance of the -``myapp.resources.MyRoot`` object. Otherwise it would use the default -:app:`Pyramid` traverser to do traversal. - -For information about how to configure an alternate traverser via -:term:`ZCML`, see :ref:`changing_traverser_zcml`. - -.. index:: - single: url generator - -.. _changing_resource_url: - -Changing How :mod:`pyramid.url.resource_url` Generates a URL ------------------------------------------------------------- - -When you add a traverser as described in :ref:`changing_the_traverser`, it's -often convenient to continue to use the :func:`pyramid.url.resource_url` API. -However, since the way traversal is done will have been modified, the URLs it -generates by default may be incorrect. - -If you've added a traverser, you can change how -:func:`pyramid.url.resource_url` generates a URL for a specific type of -resource by adding a registerAdapter call for -:class:`pyramid.interfaces.IContextURL` to your application: - -.. code-block:: python - :linenos: - - from pyramid.interfaces import ITraverser - from zope.interface import Interface - from myapp.traversal import URLGenerator - from myapp.resources import MyRoot - - config.registry.registerAdapter(URLGenerator, (MyRoot, Interface), - IContextURL) - -In the above example, the ``myapp.traversal.URLGenerator`` class will be used -to provide services to :func:`pyramid.url.resource_url` any time the -:term:`context` passed to ``resource_url`` is of class -``myapp.resources.MyRoot``. The second argument in the ``(MyRoot, -Interface)`` tuple represents the type of interface that must be possessed by -the :term:`request` (in this case, any interface, represented by -``zope.interface.Interface``). - -The API that must be implemented by a class that provides -:class:`pyramid.interfaces.IContextURL` is as follows: - -.. code-block:: python - :linenos: - - from zope.interface import Interface - - class IContextURL(Interface): - """ An adapter which deals with URLs related to a context. - """ - def __init__(self, context, request): - """ Accept the context and request """ - - def virtual_root(self): - """ Return the virtual root object related to a request and the - current context""" - - def __call__(self): - """ Return a URL that points to the context """ - -The default context URL generator is available for perusal as the class -:class:`pyramid.traversal.TraversalContextURL` in the `traversal module -`_ of the -:term:`Pylons` GitHub Pyramid repository. + single: request factory .. _changing_the_request_factory: @@ -329,6 +187,9 @@ already constructed a :term:`configurator` it can also be registered via the To use ZCML for the same purpose, see :ref:`changing_request_factory_zcml`. +.. index:: + single: renderer globals + .. _adding_renderer_globals: Adding Renderer Globals @@ -384,6 +245,9 @@ exists in :ref:`beforerender_event`. If you'd rather ZCML to register a renderer globals factory, see :ref:`adding_renderer_globals_zcml`. +.. index:: + single: before render event + .. _beforerender_event: Using The Before Render Event @@ -422,6 +286,9 @@ 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`. +.. index:: + single: response callback + .. _using_response_callbacks: Using Response Callbacks @@ -466,6 +333,9 @@ 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). +.. index:: + single: finished callback + .. _using_finished_callbacks: Using Finished Callbacks @@ -525,6 +395,154 @@ 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). +.. index:: + single: traverser + +.. _changing_the_traverser: + +Changing the Traverser +---------------------- + +The default :term:`traversal` algorithm that :app:`Pyramid` uses is explained +in :ref:`traversal_algorithm`. Though it is rarely necessary, this default +algorithm can be swapped out selectively for a different traversal pattern +via configuration. + +.. code-block:: python + :linenos: + + from pyramid.interfaces import ITraverser + from zope.interface import Interface + from myapp.traversal import Traverser + + config.registry.registerAdapter(Traverser, (Interface,), ITraverser) + +In the example above, ``myapp.traversal.Traverser`` is assumed to be a class +that implements the following interface: + +.. code-block:: python + :linenos: + + class Traverser(object): + def __init__(self, root): + """ Accept the root object returned from the root factory """ + + def __call__(self, request): + """ Return a dictionary with (at least) the keys ``root``, + ``context``, ``view_name``, ``subpath``, ``traversed``, + ``virtual_root``, and ``virtual_root_path``. These values are + typically the result of a resource tree traversal. ``root`` + is the physical root object, ``context`` will be a resource + object, ``view_name`` will be the view name used (a Unicode + name), ``subpath`` will be a sequence of Unicode names that + followed the view name but were not traversed, ``traversed`` + will be a sequence of Unicode names that were traversed + (including the virtual root path, if any) ``virtual_root`` + will be a resource object representing the virtual root (or the + physical root if traversal was not performed), and + ``virtual_root_path`` will be a sequence representing the + virtual root path (a sequence of Unicode names) or None if + traversal was not performed. + + Extra keys for special purpose functionality can be added as + necessary. + + All values returned in the dictionary will be made available + as attributes of the ``request`` object. + """ + +More than one traversal algorithm can be active at the same time. For +instance, if your :term:`root factory` returns more than one type of object +conditionally, you could claim that an alternate traverser adapter is ``for`` +only one particular class or interface. When the root factory returned an +object that implemented that class or interface, a custom traverser would be +used. Otherwise, the default traverser would be used. For example: + +.. code-block:: python + :linenos: + + from pyramid.interfaces import ITraverser + from zope.interface import Interface + from myapp.traversal import Traverser + from myapp.resources import MyRoot + + config.registry.registerAdapter(Traverser, (MyRoot,), ITraverser) + +If the above stanza was added to a Pyramid ``__init__.py`` file's ``main`` +function, :app:`Pyramid` would use the ``myapp.traversal.Traverser`` only +when the application :term:`root factory` returned an instance of the +``myapp.resources.MyRoot`` object. Otherwise it would use the default +:app:`Pyramid` traverser to do traversal. + +For information about how to configure an alternate traverser via +:term:`ZCML`, see :ref:`changing_traverser_zcml`. + +.. index:: + single: url generator + +.. _changing_resource_url: + +Changing How :mod:`pyramid.url.resource_url` Generates a URL +------------------------------------------------------------ + +When you add a traverser as described in :ref:`changing_the_traverser`, it's +often convenient to continue to use the :func:`pyramid.url.resource_url` API. +However, since the way traversal is done will have been modified, the URLs it +generates by default may be incorrect. + +If you've added a traverser, you can change how +:func:`pyramid.url.resource_url` generates a URL for a specific type of +resource by adding a registerAdapter call for +:class:`pyramid.interfaces.IContextURL` to your application: + +.. code-block:: python + :linenos: + + from pyramid.interfaces import ITraverser + from zope.interface import Interface + from myapp.traversal import URLGenerator + from myapp.resources import MyRoot + + config.registry.registerAdapter(URLGenerator, (MyRoot, Interface), + IContextURL) + +In the above example, the ``myapp.traversal.URLGenerator`` class will be used +to provide services to :func:`pyramid.url.resource_url` any time the +:term:`context` passed to ``resource_url`` is of class +``myapp.resources.MyRoot``. The second argument in the ``(MyRoot, +Interface)`` tuple represents the type of interface that must be possessed by +the :term:`request` (in this case, any interface, represented by +``zope.interface.Interface``). + +The API that must be implemented by a class that provides +:class:`pyramid.interfaces.IContextURL` is as follows: + +.. code-block:: python + :linenos: + + from zope.interface import Interface + + class IContextURL(Interface): + """ An adapter which deals with URLs related to a context. + """ + def __init__(self, context, request): + """ Accept the context and request """ + + def virtual_root(self): + """ Return the virtual root object related to a request and the + current context""" + + def __call__(self): + """ Return a URL that points to the context """ + +The default context URL generator is available for perusal as the class +:class:`pyramid.traversal.TraversalContextURL` in the `traversal module +`_ of the +:term:`Pylons` GitHub Pyramid repository. + +.. index:: + single: configuration decorator + .. _registering_configuration_decorators: Registering Configuration Decorators -- cgit v1.2.3 From d30a83540d98bb803caca74b94ae75f88dd3154b Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 27 Dec 2010 01:05:14 -0500 Subject: remove inappropriate use of begin/end --- docs/narr/hooks.rst | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs/narr/hooks.rst') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 238ac8328..2917b5254 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -621,10 +621,8 @@ performed, enabling you to set up the utility in advance: if __name__ == '__main__': config = Configurator() - config.begin() config.registry.registerUtility(UtilityImplementation()) config.scan() - config.end() app = config.make_wsgi_app() serve(app, host='0.0.0.0') -- cgit v1.2.3 From 780b6f1937b12ebaf99147ed996f224dc169fc9f Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 6 Jan 2011 20:47:49 -0500 Subject: get rid of incorrect usage of threadlocals during configuration in venusian example --- docs/narr/hooks.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/hooks.rst') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 2917b5254..e30313d5c 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -581,7 +581,7 @@ follows: self.path = path def register(self, scanner, name, wrapped): - registry = get_current_registry() + registry = scanner.config.registry registry.getUtility(IMyUtility).register( self.path, wrapped ) -- cgit v1.2.3 From c5e83c3285b12a4f08547fa5cdafcb9fbeb044e9 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 7 Jan 2011 23:47:46 -0500 Subject: - Document ``Configurator.set_view_mapper``. - Document ``__view_mapper__`` attribute and ``mapper`` argument to view configuration for view callable view mapper preference. --- docs/narr/hooks.rst | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) (limited to 'docs/narr/hooks.rst') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index e30313d5c..cf3f56e87 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -540,6 +540,94 @@ The default context URL generator is available for perusal as the class `_ of the :term:`Pylons` GitHub Pyramid repository. +.. index:: + single: view mapper + +Using a View Mapper +------------------- + +The default calling conventions for view callables are documented in the +:ref:`views_chapter`. You can change the way users define view callbles by +employing a :term:`view mapper`. + +A view mapper is an object that accepts a set of keyword arguments and which +returns a callable. The returned callable is called with the :term:`view +callable` object. The returned callable should itself return another +callable which can be called with the "internal calling protocol" ``(context, +request)``. + +You can use a view mapper in a number of ways: + +- by setting a ``__view_mapper__`` attribute (which is the view mapper + object) on the view callable itself + +- by passing the mapper object to + :meth:`pyramid.config.Configurator.add_view` (or its declarative/decorator + equivalents) as the ``mapper`` argument. + +- by registering a *default* view mapper. + +Here's an example of a view mapper that emulates (somewhat) a Pylons +"controller". The mapper is initialized with some keyword arguments. Its +``__call__`` method accepts the view object (which will be a class). It uses +the ``attr`` keyword argument it is passed to determine which attribute +should be used as an action method. The wrapper method it returns accepts +``(context, request)`` and returns the result of calling the action method +with keyword arguments implied by the :term:`matchdict` after popping the +``action`` out of it. This somewhat emulates the Pylons style of calling +action methods with routing parameters pulled out of the route matching dict +as keyword arguments. + +.. code-block:: python + :linenos: + + # framework + + class PylonsControllerViewMapper(object): + def __init__(self, **kw): + self.kw = kw + + def __call__(self, view): + attr = self.kw['attr'] + def wrapper(context, request): + matchdict = request.matchdict.copy() + matchdict.pop('action', None) + inst = view() + meth = getattr(inst, attr) + return meth(**matchdict) + return wrapper + + class BaseController(object): + __view_mapper__ = PylonsControllerViewMapper + +A user might make use of these framework components like so: + +.. code-block:: python + :linenos: + + # user application + + from webob import Response + from pyramid.config import Configurator + from paste.httpserver import serve + + class MyController(BaseController): + def index(self, id): + return Response(id) + + if __name__ == '__main__': + config = Configurator() + config.add_handler('one', '/{id}', MyController, action='index') + config.add_handler('two', '/{action}/{id}', MyController) + serve(config.make_wsgi_app()) + +The :meth:`pyramid.config.Configurator.set_default_mapper` method can be used +to set a *default* view mapper (overriding the superdefault view mapper used +by Pyramid itself). + +A *single* view registration can use a view mapper by passing the mapper as +the ``mapper`` argument to :meth:`pyramid.config.Configuration.add_view`. + .. index:: single: configuration decorator -- cgit v1.2.3 From 522d7d704b4d4413f0222dcc404e7d7b07b73b68 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 9 Jan 2011 12:44:54 -0500 Subject: add reference target --- docs/narr/hooks.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/narr/hooks.rst') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index cf3f56e87..c12a5abb4 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -543,6 +543,8 @@ The default context URL generator is available for perusal as the class .. index:: single: view mapper +.. _using_a_view_mapper: + Using a View Mapper ------------------- -- cgit v1.2.3 From 2fa5764cb1fd001550ae7c985333718667b86b1c Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 16 Jan 2011 17:41:10 -0500 Subject: - The ``pylons_minimal``, ``pylons_basic`` and ``pylons_sqla`` paster templates were removed. Use ``pyramid_sqla`` (available from PyPI) as a generic replacement for Pylons-esque development. - All references to ``add_handler`` and the ``handler`` ZCML directive have been removed from the docs, and stubs which point to ``pylons_handlers`` package have replaced them. --- docs/narr/hooks.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/narr/hooks.rst') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index c12a5abb4..96515c195 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -611,6 +611,7 @@ A user might make use of these framework components like so: from webob import Response from pyramid.config import Configurator + import pyramid_handlers from paste.httpserver import serve class MyController(BaseController): @@ -619,6 +620,7 @@ A user might make use of these framework components like so: if __name__ == '__main__': config = Configurator() + config.include(pyramid_handlers) config.add_handler('one', '/{id}', MyController, action='index') config.add_handler('two', '/{action}/{id}', MyController) serve(config.make_wsgi_app()) -- cgit v1.2.3 From c9c3c487bcaedeca97bb6463a00188b0dc01203a Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 18 Jan 2011 12:25:56 -0500 Subject: - Most references to ZCML in narrative chapters have been removed or redirected to ``pyramid_zcml`` locations. --- docs/narr/hooks.rst | 14 -------------- 1 file changed, 14 deletions(-) (limited to 'docs/narr/hooks.rst') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 96515c195..f75e0bcf5 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -70,9 +70,6 @@ Here's some sample code that implements a minimal NotFound view callable: :exc:`pyramid.exceptions.NotFound` exception instance. If available, the resource context will still be available as ``request.context``. -For information about how to configure a not found view via :term:`ZCML`, see -:ref:`notfound_zcml`. - .. index:: single: forbidden view @@ -138,9 +135,6 @@ Here's some sample code that implements a minimal forbidden view: an alternate forbidden view. For example, it would make sense to return a response with a ``403 Forbidden`` status code. -For information about how to configure a forbidden view via :term:`ZCML`, see -:ref:`forbidden_zcml`. - .. index:: single: request factory @@ -185,8 +179,6 @@ already constructed a :term:`configurator` it can also be registered via the config = Configurator() config.set_request_factory(MyRequest) -To use ZCML for the same purpose, see :ref:`changing_request_factory_zcml`. - .. index:: single: renderer globals @@ -242,9 +234,6 @@ already constructed a :term:`configurator` it can also be registered via the Another mechanism which allows event subscribers to add renderer global values exists in :ref:`beforerender_event`. -If you'd rather ZCML to register a renderer globals factory, see -:ref:`adding_renderer_globals_zcml`. - .. index:: single: before render event @@ -474,9 +463,6 @@ when the application :term:`root factory` returned an instance of the ``myapp.resources.MyRoot`` object. Otherwise it would use the default :app:`Pyramid` traverser to do traversal. -For information about how to configure an alternate traverser via -:term:`ZCML`, see :ref:`changing_traverser_zcml`. - .. index:: single: url generator -- cgit v1.2.3 From 4dc751e613198c1aa87a47c0d5cf5047c9cfe9ba Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Tue, 18 Jan 2011 18:08:57 -0700 Subject: fix spacing --- docs/narr/hooks.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/narr/hooks.rst') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 96515c195..61e8aa1bf 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -365,10 +365,11 @@ parameter: ``request``. For example: transaction.commit() request.add_finished_callback(commit_callback) -Finished callbacks are called in the order they're added ( first- to -most-recently- added). Finished callbacks (unlike a :term:`response -callback`) are *always* called, even if an exception happens in application -code that prevents a response from being generated. +Finished callbacks are called in the order they're added +(first-to-most-recently-added). Finished callbacks (unlike a +:term:`response callback`) are *always* called, even if an exception +happens in application code that prevents a response from being +generated. The set of finished callbacks associated with a request are called *very late* in the processing of that request; they are essentially the very last -- cgit v1.2.3 From 1130ec62a4438c22eef494594c6f25dcce7fe468 Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Tue, 18 Jan 2011 18:13:15 -0700 Subject: add word chapter --- docs/narr/hooks.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/hooks.rst') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 61e8aa1bf..d49d3df11 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -550,8 +550,8 @@ Using a View Mapper ------------------- The default calling conventions for view callables are documented in the -:ref:`views_chapter`. You can change the way users define view callbles by -employing a :term:`view mapper`. +:ref:`views_chapter` chapter. You can change the way users define view +callbles by employing a :term:`view mapper`. A view mapper is an object that accepts a set of keyword arguments and which returns a callable. The returned callable is called with the :term:`view -- cgit v1.2.3 From a0535390b93d59ef77b96431df732e74240236a0 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 19 Jan 2011 02:06:36 -0500 Subject: - When a ``pyramid.exceptions.Forbidden`` error is raised, its status code now ``403 Forbidden``. It was previously ``401 Unauthorized``, for backwards compatibility purposes with ``repoze.bfg``. This change will cause problems for users of Pyramid with ``repoze.who``, which intercepts ``401 Unauthorized`` by default, but allows ``403 Forbidden`` to pass through. Those deployments will need to configure ``repoze.who`` to also react to ``403 Forbidden``. --- docs/narr/hooks.rst | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) (limited to 'docs/narr/hooks.rst') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 6b1522846..b3b41046f 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -80,7 +80,7 @@ Changing the Forbidden View When :app:`Pyramid` can't authorize execution of a view based on the :term:`authorization policy` in use, it invokes a :term:`forbidden view`. -The default forbidden response has a 401 status code and is very plain, but +The default forbidden response has a 403 status code and is very plain, but the view which generates it can be overridden as necessary. The :term:`forbidden view` callable is a view callable like any other. The @@ -129,12 +129,6 @@ Here's some sample code that implements a minimal forbidden view: ``debug_authorization`` environment setting is true than it is when it is false. -.. warning:: the default forbidden view sends a response with a ``401 - Unauthorized`` status code for backwards compatibility reasons. - You can influence the status code of Forbidden responses by using - an alternate forbidden view. For example, it would make sense to - return a response with a ``403 Forbidden`` status code. - .. index:: single: request factory -- cgit v1.2.3 From 70acd25f40f32fc6cbb3b5d38a695b8982b52a31 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 27 Jan 2011 23:06:55 -0500 Subject: module name contractions --- docs/narr/hooks.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) (limited to 'docs/narr/hooks.rst') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index b3b41046f..d2eaf8215 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -42,7 +42,7 @@ Like any other view, the notfound view must accept at least a ``request`` parameter, or both ``context`` and ``request``. The ``request`` is the current :term:`request` representing the denied action. The ``context`` (if used in the call signature) will be the instance of the -:exc:`pyramid.exceptions.NotFound` exception that caused the view to be +:exc:`~pyramid.exceptions.NotFound` exception that caused the view to be called. Here's some sample code that implements a minimal NotFound view callable: @@ -57,7 +57,7 @@ Here's some sample code that implements a minimal NotFound view callable: .. note:: When a NotFound view callable is invoked, it is passed a :term:`request`. The ``exception`` attribute of the request will - be an instance of the :exc:`pyramid.exceptions.NotFound` + be an instance of the :exc:`~pyramid.exceptions.NotFound` exception that caused the not found view to be called. The value of ``request.exception.args[0]`` will be a value explaining why the not found error was raised. This message will be different when @@ -67,7 +67,7 @@ Here's some sample code that implements a minimal NotFound view callable: .. warning:: When a NotFound view callable accepts an argument list as described in :ref:`request_and_context_view_definitions`, the ``context`` passed as the first argument to the view callable will be the - :exc:`pyramid.exceptions.NotFound` exception instance. If available, the + :exc:`~pyramid.exceptions.NotFound` exception instance. If available, the resource context will still be available as ``request.context``. .. index:: @@ -122,7 +122,7 @@ Here's some sample code that implements a minimal forbidden view: .. note:: When a forbidden view callable is invoked, it is passed a :term:`request`. The ``exception`` attribute of the request will - be an instance of the :exc:`pyramid.exceptions.Forbidden` + be an instance of the :exc:`~pyramid.exceptions.Forbidden` exception that caused the forbidden view to be called. The value of ``request.exception.args[0]`` will be a value explaining why the forbidden was raised. This message will be different when the @@ -253,7 +253,7 @@ that can be used for this purpose. For example: An object of this type is sent as an event just before a :term:`renderer` is invoked (but *after* the application-level renderer globals factory added via -:class:`pyramid.config.Configurator.set_renderer_globals_factory`, if any, +:class:`~pyramid.config.Configurator.set_renderer_globals_factory`, if any, has injected its own keys into the renderer globals dictionary). If a subscriber attempts to add a key that already exist in the renderer @@ -263,7 +263,7 @@ keys added to the renderer globals dictionary by all :class:`pyramid.events.BeforeRender` subscribers and renderer globals factories must be unique. -See the API documentation for the :class:`pyramid.events.BeforeRender` event +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 @@ -307,14 +307,14 @@ callback will be an exception object instead of its default value of Response callbacks are called in the order they're added (first-to-most-recently-added). All response callbacks are called *after* -the :class:`pyramid.events.NewResponse` event is sent. Errors raised by +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 :app:`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.events.NewRequest` event). +of a :class:`~pyramid.events.NewRequest` event). .. index:: single: finished callback @@ -377,7 +377,7 @@ 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.events.NewRequest` event). +of a :class:`~pyramid.events.NewRequest` event). .. index:: single: traverser @@ -472,7 +472,7 @@ However, since the way traversal is done will have been modified, the URLs it generates by default may be incorrect. If you've added a traverser, you can change how -:func:`pyramid.url.resource_url` generates a URL for a specific type of +:func:`~pyramid.url.resource_url` generates a URL for a specific type of resource by adding a registerAdapter call for :class:`pyramid.interfaces.IContextURL` to your application: @@ -488,7 +488,7 @@ resource by adding a registerAdapter call for IContextURL) In the above example, the ``myapp.traversal.URLGenerator`` class will be used -to provide services to :func:`pyramid.url.resource_url` any time the +to provide services to :func:`~pyramid.url.resource_url` any time the :term:`context` passed to ``resource_url`` is of class ``myapp.resources.MyRoot``. The second argument in the ``(MyRoot, Interface)`` tuple represents the type of interface that must be possessed by @@ -496,7 +496,7 @@ the :term:`request` (in this case, any interface, represented by ``zope.interface.Interface``). The API that must be implemented by a class that provides -:class:`pyramid.interfaces.IContextURL` is as follows: +:class:`~pyramid.interfaces.IContextURL` is as follows: .. code-block:: python :linenos: @@ -611,7 +611,7 @@ to set a *default* view mapper (overriding the superdefault view mapper used by Pyramid itself). A *single* view registration can use a view mapper by passing the mapper as -the ``mapper`` argument to :meth:`pyramid.config.Configuration.add_view`. +the ``mapper`` argument to :meth:`~pyramid.config.Configuration.add_view`. .. index:: single: configuration decorator @@ -621,7 +621,7 @@ the ``mapper`` argument to :meth:`pyramid.config.Configuration.add_view`. Registering Configuration Decorators ------------------------------------ -Decorators such as :class:`pyramid.view.view_config` don't change the +Decorators such as :class:`~pyramid.view.view_config` don't change the behavior of the functions or classes they're decorating. Instead, when a :term:`scan` is performed, a modified version of the function or class is registered with :app:`Pyramid`. -- cgit v1.2.3