From 1f901ab75c55bafc9c233c3c9588cc1bd92d9d66 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 28 Jul 2011 17:06:29 -0400 Subject: add some edits to the docs for response_adapter decorator; fix renderings --- CHANGES.txt | 4 ++++ docs/glossary.rst | 5 +++++ docs/narr/hooks.rst | 37 +++++++++++++++++++++++-------------- pyramid/config.py | 4 ++-- pyramid/response.py | 9 ++++++--- 5 files changed, 40 insertions(+), 19 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index 2bc462008..5ca9e9379 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -4,6 +4,10 @@ Next release Features -------- +- Added a decorator-based way to configure a response adapter: + ``pyramid.response.response_adapter``. This decorator has the same use as + ``pyramid.config.Configurator.add_response_adapter`` but it's declarative. + - The ``pyramid.events.BeforeRender`` event now has an attribute named ``rendering_val``. This can be used to introspect the value returned by a view in a BeforeRender subscriber. diff --git a/docs/glossary.rst b/docs/glossary.rst index cc1d6201d..c6705fdc5 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -23,6 +23,11 @@ Glossary a subclass such as :class:`pyramid.httpexceptions.HTTPFound`. See :ref:`webob_chapter` for information about response objects. + response adapter + A callable which accepts an arbitrary object and "converts" it to a + :class:`pyramid.response.Response` object. See :ref:`using_iresponse` + for more information. + Repoze "Repoze" is essentially a "brand" of software developed by `Agendaless Consulting `_ and a set of contributors. The diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index df081d35c..fc3f01271 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -575,20 +575,6 @@ Response: config.add_response_adapter(string_response_adapter, str) -The above example using the :class:`~pyramid.response.response_adapter` -decorator: - -.. code-block:: python - :linenos: - - from pyramid.response import Response - from pyramid.response import response_adapter - - @response_adapter(str) - def string_response_adapter(s): - response = Response(s) - return response - Likewise, if you want to be able to return a simplified kind of response object from view callables, you can use the IResponse hook to register an adapter to the more complex IResponse interface: @@ -639,6 +625,29 @@ startup time, as by their nature, instances of this class (and instances of subclasses of the class) will natively provide IResponse. The adapter registered for ``webob.Response`` simply returns the response object. +Instead of using :meth:`pyramid.config.Configurator.add_response_adapter`, +you can use the :class:`pyramid.response.response_adapter` decorator: + +.. code-block:: python + :linenos: + + from pyramid.response import Response + from pyramid.response import response_adapter + + @response_adapter(str) + def string_response_adapter(s): + response = Response(s) + return response + +The above example, when scanned, has the same effect as: + +.. code-block:: python + + config.add_response_adapter(string_response_adapter, str) + +The :class:`~pyramid.response.response_adapter` decorator will have no effect +until activated by a :term:`scan`. + .. index:: single: view mapper diff --git a/pyramid/config.py b/pyramid/config.py index 46249d14e..b0041f370 100644 --- a/pyramid/config.py +++ b/pyramid/config.py @@ -661,7 +661,7 @@ class Configurator(object): """ Return a new Configurator instance with the same registry as this configurator using the package supplied as the ``package`` argument to the new configurator. ``package`` may - be an actual Python package object or a Python dotted name + be an actual Python package object or a :term:`dotted Python name` representing a package.""" context = self._ctx if context is None: @@ -901,7 +901,7 @@ class Configurator(object): the server. A request handler factory (passed as ``handler_factory``) must be a - callable (or a :term:`Python dotted name` to a callable) which + callable (or a :term:`dotted Python name` to a callable) which accepts two arguments: ``handler`` and ``registry``. ``handler`` will be the request handler being wrapped. ``registry`` will be the Pyramid :term:`application registry` represented by this diff --git a/pyramid/response.py b/pyramid/response.py index 60666bd03..db53de0c3 100644 --- a/pyramid/response.py +++ b/pyramid/response.py @@ -9,11 +9,11 @@ class Response(_Response): class response_adapter(object): - """ Decorator activated via a :term:`scan` which treats the - function being decorated as a response adapter for the set of types or + """ Decorator activated via a :term:`scan` which treats the function + being decorated as a :term:`response adapter` for the set of types or interfaces passed as ``*types_or_ifaces`` to the decorator constructor. - For example: + For example, if you scan the following response adapter: .. code-block:: python @@ -24,6 +24,9 @@ class response_adapter(object): def myadapter(i): return Response(status=i) + You can then return an integer from your view callables, and it will be + converted into a response with the integer as the status code. + More than one type or interface can be passed as a constructor argument. The decorated response adapter will be called for each type or interface. -- cgit v1.2.3