Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Merge pull request #824 from kusut/add_request_method

narrative docs for add_request_method
  • Loading branch information...
commit e27746fd29146de7620b9e002c7edd770d9238b4 2 parents 97f17d1 + 5b9c21e
@mcdonc mcdonc authored
Showing with 89 additions and 0 deletions.
  1. +89 −0 docs/narr/hooks.rst
View
89 docs/narr/hooks.rst
@@ -257,6 +257,95 @@ already constructed a :term:`configurator` it can also be registered via the
config.set_request_factory(MyRequest)
.. index::
+ single: request method
+
+.. _adding_request_method:
+
+Adding Methods or Properties to Request Object
+----------------------------------------------
+
+.. versionadded:: 1.4.
+
+Since each Pyramid application can only have one :term:`request` factory,
+:ref:`changing the request factory <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.
+
+.. 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
Please sign in to comment.
Something went wrong with that request. Please try again.