From 2a922b4cf51d3fe083b33d375282c227f90a3e4e Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 29 Dec 2010 01:59:22 -0500 Subject: fix misleading example --- docs/narr/renderers.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/narr/renderers.rst') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 3804fcf42..76e9562fa 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -22,6 +22,7 @@ response. For example: from pyramid.response import Response from pyramid.view import view_config + @view_config(renderer='json') def hello_world(request): return {'content':'Hello!'} -- cgit v1.2.3 From c7af1563eaf89694233ddd1ebf2c48b163146d01 Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Sun, 2 Jan 2011 23:50:39 -0700 Subject: remove unneeded liars remorse paragraph atop renderers --- docs/narr/renderers.rst | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) (limited to 'docs/narr/renderers.rst') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 76e9562fa..d888e3376 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -3,18 +3,10 @@ Renderers ========= -In the :ref:`views_chapter` chapter, we said that a view callable must -return a :term:`Response` object. We lied. A :term:`renderer` is a service -that attempts to convert a non-Response return value of a function, class, or -instance that acts as a :term:`view callable` to a :term:`Response` object. - -Overview --------- - -A view needn't *always* return a Response object. If a view happens to -return something which does not implement the Pyramid Response interface, -:app:`Pyramid` will attempt to use a :term:`renderer` to construct a -response. For example: +A view needn't *always* return a :term:`Response` object. If a view +happens to return something which does not implement the Pyramid +Response interface, :app:`Pyramid` will attempt to use a +:term:`renderer` to construct a response. For example: .. code-block:: python :linenos: -- cgit v1.2.3 From 6a790b32db3ff52e568222fd2cbf1437dcfa09b6 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 12 Jan 2011 02:55:31 -0500 Subject: - Document the ``request.override_renderer`` attribute within the narrative "Renderers" chapter in a section named "Overriding A Renderer at Runtime". --- docs/narr/renderers.rst | 51 ++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 46 insertions(+), 5 deletions(-) (limited to 'docs/narr/renderers.rst') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index d888e3376..56d0a5199 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -389,12 +389,12 @@ documentation in :ref:`request_module`. .. _adding_and_overriding_renderers: -Adding and Overriding Renderers -------------------------------- +Adding and Changing Renderers +----------------------------- New templating systems and serializers can be associated with :app:`Pyramid` renderer names. To this end, configuration declarations can be made which -override an existing :term:`renderer factory`, and which add a new renderer +change an existing :term:`renderer factory`, and which add a new renderer factory. Renderers can be registered imperatively using the @@ -546,7 +546,7 @@ set as ``renderer=`` in the view configuration. See also :ref:`renderer_directive` and :meth:`pyramid.config.Configurator.add_renderer`. -Overriding an Existing Renderer +Changing an Existing Renderer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can associate more than one filename extension with the same existing @@ -563,7 +563,7 @@ extension for the same kinds of templates. For example, to associate the After you do this, :app:`Pyramid` will treat templates ending in both the ``.pt`` and ``.zpt`` filename extensions as Chameleon ZPT templates. -To override the default mapping in which files with a ``.pt`` extension are +To change the default mapping in which files with a ``.pt`` extension are rendered via a Chameleon ZPT page template renderer, use a variation on the following in your application's startup code: @@ -585,3 +585,44 @@ the ``name`` attribute to the renderer tag: config.add_renderer(None, 'mypackage.json_renderer_factory') +Overriding A Renderer At Runtime +-------------------------------- + +.. warning:: This is an advanced feature, not typically used by "civilians". + +In some circumstances, it is necessary to instruct the system to ignore the +static renderer declaration provided by the developer in view configuration, +replacing the renderer with another *after a request starts*. For example, +an "omnipresent" XML-RPC implementation that detects that the request is from +an XML-RPC client might override a view configuration statement made by the +user instructing the view to use a template renderer with one that uses an +XML-RPC renderer. This renderer would produce an XML-RPC representation of +the data returned by an arbitrary view callable. + +To use this feature, create a :class:`pyramid.events.NewRequest` +:term:`subscriber` which sniffs at the request data and which conditionally +sets an ``override_renderer`` attribute on the request itself, which is the +*name* of a registered renderer. For example: + +.. code-block:: python + :linenos: + + from pyramid.event import subscriber + from pyramid.event import NewRequest + + @subscriber(NewRequest) + def set_xmlrpc_params(event): + request = event.request + if (request.content_type == 'text/xml' + and request.method == 'POST' + and not 'soapaction' in request.headers + and not 'x-pyramid-avoid-xmlrpc' in request.headers): + params, method = parse_xmlrpc_request(request) + request.xmlrpc_params, request.xmlrpc_method = params, method + request.is_xmlrpc = True + request.override_renderer = 'xmlrpc' + return True + +The result of such a subscriber will be to replace any existing static +renderer configured by the developer with a (notional, nonexistent) XML-RPC +renderer if the request appears to come from an XML-RPC client. -- 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/renderers.rst | 4 ---- 1 file changed, 4 deletions(-) (limited to 'docs/narr/renderers.rst') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 56d0a5199..a80c5a9c2 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -400,10 +400,6 @@ factory. Renderers can be registered imperatively using the :meth:`pyramid.config.Configurator.add_renderer` API. -.. note:: The tasks described in this section can also be performed via - :term:`declarative configuration`. See - :ref:`zcml_adding_and_overriding_renderers`. - For example, to add a renderer which renders views which have a ``renderer`` attribute that is a path that ends in ``.jinja2``: -- cgit v1.2.3 From 7a2ab7108c567bdc792c4e8f999e6ef0dbf24917 Mon Sep 17 00:00:00 2001 From: Chris Beelby Date: Thu, 27 Jan 2011 13:06:57 -0500 Subject: First batch of fixes for typo's and other language issues. --- docs/narr/renderers.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs/narr/renderers.rst') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index a80c5a9c2..91c00057b 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -79,7 +79,7 @@ If the :term:`view callable` associated with a :term:`view configuration` returns a Response object directly (an object with the attributes ``status``, ``headerlist`` and ``app_iter``), any renderer associated with the view configuration is ignored, and the response is passed back to :app:`Pyramid` -unmolested. For example, if your view callable returns an instance of the +unchanged. For example, if your view callable returns an instance of the :class:`pyramid.httpexceptions.HTTPFound` class as a response, no renderer will be employed. @@ -351,7 +351,7 @@ to influence associated response attributes. e.g. ``text/xml``. ``response_headerlist`` - A sequence of tuples describing cookie values that should be set in the + A sequence of tuples describing header values that should be set in the response, e.g. ``[('Set-Cookie', 'abc=123'), ('X-My-Header', 'foo')]``. ``response_status`` @@ -464,7 +464,7 @@ There are essentially two different kinds of renderer factories: .. sidebar:: Asset Specifications - A asset specification is a colon-delimited identifier for a + A asset specification is a colon-delimited identifier for an :term:`asset`. The colon separates a Python :term:`package` name from a package subpath. For example, the asset specification ``my.package:static/baz.css`` identifies the file named @@ -500,8 +500,8 @@ At startup time, when a :term:`view configuration` is encountered, which has a ``name`` attribute that does not contain a dot, the full ``name`` value is used to construct a renderer from the associated renderer factory. In this case, the view configuration will create an instance -of an ``AMFRenderer`` for each view configuration which includes ``amf`` -as its renderer value. The ``name`` passed to the ``AMFRenderer`` +of an ``MyAMFRenderer`` for each view configuration which includes ``amf`` +as its renderer value. The ``name`` passed to the ``MyAMFRenderer`` constructor will always be ``amf``. Here's an example of the registration of a more complicated renderer @@ -534,9 +534,9 @@ typically the filename extension. This extension is used to look up a renderer factory for the configured view. Then the value of ``renderer`` is passed to the factory to create a renderer for the view. In this case, the view configuration will create an instance of a -``Jinja2Renderer`` for each view configuration which includes anything +``MyJinja2Renderer`` for each view configuration which includes anything ending with ``.jinja2`` in its ``renderer`` value. The ``name`` passed -to the ``Jinja2Renderer`` constructor will be the full value that was +to the ``MyJinja2Renderer`` constructor will be the full value that was set as ``renderer=`` in the view configuration. See also :ref:`renderer_directive` and -- 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/renderers.rst | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) (limited to 'docs/narr/renderers.rst') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index a80c5a9c2..792c64fcb 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -23,7 +23,7 @@ dictionary does not implement the Pyramid response interface, so you might believe that this example would fail. However, since a ``renderer`` is associated with the view callable through its :term:`view configuration` (in this case, using a ``renderer`` argument passed to -:func:`pyramid.view.view_config`), if the view does *not* return a Response +:func:`~pyramid.view.view_config`), if the view does *not* return a Response object, the renderer will attempt to convert the result of the view to a response on the developer's behalf. @@ -60,7 +60,7 @@ object serialization techniques. View configuration can vary the renderer associated with a view callable via the ``renderer`` attribute. For example, this call to -:meth:`pyramid.config.Configurator.add_view` associates the ``json`` renderer +:meth:`~pyramid.config.Configurator.add_view` associates the ``json`` renderer with a view callable: .. code-block:: python @@ -187,7 +187,7 @@ values serializable by :func:`json.dumps`. You can configure a view to use the JSON renderer by naming ``json`` as the ``renderer`` argument of a view configuration, e.g. by using -:meth:`pyramid.config.Configurator.add_view`: +:meth:`~pyramid.config.Configurator.add_view`: .. code-block:: python :linenos: @@ -472,7 +472,7 @@ There are essentially two different kinds of renderer factories: :term:`package`. Here's an example of the registration of a simple renderer factory via -:meth:`pyramid.config.Configurator.add_renderer`: +:meth:`~pyramid.config.Configurator.add_renderer`: .. code-block:: python :linenos: @@ -539,9 +539,6 @@ ending with ``.jinja2`` in its ``renderer`` value. The ``name`` passed to the ``Jinja2Renderer`` constructor will be the full value that was set as ``renderer=`` in the view configuration. -See also :ref:`renderer_directive` and -:meth:`pyramid.config.Configurator.add_renderer`. - Changing an Existing Renderer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -595,7 +592,7 @@ user instructing the view to use a template renderer with one that uses an XML-RPC renderer. This renderer would produce an XML-RPC representation of the data returned by an arbitrary view callable. -To use this feature, create a :class:`pyramid.events.NewRequest` +To use this feature, create a :class:`~pyramid.events.NewRequest` :term:`subscriber` which sniffs at the request data and which conditionally sets an ``override_renderer`` attribute on the request itself, which is the *name* of a registered renderer. For example: -- cgit v1.2.3 From 499eef7bc30654a241bafa88f9e492df508a215d Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 27 Jan 2011 23:17:31 -0500 Subject: remove bacticks from interface description --- docs/narr/renderers.rst | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) (limited to 'docs/narr/renderers.rst') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 792c64fcb..d8c58a66a 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -428,21 +428,20 @@ following interface: class RendererFactory: def __init__(self, info): - """ Constructor: ``info`` will be an object having the - the following attributes: ``name`` (the renderer name), ``package`` - (the package that was 'current' at the time the renderer was - registered), ``type`` (the renderer type name), ``registry`` - (the current application registry) and ``settings`` (the - deployment settings dictionary). - """ + """ Constructor: info will be an object having the the + following attributes: name (the renderer name), package + (the package that was 'current' at the time the + renderer was registered), type (the renderer type + name), registry (the current application registry) and + settings (the deployment settings dictionary). """ def __call__(self, value, system): - """ Call a the renderer implementation with the value and - the system value passed in as arguments and return the - result (a string or unicode object). The value is the - return value of a view. The system value is a dictionary - containing available system values (e.g. ``view``, - ``context``, and ``request``). """ + """ Call a the renderer implementation with the value + and the system value passed in as arguments and return + the result (a string or unicode object). The value is + the return value of a view. The system value is a + dictionary containing available system values + (e.g. view, context, and request). """ The formal interface definition of the ``info`` object passed to a renderer factory constructor is available as :class:`pyramid.interfaces.IRendererInfo`. -- cgit v1.2.3 From a42a1efebd872f21c2fa96382248a2459cfb483c Mon Sep 17 00:00:00 2001 From: Kyle Johnson Date: Fri, 28 Jan 2011 20:16:49 -0800 Subject: minor grammar fixes ('a' vs 'an') --- docs/narr/renderers.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/renderers.rst') diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index d8c58a66a..8ec2e3fb8 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -456,14 +456,14 @@ There are essentially two different kinds of renderer factories: such as a template. - A renderer factory which expects to accept a token that does not represent - a filesystem path or a asset specification in the ``name`` + a filesystem path or an asset specification in the ``name`` attribute of the ``info`` object fed to its constructor. These renderer factories are registered with a ``name`` value that does not begin with a dot. These renderer factories are typically object serializers. .. sidebar:: Asset Specifications - A asset specification is a colon-delimited identifier for a + An asset specification is a colon-delimited identifier for an :term:`asset`. The colon separates a Python :term:`package` name from a package subpath. For example, the asset specification ``my.package:static/baz.css`` identifies the file named -- cgit v1.2.3