diff options
Diffstat (limited to 'docs/narr/views.rst')
| -rw-r--r-- | docs/narr/views.rst | 237 |
1 files changed, 114 insertions, 123 deletions
diff --git a/docs/narr/views.rst b/docs/narr/views.rst index cbd8fcfb7..a3fd61098 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -3,10 +3,10 @@ Views ===== -One of the primary jobs of :app:`Pyramid` is to find and invoke a -:term:`view callable` when a :term:`request` reaches your application. View -callables are bits of code which do something interesting in response to a -request made to your application. +One of the primary jobs of :app:`Pyramid` is to find and invoke a :term:`view +callable` when a :term:`request` reaches your application. View callables +are bits of code which do something interesting in response to a request made +to your application. They are the "meat" of any interesting web application. .. note:: @@ -17,48 +17,32 @@ request made to your application. that implements a view *callable*, and the process of view *lookup*. -The :ref:`urldispatch_chapter`, and :ref:`traversal_chapter` chapters -describes how, using information from the :term:`request`, a -:term:`context` resource is computed. But the context resource itself -isn't very useful without an associated :term:`view callable`. A view -callable returns a response to a user, often using the context resource -to do so. +This chapter describes how view callables should be defined. We'll have to +wait until a following chapter (entitled :ref:`view_config_chapter`) to find +out how we actually tell :app:`Pyramid` to wire up view callables to +particular URL patterns and other request circumstances. -The job of actually locating and invoking the "best" :term:`view callable` is -the job of the :term:`view lookup` subsystem. The view lookup subsystem -compares the resource supplied by :term:`resource location` and information -in the :term:`request` against :term:`view configuration` statements made by -the developer to choose the most appropriate view callable for a specific -set of circumstances. - -This chapter describes how view callables work. In the -:ref:`view_config_chapter` chapter, there are details about performing -view configuration, and a detailed explanation of view lookup. +.. index:: + single: view callables View Callables -------------- View callables are, at the risk of sounding obvious, callable Python -objects. Specifically, view callables can be functions, classes, or -instances that implement an ``__call__`` method (making the -instance callable). +objects. Specifically, view callables can be functions, classes, or instances +that implement an ``__call__`` method (making the instance callable). View callables must, at a minimum, accept a single argument named ``request``. This argument represents a :app:`Pyramid` :term:`Request` -object. A request object encapsulates a WSGI environment provided to -:app:`Pyramid` by the upstream :term:`WSGI` server. As you might expect, -the request object contains everything your application needs to know -about the specific HTTP request being made. +object. A request object represents a :term:`WSGI` environment provided to +:app:`Pyramid` by the upstream WSGI server. As you might expect, the request +object contains everything your application needs to know about the specific +HTTP request being made. A view callable's ultimate responsibility is to create a :mod:`Pyramid` -:term:`Response` object. This can be done by creating the response object in -the view callable code and returning it directly, as we will be doing in this -chapter. However, if a view callable does not return a response itself, it -can be configured to use a :term:`renderer` that converts its return value -into a :term:`Response` object. Using renderers is the common way that -templates are used with view callables to generate markup: see the -:ref:`renderers_chapter` chapter for details. In some cases, a response may -also be generated by raising an exception within a view callable. +:term:`Response` object. This can be done by creating a :term:`Response` +object in the view callable code and returning it directly or by raising +special kinds of exceptions from within the body of a view callable. .. index:: single: view calling convention @@ -129,85 +113,6 @@ statements with different ``attr`` values, each pointing at a different method of the class if you'd like the class to represent a collection of related view callables. -.. note:: A package named :term:`pyramid_handlers` (available from PyPI) - provides an analogue of :term:`Pylons` -style "controllers", which are a - special kind of view class which provides more automation when your - application uses :term:`URL dispatch` solely. - -.. index:: - single: view calling convention - -.. _request_and_context_view_definitions: - -Alternate View Callable Argument/Calling Conventions ----------------------------------------------------- - -Usually, view callables are defined to accept only a single argument: -``request``. However, view callables may alternately be defined as classes, -functions, or any callable that accept *two* positional arguments: a -:term:`context` resource as the first argument and a :term:`request` as the -second argument. - -The :term:`context` and :term:`request` arguments passed to a view function -defined in this style can be defined as follows: - -context - - The :term:`resource` object found via tree :term:`traversal` or :term:`URL - dispatch`. - -request - A :app:`Pyramid` Request object representing the current WSGI request. - -The following types work as view callables in this style: - -#. Functions that accept two arguments: ``context``, and ``request``, - e.g.: - - .. code-block:: python - :linenos: - - from pyramid.response import Response - - def view(context, request): - return Response('OK') - -#. Classes that have an ``__init__`` method that accepts ``context, - request`` and a ``__call__`` method which accepts no arguments, e.g.: - - .. code-block:: python - :linenos: - - from pyramid.response import Response - - class view(object): - def __init__(self, context, request): - self.context = context - self.request = request - - def __call__(self): - return Response('OK') - -#. Arbitrary callables that have a ``__call__`` method that accepts - ``context, request``, e.g.: - - .. code-block:: python - :linenos: - - from pyramid.response import Response - - class View(object): - def __call__(self, context, request): - return Response('OK') - view = View() # this is the view callable - -This style of calling convention is most useful for :term:`traversal` based -applications, where the context object is frequently used within the view -callable code itself. - -No matter which view calling convention is used, the view code always has -access to the context via ``request.context``. - .. index:: single: view response single: response @@ -234,15 +139,16 @@ implements the :term:`Response` interface is to return a inherit from :class:`pyramid.response.Response`. For example, an instance of the class :class:`pyramid.httpexceptions.HTTPFound` is also a valid response object because it inherits from :class:`~pyramid.response.Response`. For -examples, see :ref:`http_exceptions` and ref:`http_redirect`. +examples, see :ref:`http_exceptions` and :ref:`http_redirect`. + +.. note:: -You can also return objects from view callables that aren't instances of (or -instances of classes which are subclasses of) -:class:`pyramid.response.Response` in various circumstances. This can be -helpful when writing tests and when attempting to share code between view -callables. See :ref:`renderers_chapter` for the common way to allow for -this. A much less common way to allow for view callables to return -non-Response objects is documented in :ref:`using_iresponse`. + You can also return objects from view callables that aren't instances of + :class:`pyramid.response.Response` in various circumstances. This can be + helpful when writing tests and when attempting to share code between view + callables. See :ref:`renderers_chapter` for the common way to allow for + this. A much less common way to allow for view callables to return + non-Response objects is documented in :ref:`using_iresponse`. .. index:: single: view exceptions @@ -483,7 +389,7 @@ various other clients. In :app:`Pyramid`, form submission handling logic is always part of a :term:`view`. For a general overview of how to handle form submission data using the :term:`WebOb` API, see :ref:`webob_chapter` and `"Query and POST variables" within the WebOb documentation -<http://pythonpaste.org/webob/reference.html#query-post-variables>`_. +<http://docs.webob.org/en/latest/reference.html#query-post-variables>`_. :app:`Pyramid` defers to WebOb for its request and response implementations, and handling form submission data is a property of the request implementation. Understanding WebOb's request API is the key to @@ -591,3 +497,88 @@ using your own response object, you will need to ensure you do this yourself. configuration. The keys are still (byte) strings. +.. index:: + single: view calling convention + +.. _request_and_context_view_definitions: + +Alternate View Callable Argument/Calling Conventions +---------------------------------------------------- + +Usually, view callables are defined to accept only a single argument: +``request``. However, view callables may alternately be defined as classes, +functions, or any callable that accept *two* positional arguments: a +:term:`context` resource as the first argument and a :term:`request` as the +second argument. + +The :term:`context` and :term:`request` arguments passed to a view function +defined in this style can be defined as follows: + +context + + The :term:`resource` object found via tree :term:`traversal` or :term:`URL + dispatch`. + +request + A :app:`Pyramid` Request object representing the current WSGI request. + +The following types work as view callables in this style: + +#. Functions that accept two arguments: ``context``, and ``request``, + e.g.: + + .. code-block:: python + :linenos: + + from pyramid.response import Response + + def view(context, request): + return Response('OK') + +#. Classes that have an ``__init__`` method that accepts ``context, + request`` and a ``__call__`` method which accepts no arguments, e.g.: + + .. code-block:: python + :linenos: + + from pyramid.response import Response + + class view(object): + def __init__(self, context, request): + self.context = context + self.request = request + + def __call__(self): + return Response('OK') + +#. Arbitrary callables that have a ``__call__`` method that accepts + ``context, request``, e.g.: + + .. code-block:: python + :linenos: + + from pyramid.response import Response + + class View(object): + def __call__(self, context, request): + return Response('OK') + view = View() # this is the view callable + +This style of calling convention is most useful for :term:`traversal` based +applications, where the context object is frequently used within the view +callable code itself. + +No matter which view calling convention is used, the view code always has +access to the context via ``request.context``. + +.. index:: + single: Pylons-style controller dispatch + +Pylons-1.0-Style "Controller" Dispatch +-------------------------------------- + +A package named :term:`pyramid_handlers` (available from PyPI) provides an +analogue of :term:`Pylons` -style "controllers", which are a special kind of +view class which provides more automation when your application uses +:term:`URL dispatch` solely. + |