From 9db1a14cd16f6e92fdb72650d2a3e3ef6e55ef9a Mon Sep 17 00:00:00 2001 From: kusut Date: Mon, 28 Jan 2013 23:42:27 +0700 Subject: narrative docs for add_request_method --- docs/narr/hooks.rst | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) (limited to 'docs/narr/hooks.rst') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index b5efc0df1..957426ec2 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -256,6 +256,97 @@ already constructed a :term:`configurator` it can also be registered via the config = Configurator() config.set_request_factory(MyRequest) +.. index:: + single: request method + +.. _adding_request_method: + +Adding Methods or Properties to Request Object +---------------------------------------------- + +Since each pyramid application can only have one :term:`request` factory, +:ref:`changing the request factory ` +is not that extensible especially if you want to build composable features +(e.g., pyramid add-ons and plugins). + +A lazy property can be registered to the request object via the +:meth:`pyramid.config.Configurator.add_request_method` API. This allows you +to specify a callable that will be available on the request object, but will not +actually execute the function until accessed. + +.. note:: This feature is new as of Pyramid 1.4. + +.. warning:: This will silently override methods and properties from + :term:`request factory` that have the same name. + +.. code-block:: python + :linenos: + + from pyramid.config import Configurator + + def total(request, *args): + return sum(args) + + def prop(request): + print "getting the property" + return "the property" + + config = Configurator() + config.add_request_method(total) + config.add_request_method(prop, reify=True) + +In the above example, ``total`` is added as a method. However, ``prop`` is added +as a property and its result is cached per-request by setting ``reify=True``. +This way, we eliminate the overhead of running the function multiple times. + + >>> request.total(1, 2, 3) + 6 + >>> request.prop + getting the property + the property + >>> request.prop + the property + +To not cache the result of ``request.prop``, set ``property=True`` instead of +``reify=True``. + +Here is an example of passing a class to ``Configurator.add_request_method``: + +.. code-block:: python + :linenos: + + from pyramid.config import Configurator + from pyramid.decorator import reify + + + class ExtraStuff(object): + + def __init__(self, request): + self.request = request + + def total(self, *args): + return sum(args) + + # use @property if you don't want to cache the result + @reify + def prop(self): + print "getting the property" + return "the property" + + config = Configurator() + config.add_request_method(ExtraStuff, 'extra', reify=True) + +We attach and cache an object named ``extra`` to the ``request`` object. + + >>> request.extra.total(1, 2, 3) + 6 + >>> request.extra.prop + getting the property + the property + >>> request.extra.prop + the property + + .. index:: single: before render event single: adding renderer globals -- cgit v1.2.3 From 5b9c21ebe7d295bb9ac4356033899181ac69396e Mon Sep 17 00:00:00 2001 From: kusut Date: Tue, 29 Jan 2013 22:16:00 +0700 Subject: enhance! --- docs/narr/hooks.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) (limited to 'docs/narr/hooks.rst') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 957426ec2..d693149e4 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -264,18 +264,18 @@ already constructed a :term:`configurator` it can also be registered via the Adding Methods or Properties to Request Object ---------------------------------------------- -Since each pyramid application can only have one :term:`request` factory, +.. versionadded:: 1.4. + +Since each Pyramid application can only have one :term:`request` factory, :ref:`changing the request factory ` -is not that extensible especially if you want to build composable features -(e.g., pyramid add-ons and plugins). +is not that extensible, especially if you want to build composable features +(e.g., Pyramid add-ons and plugins). A lazy property can be registered to the request object via the :meth:`pyramid.config.Configurator.add_request_method` API. This allows you to specify a callable that will be available on the request object, but will not actually execute the function until accessed. -.. note:: This feature is new as of Pyramid 1.4. - .. warning:: This will silently override methods and properties from :term:`request factory` that have the same name. @@ -318,7 +318,6 @@ Here is an example of passing a class to ``Configurator.add_request_method``: from pyramid.config import Configurator from pyramid.decorator import reify - class ExtraStuff(object): def __init__(self, request): @@ -346,7 +345,6 @@ We attach and cache an object named ``extra`` to the ``request`` object. >>> request.extra.prop the property - .. index:: single: before render event single: adding renderer globals -- cgit v1.2.3 From 40dbf42a2df1783c3d803adf950380c21512bb91 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 30 Jan 2013 00:41:23 +0200 Subject: use the more appropriate directives --- docs/narr/hooks.rst | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) (limited to 'docs/narr/hooks.rst') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index b5efc0df1..fc5c0ff23 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -336,9 +336,9 @@ when adding renderer global values exists in :ref:`adding_renderer_globals`. Adding Renderer Globals (Deprecated) ------------------------------------ -.. warning:: this feature is deprecated as of Pyramid 1.1. A non-deprecated - mechanism which allows event subscribers to add renderer global values - is documented in :ref:`beforerender_event`. +.. deprecated:: 1.1 + An alternative mechanism which allows event subscribers to add renderer + global values is documented in :ref:`beforerender_event`. Whenever :app:`Pyramid` handles a request to perform a rendering (after a view with a ``renderer=`` configuration attribute is invoked, or when any of @@ -635,13 +635,13 @@ See :meth:`pyramid.config.add_resource_url_adapter` for more information. Changing How Pyramid Treats View Responses ------------------------------------------ +.. versionadded:: 1.1 + It is possible to control how Pyramid treats the result of calling a view callable on a per-type basis by using a hook involving :meth:`pyramid.config.Configurator.add_response_adapter` or the :class:`~pyramid.response.response_adapter` decorator. -.. note:: This feature is new as of Pyramid 1.1. - Pyramid, in various places, adapts the result of calling a view callable to the :class:`~pyramid.interfaces.IResponse` interface to ensure that the object returned by the view callable is a "true" response object. The vast @@ -936,8 +936,8 @@ For full details, please read the `Venusian documentation Registering "Tweens" -------------------- -.. note:: Tweens are a feature which were added in Pyramid 1.2. They are - not available in any previous version. +.. versionadded:: 1.2 + Tweens A :term:`tween` (a contraction of the word "between") is a bit of code that sits between the Pyramid router's main request handling function and the @@ -1241,10 +1241,7 @@ implict and explicit tween chains used by an application. See Adding A Third Party View, Route, or Subscriber Predicate --------------------------------------------------------- -.. note:: - - Third-party view, route, and subscriber predicates are a feature new as of - Pyramid 1.4. +.. versionadded:: 1.4 .. _view_and_route_predicates: -- cgit v1.2.3 From c7a06f41d56d076dc979d800388c8befc1b8e5e5 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 9 Feb 2013 19:54:32 -0500 Subject: fix warning block for newer docutils versions --- docs/narr/hooks.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/narr/hooks.rst') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 43bf48289..7d4d03b89 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -276,8 +276,10 @@ A lazy property can be registered to the request object via the to specify a callable that will be available on the request object, but will not actually execute the function until accessed. -.. warning:: This will silently override methods and properties from - :term:`request factory` that have the same name. +.. warning:: + + This will silently override methods and properties from :term:`request + factory` that have the same name. .. code-block:: python :linenos: -- cgit v1.2.3 From 580d74db2a032fa6c84662d1d89362f83d068d48 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 23 Feb 2013 12:42:52 +0200 Subject: replace awkward explanation --- docs/narr/hooks.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'docs/narr/hooks.rst') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 7d4d03b89..f38d57e73 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -15,9 +15,8 @@ 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. +found view`, which is a :term:`view callable`. The default Not Found View +can be overridden through application configuration. If your application uses :term:`imperative configuration`, you can replace the Not Found view by using the -- cgit v1.2.3 From cd8ac801ac1ccefb81c2e015124be910cb8c93de Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Fri, 15 Feb 2013 00:48:08 +0200 Subject: update some links and fix others --- 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 f38d57e73..20cadc996 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -711,7 +711,7 @@ The API that must be implemented by your a class that provides The default context URL generator is available for perusal as the class :class:`pyramid.traversal.ResourceURL` in the `traversal module -`_ of the +`_ of the :term:`Pylons` GitHub Pyramid repository. See :meth:`pyramid.config.add_resource_url_adapter` for more information. -- cgit v1.2.3 From 2f4bdefd18073c418ae95fe9e5a8c7b2a9d1130e Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 9 Mar 2013 03:06:17 +0200 Subject: capitalize; add term role --- docs/narr/hooks.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs/narr/hooks.rst') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index f38d57e73..d7af5ab98 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -19,7 +19,7 @@ found view`, which is a :term:`view callable`. The default Not Found View can be overridden through application configuration. If your application uses :term:`imperative configuration`, you can replace -the Not Found view by using the +the Not Found View by using the :meth:`pyramid.config.Configurator.add_notfound_view` method: .. code-block:: python @@ -29,7 +29,7 @@ the Not Found view by using the config.add_notfound_view(notfound) Replace ``helloworld.views.notfound`` with a reference to the :term:`view -callable` you want to use to represent the Not Found view. The :term:`not +callable` you want to use to represent the Not Found View. The :term:`not found view` callable is a view callable like any other. If your application instead uses :class:`pyramid.view.view_config` decorators @@ -51,12 +51,12 @@ and a :term:`scan`, you can replace the Not Found view by using the This does exactly what the imperative example above showed. -Your application can define *multiple* not found views if necessary. Both +Your application can define *multiple* Not Found Views if necessary. Both :meth:`pyramid.config.Configurator.add_notfound_view` and :class:`pyramid.view.notfound_view_config` take most of the same arguments as :class:`pyramid.config.Configurator.add_view` and -:class:`pyramid.view.view_config`, respectively. This means that not found -views can carry predicates limiting their applicability. For example: +:class:`pyramid.view.view_config`, respectively. This means that Not Found +Views can carry predicates limiting their applicability. For example: .. code-block:: python :linenos: @@ -106,8 +106,8 @@ Here's some sample code that implements a minimal NotFound view callable: 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.httpexceptions.HTTPNotFound` exception that - caused the not found view to be called. The value of - ``request.exception.message`` will be a value explaining why the not found + caused the Not Found View to be called. The value of + ``request.exception.message`` will be a value explaining why the Not Found error was raised. This message will be different when the ``pyramid.debug_notfound`` environment setting is true than it is when it is false. -- cgit v1.2.3 From cec2b05e74b3296ab8b54b9644223e08f269808b Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 9 Mar 2013 03:15:15 +0200 Subject: consistency --- 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 d7af5ab98..d103ca1cd 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -79,7 +79,7 @@ The ``notfound_get`` view will be called when a view could not be found and the request method was ``GET``. The ``notfound_post`` view will be called when a view could not be found and the request method was ``POST``. -Like any other view, the notfound view must accept at least a ``request`` +Like any other view, the Not Found 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 @@ -91,7 +91,8 @@ Both :meth:`pyramid.config.Configurator.add_notfound_view` and redirect requests to slash-appended routes. See :ref:`redirecting_to_slash_appended_routes` for examples. -Here's some sample code that implements a minimal NotFound view callable: +Here's some sample code that implements a minimal :term:`Not Found View` +callable: .. code-block:: python :linenos: @@ -103,7 +104,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 + When a Not Found View callable is invoked, it is passed a :term:`request`. The ``exception`` attribute of the request will be an instance of the :exc:`~pyramid.httpexceptions.HTTPNotFound` exception that caused the Not Found View to be called. The value of @@ -122,7 +123,7 @@ Here's some sample code that implements a minimal NotFound view callable: .. warning:: - When a NotFound view callable accepts an argument list as + When a Not Found 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.httpexceptions.HTTPNotFound` exception instance. If -- cgit v1.2.3