From 1ffb8e3cc21603b29ccd78152f82cca7f61a09b1 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 16 May 2011 02:11:56 -0400 Subject: - Added API docs for ``pyramid.httpexceptions.abort`` and ``pyramid.httpexceptions.redirect``. - Added "HTTP Exceptions" section to Views narrative chapter including a description of ``pyramid.httpexceptions.abort``; adjusted redirect section to note ``pyramid.httpexceptions.redirect``. - A default exception view for the context ``webob.exc.HTTPException`` (aka ``pyramid.httpexceptions.HTTPException``) is now registered by default. This means that an instance of any exception class imported from ``pyramid.httpexceptions`` (such as ``HTTPFound``) can now be raised from within view code; when raised, this exception view will render the exception to a response. - New functions named ``pyramid.httpexceptions.abort`` and ``pyramid.httpexceptions.redirect`` perform the equivalent of their Pylons brethren when an HTTP exception handler is registered. These functions take advantage of the newly registered exception view for ``webob.exc.HTTPException``. - The Configurator now accepts an additional keyword argument named ``httpexception_view``. By default, this argument is populated with a default exception view function that will be used when an HTTP exception is raised. When ``None`` is passed for this value, an exception view for HTTP exceptions will not be registered. Passing ``None`` returns the behavior of raising an HTTP exception to that of Pyramid 1.0 (the exception will propagate to middleware and to the WSGI server). --- docs/narr/views.rst | 249 +++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 179 insertions(+), 70 deletions(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 5c9bd91af..465cd3c0d 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -51,14 +51,14 @@ 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. +: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. .. index:: single: view calling convention @@ -234,8 +234,8 @@ You don't need to always use :class:`~pyramid.response.Response` to represent a response. :app:`Pyramid` provides a range of different "exception" classes which can act as response objects too. For example, an instance of the class :class:`pyramid.httpexceptions.HTTPFound` is also a valid response object -(see :ref:`http_redirect`). A view can actually return any object that has -the following attributes. +(see :ref:`http_exceptions` and ref:`http_redirect`). A view can actually +return any object that has the following attributes. status The HTTP status code (including the name) for the response as a string. @@ -254,46 +254,6 @@ app_iter These attributes form the structure of the "Pyramid Response interface". -.. index:: - single: view http redirect - single: http redirect (from a view) - -.. _http_redirect: - -Using a View Callable to Do an HTTP Redirect --------------------------------------------- - -You can issue an HTTP redirect from within a view by returning a particular -kind of response. - -.. code-block:: python - :linenos: - - from pyramid.httpexceptions import HTTPFound - - def myview(request): - return HTTPFound(location='http://example.com') - -All exception types from the :mod:`pyramid.httpexceptions` module implement -the :term:`Response` interface; any can be returned as the response from a -view. See :mod:`pyramid.httpexceptions` for the documentation for the -``HTTPFound`` exception; it also includes other response types that imply -other HTTP response codes, such as ``HTTPUnauthorized`` for ``401 -Unauthorized``. - -.. note:: - - Although exception types from the :mod:`pyramid.httpexceptions` module are - in fact bona fide Python :class:`Exception` types, the :app:`Pyramid` view - machinery expects them to be *returned* by a view callable rather than - *raised*. - - It is possible, however, in Python 2.5 and above, to configure an - *exception view* to catch these exceptions, and return an appropriate - :class:`~pyramid.response.Response`. The simplest such view could just - catch and return the original exception. See :ref:`exception_views` for - more details. - .. index:: single: view exceptions @@ -304,13 +264,21 @@ Using Special Exceptions In View Callables Usually when a Python exception is raised within a view callable, :app:`Pyramid` allows the exception to propagate all the way out to the -:term:`WSGI` server which invoked the application. +:term:`WSGI` server which invoked the application. It is usually caught and +logged there. -However, for convenience, two special exceptions exist which are always -handled by :app:`Pyramid` itself. These are -:exc:`pyramid.exceptions.NotFound` and :exc:`pyramid.exceptions.Forbidden`. -Both are exception classes which accept a single positional constructor -argument: a ``message``. +However, for convenience, a special set of exceptions exists. When one of +these exceptions is raised within a view callable, it will always cause +:app:`Pyramid` to generate a response. Two categories of special exceptions +exist: internal exceptions and HTTP exceptions. + +Internal Exceptions +~~~~~~~~~~~~~~~~~~~ + +:exc:`pyramid.exceptions.NotFound` and :exc:`pyramid.exceptions.Forbidden` +are exceptions often raised by Pyramid itself when it (respectively) cannot +find a view to service a request or when authorization was forbidden by a +security policy. However, they can also be raised by application developers. If :exc:`~pyramid.exceptions.NotFound` is raised within view code, the result of the :term:`Not Found View` will be returned to the user agent which @@ -320,22 +288,100 @@ If :exc:`~pyramid.exceptions.Forbidden` is raised within view code, the result of the :term:`Forbidden View` will be returned to the user agent which performed the request. -In all cases, the message provided to the exception constructor is made -available to the view which :app:`Pyramid` invokes as +Both are exception classes which accept a single positional constructor +argument: a ``message``. In all cases, the message provided to the exception +constructor is made available to the view which :app:`Pyramid` invokes as ``request.exception.args[0]``. +An example: + +.. code-block:: python + :linenos: + + from pyramid.exceptions import NotFound + + def aview(request): + raise NotFound('not found!') + +Internal exceptions may not be *returned* in order to generate a response, +they must always be *raised*. + +.. index:: + single: HTTP exceptions + +.. _http_exceptions: + +HTTP Exceptions +~~~~~~~~~~~~~~~ + +All exception classes documented in the :mod:`pyramid.httpexceptions` module +implement the :term:`Response` interface; an instance of any of these classes +can be returned or raised from within a view. The instance will be used as +as the view's response. + +For example, the :class:`pyramid.httpexceptions.HTTPUnauthorized` exception +can be raised. This will cause a response to be generated with a ``401 +Unauthorized`` status: + +.. code-block:: python + :linenos: + + from pyramid.httpexceptions import HTTPUnauthorized + + def aview(request): + raise HTTPUnauthorized() + +A shortcut for importing and raising an HTTP exception is the +:func:`pyramid.httpexceptions.abort` function. This function accepts an HTTP +status code and raises the corresponding HTTP exception. For example, to +raise HTTPUnauthorized, instead of the above, you could do: + +.. code-block:: python + :linenos: + + from pyramid.httpexceptions import abort + + def aview(request): + abort(401) + +This is the case because ``401`` is the HTTP status code for "HTTP +Unauthorized". Therefore, ``abort(401)`` is functionally equivalent to +``raise HTTPUnauthorized()``. Other exceptions in +:mod:`pyramid.httpexceptions` can be raised via +:func:`pyramid.httpexceptions.abort` as well, as long as the status code +associated with the exception is provided to the function. + +An HTTP exception, instead of being raised, can alternately be *returned* +(HTTP exceptions are also valid response objects): + +.. code-block:: python + :linenos: + + from pyramid.httpexceptions import HTTPUnauthorized + + def aview(request): + return HTTPUnauthorized() + +Note that :class:`pyramid.exceptions.NotFound` is *not* the same as +:class:`pyramid.httpexceptions.HTTPNotFound`. If the latter is raised, the +:term:`Not Found view` will *not* be called automatically. Likewise, +:class:`pyramid.exceptions.Foribdden` is not the same exception as +:class:`pyramid.httpexceptions.HTTPForbidden`. If the latter is raised, the +:term:`Forbidden view` will not be called automatically. + .. index:: single: exception views .. _exception_views: -Exception Views ---------------- +Custom Exception Views +---------------------- -The machinery which allows the special :exc:`~pyramid.exceptions.NotFound` and -:exc:`~pyramid.exceptions.Forbidden` exceptions to be caught by specialized -views as described in :ref:`special_exceptions_in_callables` can also be used -by application developers to convert arbitrary exceptions to responses. +The machinery which allows :exc:`~pyramid.exceptions.NotFound`, +:exc:`~pyramid.exceptions.Forbidden` and HTTP exceptions to be caught by +specialized views as described in :ref:`special_exceptions_in_callables` can +also be used by application developers to convert arbitrary exceptions to +responses. To register a view that should be called whenever a particular exception is raised from with :app:`Pyramid` view code, use the exception class or one of @@ -359,6 +405,7 @@ raises a ``helloworld.exceptions.ValidationFailure`` exception: .. code-block:: python :linenos: + from pyramid.view import view_config from helloworld.exceptions import ValidationFailure @view_config(context=ValidationFailure) @@ -380,12 +427,13 @@ exception view registration: :linenos: from pyramid.view import view_config - from pyramid.exceptions import NotFound - from pyramid.httpexceptions import HTTPNotFound + from helloworld.exceptions import ValidationFailure - @view_config(context=NotFound, route_name='home') - def notfound_view(request): - return HTTPNotFound() + @view_config(context=ValidationFailure, route_name='home') + def failed_validation(exc, request): + response = Response('Failed validation: %s' % exc.msg) + response.status_int = 500 + return response The above exception view names the ``route_name`` of ``home``, meaning that it will only be called when the route matched has a name of ``home``. You @@ -407,7 +455,68 @@ exception views which have a name will be ignored. can use an exception as ``context`` for a normal view. Exception views can be configured with any view registration mechanism: -``@view_config`` decorator, ZCML, or imperative ``add_view`` styles. +``@view_config`` decorator or imperative ``add_view`` styles. + +.. index:: + single: view http redirect + single: http redirect (from a view) + +.. _http_redirect: + +Using a View Callable to Do an HTTP Redirect +-------------------------------------------- + +Two methods exist to redirect to another URL from within a view callable: a +short form and a long form. The short form should be preferred when +possible. + +Short Form +~~~~~~~~~~ + +You can issue an HTTP redirect from within a view callable by using the +:func:`pyramid.httpexceptions.redirect` function. This function raises an +:class:`pyramid.httpexceptions.HTTPFound` exception (a "302"), which is +caught by an exception handler and turned into a response. + +.. code-block:: python + :linenos: + + from pyramid.httpexceptions import redirect + + def myview(request): + redirect('http://example.com') + +Long Form +~~~~~~~~~ + +You can issue an HTTP redirect from within a view "by hand" instead of +relying on the :func:`pyramid.httpexceptions.redirect` function to do it for +you. + +To do so, you can *return* a :class:`pyramid.httpexceptions.HTTPFound` +instance. + +.. code-block:: python + :linenos: + + from pyramid.httpexceptions import HTTPFound + + def myview(request): + return HTTPFound(location='http://example.com') + +Or, alternately, you can *raise* an HTTPFound exception instead of returning +one. + +.. code-block:: python + :linenos: + + from pyramid.httpexceptions import HTTPFound + + def myview(request): + raise HTTPFound(location='http://example.com') + +The above form of generating a response by raising HTTPFound is completely +equivalent to ``redirect('http://example.com')``. .. index:: single: unicode, views, and forms -- cgit v1.2.3 From e1e0df9ff85d5d31b355527549e0b5654cce3af9 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 16 May 2011 02:19:37 -0400 Subject: typo --- docs/narr/views.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 465cd3c0d..66e9919e2 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -365,7 +365,7 @@ An HTTP exception, instead of being raised, can alternately be *returned* Note that :class:`pyramid.exceptions.NotFound` is *not* the same as :class:`pyramid.httpexceptions.HTTPNotFound`. If the latter is raised, the :term:`Not Found view` will *not* be called automatically. Likewise, -:class:`pyramid.exceptions.Foribdden` is not the same exception as +:class:`pyramid.exceptions.Forbidden` is not the same exception as :class:`pyramid.httpexceptions.HTTPForbidden`. If the latter is raised, the :term:`Forbidden view` will not be called automatically. -- cgit v1.2.3 From a7e625785f65c41e5a6dc017b31bd0d74821474e Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 31 May 2011 14:40:05 -0400 Subject: the canonical import location for HTTP exceptions/responses is now pyramid.response --- docs/narr/views.rst | 82 ++++++++++++++++++++++++----------------------------- 1 file changed, 37 insertions(+), 45 deletions(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 66e9919e2..73a7c2e2a 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -233,7 +233,7 @@ implements the :term:`Response` interface is to return a You don't need to always use :class:`~pyramid.response.Response` to represent a response. :app:`Pyramid` provides a range of different "exception" classes which can act as response objects too. For example, an instance of the class -:class:`pyramid.httpexceptions.HTTPFound` is also a valid response object +:class:`pyramid.response.HTTPFound` is also a valid response object (see :ref:`http_exceptions` and ref:`http_redirect`). A view can actually return any object that has the following attributes. @@ -275,17 +275,18 @@ exist: internal exceptions and HTTP exceptions. Internal Exceptions ~~~~~~~~~~~~~~~~~~~ -:exc:`pyramid.exceptions.NotFound` and :exc:`pyramid.exceptions.Forbidden` -are exceptions often raised by Pyramid itself when it (respectively) cannot -find a view to service a request or when authorization was forbidden by a -security policy. However, they can also be raised by application developers. +:exc:`pyramid.response.HTTPNotFound` and +:exc:`pyramid.response.HTTPForbidden` are exceptions often raised by Pyramid +itself when it (respectively) cannot find a view to service a request or when +authorization was forbidden by a security policy. However, they can also be +raised by application developers. -If :exc:`~pyramid.exceptions.NotFound` is raised within view code, the result -of the :term:`Not Found View` will be returned to the user agent which +If :exc:`~pyramid.response.HTTPNotFound` is raised within view code, the +result of the :term:`Not Found View` will be returned to the user agent which performed the request. -If :exc:`~pyramid.exceptions.Forbidden` is raised within view code, the result -of the :term:`Forbidden View` will be returned to the user agent which +If :exc:`~pyramid.response.HTTPForbidden` is raised within view code, the +result of the :term:`Forbidden View` will be returned to the user agent which performed the request. Both are exception classes which accept a single positional constructor @@ -298,13 +299,10 @@ An example: .. code-block:: python :linenos: - from pyramid.exceptions import NotFound + from pyramid.response import HTTPNotFound def aview(request): - raise NotFound('not found!') - -Internal exceptions may not be *returned* in order to generate a response, -they must always be *raised*. + raise HTTPNotFound('not found!') .. index:: single: HTTP exceptions @@ -314,32 +312,33 @@ they must always be *raised*. HTTP Exceptions ~~~~~~~~~~~~~~~ -All exception classes documented in the :mod:`pyramid.httpexceptions` module -implement the :term:`Response` interface; an instance of any of these classes -can be returned or raised from within a view. The instance will be used as -as the view's response. +All classes documented in the :mod:`pyramid.response` module as inheriting +from the :class:`pryamid.response.Response` object implement the +:term:`Response` interface; an instance of any of these classes can be +returned or raised from within a view. The instance will be used as as the +view's response. -For example, the :class:`pyramid.httpexceptions.HTTPUnauthorized` exception +For example, the :class:`pyramid.response.HTTPUnauthorized` exception can be raised. This will cause a response to be generated with a ``401 Unauthorized`` status: .. code-block:: python :linenos: - from pyramid.httpexceptions import HTTPUnauthorized + from pyramid.response import HTTPUnauthorized def aview(request): raise HTTPUnauthorized() A shortcut for importing and raising an HTTP exception is the -:func:`pyramid.httpexceptions.abort` function. This function accepts an HTTP +:func:`pyramid.response.abort` function. This function accepts an HTTP status code and raises the corresponding HTTP exception. For example, to raise HTTPUnauthorized, instead of the above, you could do: .. code-block:: python :linenos: - from pyramid.httpexceptions import abort + from pyramid.response import abort def aview(request): abort(401) @@ -347,8 +346,8 @@ raise HTTPUnauthorized, instead of the above, you could do: This is the case because ``401`` is the HTTP status code for "HTTP Unauthorized". Therefore, ``abort(401)`` is functionally equivalent to ``raise HTTPUnauthorized()``. Other exceptions in -:mod:`pyramid.httpexceptions` can be raised via -:func:`pyramid.httpexceptions.abort` as well, as long as the status code +:mod:`pyramid.response` can be raised via +:func:`pyramid.response.abort` as well, as long as the status code associated with the exception is provided to the function. An HTTP exception, instead of being raised, can alternately be *returned* @@ -357,18 +356,11 @@ An HTTP exception, instead of being raised, can alternately be *returned* .. code-block:: python :linenos: - from pyramid.httpexceptions import HTTPUnauthorized + from pyramid.response import HTTPUnauthorized def aview(request): return HTTPUnauthorized() -Note that :class:`pyramid.exceptions.NotFound` is *not* the same as -:class:`pyramid.httpexceptions.HTTPNotFound`. If the latter is raised, the -:term:`Not Found view` will *not* be called automatically. Likewise, -:class:`pyramid.exceptions.Forbidden` is not the same exception as -:class:`pyramid.httpexceptions.HTTPForbidden`. If the latter is raised, the -:term:`Forbidden view` will not be called automatically. - .. index:: single: exception views @@ -377,11 +369,11 @@ Note that :class:`pyramid.exceptions.NotFound` is *not* the same as Custom Exception Views ---------------------- -The machinery which allows :exc:`~pyramid.exceptions.NotFound`, -:exc:`~pyramid.exceptions.Forbidden` and HTTP exceptions to be caught by -specialized views as described in :ref:`special_exceptions_in_callables` can -also be used by application developers to convert arbitrary exceptions to -responses. +The machinery which allows :exc:`~pyramid.response.HTTPNotFound`, +:exc:`~pyramid.response.HTTPForbidden` and other responses to be used as +exceptions and caught by specialized views as described in +:ref:`special_exceptions_in_callables` can also be used by application +developers to convert arbitrary exceptions to responses. To register a view that should be called whenever a particular exception is raised from with :app:`Pyramid` view code, use the exception class or one of @@ -474,14 +466,14 @@ Short Form ~~~~~~~~~~ You can issue an HTTP redirect from within a view callable by using the -:func:`pyramid.httpexceptions.redirect` function. This function raises an -:class:`pyramid.httpexceptions.HTTPFound` exception (a "302"), which is -caught by an exception handler and turned into a response. +:func:`pyramid.response.redirect` function. This function raises an +:class:`pyramid.response.HTTPFound` exception (a "302"), which is caught by +the default exception response handler and turned into a response. .. code-block:: python :linenos: - from pyramid.httpexceptions import redirect + from pyramid.response import redirect def myview(request): redirect('http://example.com') @@ -490,16 +482,16 @@ Long Form ~~~~~~~~~ You can issue an HTTP redirect from within a view "by hand" instead of -relying on the :func:`pyramid.httpexceptions.redirect` function to do it for +relying on the :func:`pyramid.response.redirect` function to do it for you. -To do so, you can *return* a :class:`pyramid.httpexceptions.HTTPFound` +To do so, you can *return* a :class:`pyramid.response.HTTPFound` instance. .. code-block:: python :linenos: - from pyramid.httpexceptions import HTTPFound + from pyramid.response import HTTPFound def myview(request): return HTTPFound(location='http://example.com') @@ -510,7 +502,7 @@ one. .. code-block:: python :linenos: - from pyramid.httpexceptions import HTTPFound + from pyramid.response import HTTPFound def myview(request): raise HTTPFound(location='http://example.com') -- cgit v1.2.3 From 99edc51a3b05309c7f5d98ff96289ec51b1d7660 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 11 Jun 2011 05:35:27 -0400 Subject: - Pyramid now expects Response objects to have a __call__ method which implements the WSGI application interface instead of the three webob attrs status, headerlist and app_iter. Backwards compatibility exists for code which returns response objects that do not have a __call__. - pyramid.response.Response is no longer an exception (and therefore cannot be raised in order to generate a response). - Changed my mind about moving stuff from pyramid.httpexceptions to pyramid.response. The stuff I moved over has been moved back to pyramid.httpexceptions. --- docs/narr/views.rst | 209 ++++++++++++++++++++++------------------------------ 1 file changed, 88 insertions(+), 121 deletions(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 73a7c2e2a..990828f80 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -230,29 +230,29 @@ implements the :term:`Response` interface is to return a def view(request): return Response('OK') -You don't need to always use :class:`~pyramid.response.Response` to represent -a response. :app:`Pyramid` provides a range of different "exception" classes -which can act as response objects too. For example, an instance of the class -:class:`pyramid.response.HTTPFound` is also a valid response object -(see :ref:`http_exceptions` and ref:`http_redirect`). A view can actually -return any object that has the following attributes. - -status - The HTTP status code (including the name) for the response as a string. - E.g. ``200 OK`` or ``401 Unauthorized``. - -headerlist - A sequence of tuples representing the list of headers that should be - set in the response. E.g. ``[('Content-Type', 'text/html'), - ('Content-Length', '412')]`` - -app_iter - An iterable representing the body of the response. This can be a - list, e.g. ``['Hello - world!']`` or it can be a file-like object, or any - other sort of iterable. - -These attributes form the structure of the "Pyramid Response interface". +You don't need to use :class:`~pyramid.response.Response` to represent a +response. A view can actually return any object that has a ``__call__`` +method that implements the :term:`WSGI` application call interface. For +example, an instance of the following class could be successfully returned by +a view callable as a response object: + +.. code-block:: python + :linenos: + + class SimpleResponse(object): + def __call__(self, environ, start_response): + """ Call the ``start_response`` callback and return + an iterable """ + body = 'Hello World!' + headers = [('Content-Type', 'text/plain'), + ('Content-Length', str(len(body)))] + start_response('200 OK', headers) + return [body] + +:app:`Pyramid` provides a range of different "exception" classes which can +act as response objects too. For example, an instance of the class +:class:`pyramid.httpexceptions.HTTPFound` is also a valid response object +(see :ref:`http_exceptions` and ref:`http_redirect`). .. index:: single: view exceptions @@ -269,40 +269,8 @@ logged there. However, for convenience, a special set of exceptions exists. When one of these exceptions is raised within a view callable, it will always cause -:app:`Pyramid` to generate a response. Two categories of special exceptions -exist: internal exceptions and HTTP exceptions. - -Internal Exceptions -~~~~~~~~~~~~~~~~~~~ - -:exc:`pyramid.response.HTTPNotFound` and -:exc:`pyramid.response.HTTPForbidden` are exceptions often raised by Pyramid -itself when it (respectively) cannot find a view to service a request or when -authorization was forbidden by a security policy. However, they can also be -raised by application developers. - -If :exc:`~pyramid.response.HTTPNotFound` is raised within view code, the -result of the :term:`Not Found View` will be returned to the user agent which -performed the request. - -If :exc:`~pyramid.response.HTTPForbidden` is raised within view code, the -result of the :term:`Forbidden View` will be returned to the user agent which -performed the request. - -Both are exception classes which accept a single positional constructor -argument: a ``message``. In all cases, the message provided to the exception -constructor is made available to the view which :app:`Pyramid` invokes as -``request.exception.args[0]``. - -An example: - -.. code-block:: python - :linenos: - - from pyramid.response import HTTPNotFound - - def aview(request): - raise HTTPNotFound('not found!') +:app:`Pyramid` to generate a response. These are known as :term:`HTTP +exception` objects. .. index:: single: HTTP exceptions @@ -312,54 +280,77 @@ An example: HTTP Exceptions ~~~~~~~~~~~~~~~ -All classes documented in the :mod:`pyramid.response` module as inheriting -from the :class:`pryamid.response.Response` object implement the -:term:`Response` interface; an instance of any of these classes can be -returned or raised from within a view. The instance will be used as as the -view's response. +All classes documented in the :mod:`pyramid.httpexceptions` module documented +as inheriting from the :class:`pryamid.httpexceptions.HTTPException` are +:term:`http exception` objects. An instances of an HTTP exception object may +either be *returned* or *raised* from within view code. In either case +(return or raise) the instance will be used as as the view's response. -For example, the :class:`pyramid.response.HTTPUnauthorized` exception +For example, the :class:`pyramid.httpexceptions.HTTPUnauthorized` exception can be raised. This will cause a response to be generated with a ``401 Unauthorized`` status: .. code-block:: python :linenos: - from pyramid.response import HTTPUnauthorized + from pyramid.httpexceptions import HTTPUnauthorized def aview(request): raise HTTPUnauthorized() -A shortcut for importing and raising an HTTP exception is the -:func:`pyramid.response.abort` function. This function accepts an HTTP -status code and raises the corresponding HTTP exception. For example, to -raise HTTPUnauthorized, instead of the above, you could do: +An HTTP exception, instead of being raised, can alternately be *returned* +(HTTP exceptions are also valid response objects): .. code-block:: python :linenos: - from pyramid.response import abort + from pyramid.httpexceptions import HTTPUnauthorized def aview(request): - abort(401) - -This is the case because ``401`` is the HTTP status code for "HTTP -Unauthorized". Therefore, ``abort(401)`` is functionally equivalent to -``raise HTTPUnauthorized()``. Other exceptions in -:mod:`pyramid.response` can be raised via -:func:`pyramid.response.abort` as well, as long as the status code -associated with the exception is provided to the function. + return HTTPUnauthorized() -An HTTP exception, instead of being raised, can alternately be *returned* -(HTTP exceptions are also valid response objects): +A shortcut for creating an HTTP exception is the +:func:`pyramid.httpexceptions.responsecode` function. This function accepts +an HTTP status code and returns the corresponding HTTP exception. For +example, instead of importing and constructing a +:class:`~pyramid.httpexceptions.HTTPUnauthorized` response object, you can +use the :func:`~pyramid.httpexceptions.responsecode` function to construct +and return the same object. .. code-block:: python :linenos: - from pyramid.response import HTTPUnauthorized + from pyramid.httpexceptions import responsecode def aview(request): - return HTTPUnauthorized() + raise responsecode(401) + +This is the case because ``401`` is the HTTP status code for "HTTP +Unauthorized". Therefore, ``raise responsecode(401)`` is functionally +equivalent to ``raise HTTPUnauthorized()``. Documentation which maps each +HTTP response code to its purpose and its associated HTTP exception object is +provided within :mod:`pyramid.httpexceptions`. + +How Pyramid Uses HTTP Exceptions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +HTTP exceptions are meant to be used directly by application application +developers. However, Pyramid itself will raise two HTTP exceptions at +various points during normal operations: +:exc:`pyramid.httpexceptions.HTTPNotFound` and +:exc:`pyramid.httpexceptions.HTTPForbidden`. Pyramid will raise the +:exc:`~pyramid.httpexceptions.HTTPNotFound` exception are raised when it +cannot find a view to service a request. Pyramid will raise the +:exc:`~pyramid.httpexceptions.Forbidden` exception or when authorization was +forbidden by a security policy. + +If :exc:`~pyramid.httpexceptions.HTTPNotFound` is raised by Pyramid itself or +within view code, the result of the :term:`Not Found View` will be returned +to the user agent which performed the request. + +If :exc:`~pyramid.httpexceptions.HTTPForbidden` is raised by Pyramid itself +within view code, the result of the :term:`Forbidden View` will be returned +to the user agent which performed the request. .. index:: single: exception views @@ -369,11 +360,10 @@ An HTTP exception, instead of being raised, can alternately be *returned* Custom Exception Views ---------------------- -The machinery which allows :exc:`~pyramid.response.HTTPNotFound`, -:exc:`~pyramid.response.HTTPForbidden` and other responses to be used as -exceptions and caught by specialized views as described in -:ref:`special_exceptions_in_callables` can also be used by application -developers to convert arbitrary exceptions to responses. +The machinery which allows HTTP exceptions to be raised and caught by +specialized views as described in :ref:`special_exceptions_in_callables` can +also be used by application developers to convert arbitrary exceptions to +responses. To register a view that should be called whenever a particular exception is raised from with :app:`Pyramid` view code, use the exception class or one of @@ -409,8 +399,8 @@ raises a ``helloworld.exceptions.ValidationFailure`` exception: Assuming that a :term:`scan` was run to pick up this view registration, this view callable will be invoked whenever a ``helloworld.exceptions.ValidationFailure`` is raised by your application's -view code. The same exception raised by a custom root factory or a custom -traverser is also caught and hooked. +view code. The same exception raised by a custom root factory, a custom +traverser, or a custom view or route predicate is also caught and hooked. Other normal view predicates can also be used in combination with an exception view registration: @@ -458,57 +448,34 @@ Exception views can be configured with any view registration mechanism: Using a View Callable to Do an HTTP Redirect -------------------------------------------- -Two methods exist to redirect to another URL from within a view callable: a -short form and a long form. The short form should be preferred when -possible. - -Short Form -~~~~~~~~~~ - -You can issue an HTTP redirect from within a view callable by using the -:func:`pyramid.response.redirect` function. This function raises an -:class:`pyramid.response.HTTPFound` exception (a "302"), which is caught by -the default exception response handler and turned into a response. - -.. code-block:: python - :linenos: - - from pyramid.response import redirect - - def myview(request): - redirect('http://example.com') - -Long Form -~~~~~~~~~ - -You can issue an HTTP redirect from within a view "by hand" instead of -relying on the :func:`pyramid.response.redirect` function to do it for -you. +You can issue an HTTP redirect by using the +:class:`pyramid.httpexceptions.HTTPFound` class. Raising or returning an +instance of this class will cause the client to receive a "302 Found" +response. -To do so, you can *return* a :class:`pyramid.response.HTTPFound` +To do so, you can *return* a :class:`pyramid.httpexceptions.HTTPFound` instance. .. code-block:: python :linenos: - from pyramid.response import HTTPFound + from pyramid.httpexceptions import HTTPFound def myview(request): return HTTPFound(location='http://example.com') -Or, alternately, you can *raise* an HTTPFound exception instead of returning -one. +Alternately, you can *raise* an HTTPFound exception instead of returning one. .. code-block:: python :linenos: - from pyramid.response import HTTPFound + from pyramid.httpexceptions import HTTPFound def myview(request): raise HTTPFound(location='http://example.com') -The above form of generating a response by raising HTTPFound is completely -equivalent to ``redirect('http://example.com')``. +When the instance is raised, it is caught by the default :term:`exception +response` handler and turned into a response. .. index:: single: unicode, views, and forms -- cgit v1.2.3 From d868fff7597c5a05acd1f5c024fc45dde9880413 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 13 Jun 2011 06:17:00 -0400 Subject: - Remove IResponder abstraction in favor of more general IResponse abstraction. - It is now possible to return an arbitrary object from a Pyramid view callable even if a renderer is not used, as long as a suitable adapter to ``pyramid.interfaces.IResponse`` is registered for the type of the returned object. See the section in the Hooks chapter of the documentation entitled "Changing How Pyramid Treats View Responses". - The Pyramid router now, by default, expects response objects returned from view callables to implement the ``pyramid.interfaces.IResponse`` interface. Unlike the Pyramid 1.0 version of this interface, objects which implement IResponse now must define a ``__call__`` method that accepts ``environ`` and ``start_response``, and which returns an ``app_iter`` iterable, among other things. Previously, it was possible to return any object which had the three WebOb ``app_iter``, ``headerlist``, and ``status`` attributes as a response, so this is a backwards incompatibility. It is possible to get backwards compatibility back by registering an adapter to IResponse from the type of object you're now returning from view callables. See the section in the Hooks chapter of the documentation entitled "Changing How Pyramid Treats View Responses". - The ``pyramid.interfaces.IResponse`` interface is now much more extensive. Previously it defined only ``app_iter``, ``status`` and ``headerlist``; now it is basically intended to directly mirror the ``webob.Response`` API, which has many methods and attributes. - Documentation changes to support above. --- docs/narr/views.rst | 36 +++++++++++++----------------------- 1 file changed, 13 insertions(+), 23 deletions(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 990828f80..e3d0a37e5 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -230,29 +230,19 @@ implements the :term:`Response` interface is to return a def view(request): return Response('OK') -You don't need to use :class:`~pyramid.response.Response` to represent a -response. A view can actually return any object that has a ``__call__`` -method that implements the :term:`WSGI` application call interface. For -example, an instance of the following class could be successfully returned by -a view callable as a response object: - -.. code-block:: python - :linenos: - - class SimpleResponse(object): - def __call__(self, environ, start_response): - """ Call the ``start_response`` callback and return - an iterable """ - body = 'Hello World!' - headers = [('Content-Type', 'text/plain'), - ('Content-Length', str(len(body)))] - start_response('200 OK', headers) - return [body] - -:app:`Pyramid` provides a range of different "exception" classes which can -act as response objects too. For example, an instance of the class -:class:`pyramid.httpexceptions.HTTPFound` is also a valid response object -(see :ref:`http_exceptions` and ref:`http_redirect`). +:app:`Pyramid` provides a range of different "exception" classes which +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`. + +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`. .. index:: single: view exceptions -- cgit v1.2.3 From f8f08bac0ea9edcac40fae2b3ad56e6a1ac7f47f Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 20 Jun 2011 00:57:30 -0400 Subject: responsecode -> exception_response --- docs/narr/views.rst | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index e3d0a37e5..cbd8fcfb7 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -300,27 +300,30 @@ An HTTP exception, instead of being raised, can alternately be *returned* return HTTPUnauthorized() A shortcut for creating an HTTP exception is the -:func:`pyramid.httpexceptions.responsecode` function. This function accepts -an HTTP status code and returns the corresponding HTTP exception. For -example, instead of importing and constructing a +:func:`pyramid.httpexceptions.exception_response` function. This function +accepts an HTTP status code and returns the corresponding HTTP exception. +For example, instead of importing and constructing a :class:`~pyramid.httpexceptions.HTTPUnauthorized` response object, you can -use the :func:`~pyramid.httpexceptions.responsecode` function to construct -and return the same object. +use the :func:`~pyramid.httpexceptions.exception_response` function to +construct and return the same object. .. code-block:: python :linenos: - from pyramid.httpexceptions import responsecode + from pyramid.httpexceptions import exception_response def aview(request): - raise responsecode(401) + raise exception_response(401) This is the case because ``401`` is the HTTP status code for "HTTP -Unauthorized". Therefore, ``raise responsecode(401)`` is functionally +Unauthorized". Therefore, ``raise exception_response(401)`` is functionally equivalent to ``raise HTTPUnauthorized()``. Documentation which maps each HTTP response code to its purpose and its associated HTTP exception object is provided within :mod:`pyramid.httpexceptions`. +.. note:: The :func:`~pyramid.httpexceptions.exception_response` function is + new as of Pyramid 1.1. + How Pyramid Uses HTTP Exceptions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From e005c27ae54f12d5f9579451c1c894a534eb7d48 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Sun, 10 Jul 2011 22:06:51 -0500 Subject: Modified docs to reference webob's new website. --- docs/narr/views.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index cbd8fcfb7..ca5aac508 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -483,7 +483,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 -`_. +`_. :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 -- cgit v1.2.3 From 71a5ae65dc74a7d4e07f0c74c911a449576237b5 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 11 Jul 2011 03:52:15 -0400 Subject: move alternate calling convention to chapter bottom; fix reference --- docs/narr/views.rst | 150 ++++++++++++++++++++++++++-------------------------- 1 file changed, 75 insertions(+), 75 deletions(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index cbd8fcfb7..6207ae00a 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -134,80 +134,6 @@ related view callables. 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,7 +160,7 @@ 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`. You can also return objects from view callables that aren't instances of (or instances of classes which are subclasses of) @@ -591,3 +517,77 @@ 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``. + -- cgit v1.2.3 From f98cb5d2acd274df2507f822bdc269860e39a169 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 11 Jul 2011 03:57:25 -0400 Subject: move mention of controllers to end --- docs/narr/views.rst | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 2a0aae0ed..6acb1d28d 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -129,11 +129,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 response single: response @@ -591,3 +586,11 @@ callable code itself. No matter which view calling convention is used, the view code always has access to the context via ``request.context``. +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. + -- cgit v1.2.3 From 6ce1e0cf1a141767ee0aca70786c15dd993347c5 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 20 Jul 2011 06:10:38 -0400 Subject: add more index markers --- docs/narr/views.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 6acb1d28d..1c9529860 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -35,6 +35,9 @@ 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 -------------- @@ -586,6 +589,9 @@ 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 -------------------------------------- -- cgit v1.2.3 From 8cb68208d42899b50025418812bb339f578d553f Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 20 Jul 2011 07:16:14 -0400 Subject: - Reordered chapters in narrative section for better new user friendliness. - Added more indexing markers to sections in documentation. --- docs/narr/views.rst | 68 ++++++++++++++++++++--------------------------------- 1 file changed, 25 insertions(+), 43 deletions(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 1c9529860..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,23 +17,10 @@ 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. - -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. +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. .. index:: single: view callables @@ -42,26 +29,20 @@ 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 @@ -160,13 +141,14 @@ 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`. -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`. +.. note:: + + 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 -- cgit v1.2.3 From 3c1affd62c7674e3cacd494f02db3ea91975149e Mon Sep 17 00:00:00 2001 From: davidjb Date: Wed, 25 Jan 2012 11:43:01 +1000 Subject: Minor change - remove duplicated word --- docs/narr/views.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index a3fd61098..fa34cca61 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -233,7 +233,7 @@ provided within :mod:`pyramid.httpexceptions`. How Pyramid Uses HTTP Exceptions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -HTTP exceptions are meant to be used directly by application application +HTTP exceptions are meant to be used directly by application developers. However, Pyramid itself will raise two HTTP exceptions at various points during normal operations: :exc:`pyramid.httpexceptions.HTTPNotFound` and -- cgit v1.2.3 From 02c12a9e2ff804e825fdb22c28e1d16e14ac6c1f Mon Sep 17 00:00:00 2001 From: Jens Rantil Date: Tue, 7 Feb 2012 16:01:51 +0100 Subject: Minor documentation fix. Correcting a noun; 'a' => 'an', since __call__ starts with a consonant. --- docs/narr/views.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index fa34cca61..dbc702de8 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -30,7 +30,7 @@ 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). +that implement a ``__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` -- cgit v1.2.3 From 56766163ece5d860f3f1ea9d2006b1a3d3d6f937 Mon Sep 17 00:00:00 2001 From: Martijn Pieters Date: Fri, 2 Mar 2012 11:30:55 +0100 Subject: Correct minor grammatical error. --- docs/narr/views.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index dbc702de8..c3bbbd50e 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -178,7 +178,7 @@ HTTP Exceptions All classes documented in the :mod:`pyramid.httpexceptions` module documented as inheriting from the :class:`pryamid.httpexceptions.HTTPException` are -:term:`http exception` objects. An instances of an HTTP exception object may +:term:`http exception` objects. Instances of an HTTP exception object may either be *returned* or *raised* from within view code. In either case (return or raise) the instance will be used as as the view's response. -- cgit v1.2.3 From 9834f2a0d95126001d32c34b4f2bec2b980df55e Mon Sep 17 00:00:00 2001 From: David Gay Date: Mon, 2 Apr 2012 18:49:39 -0400 Subject: addressed #327 --- docs/narr/views.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index c3bbbd50e..59bc16e6b 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -571,6 +571,16 @@ 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: Passing in configuration variables + +.. _passing_in_config_variables: + +Passing Configuration Variables to a View +----------------------------------------- +For information on passing a variable from the configuration .ini files to a +view, see :ref:`deployment_settings`. + .. index:: single: Pylons-style controller dispatch -- cgit v1.2.3 From aa1b1eda9d2e507c2c0d7c12785d6f57bfa17129 Mon Sep 17 00:00:00 2001 From: David Gay Date: Mon, 2 Apr 2012 18:49:39 -0400 Subject: addressed #327 --- docs/narr/views.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index c3bbbd50e..f6ee9a8d5 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -571,6 +571,17 @@ 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: Passing in configuration variables + +.. _passing_in_config_variables: + +Passing Configuration Variables to a View +----------------------------------------- + +For information on passing a variable from the configuration .ini files to a +view, see :ref:`deployment_settings`. + .. index:: single: Pylons-style controller dispatch -- cgit v1.2.3 From 77e06770dc174f4269c50bb5443c4b67bc6d3da2 Mon Sep 17 00:00:00 2001 From: David Gay Date: Mon, 2 Apr 2012 19:18:09 -0400 Subject: removed strange text that showed up --- docs/narr/views.rst | 3 --- 1 file changed, 3 deletions(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 6291f01b4..f6ee9a8d5 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -578,10 +578,7 @@ access to the context via ``request.context``. Passing Configuration Variables to a View ----------------------------------------- -<<<<<<< HEAD -======= ->>>>>>> 9834f2a0d95126001d32c34b4f2bec2b980df55e For information on passing a variable from the configuration .ini files to a view, see :ref:`deployment_settings`. -- cgit v1.2.3 From 75a5885afc250db7f19a4c80d947b2bef5826356 Mon Sep 17 00:00:00 2001 From: Ronan Amicel Date: Thu, 23 Aug 2012 17:02:22 +0300 Subject: Fixed typo in docs/narr/views.rst --- docs/narr/views.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index f6ee9a8d5..9e41464a6 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -177,7 +177,7 @@ HTTP Exceptions ~~~~~~~~~~~~~~~ All classes documented in the :mod:`pyramid.httpexceptions` module documented -as inheriting from the :class:`pryamid.httpexceptions.HTTPException` are +as inheriting from the :class:`pyramid.httpexceptions.HTTPException` are :term:`http exception` objects. Instances of an HTTP exception object may either be *returned* or *raised* from within view code. In either case (return or raise) the instance will be used as as the view's response. -- cgit v1.2.3 From db2a03786ec76f2c6b7eaebb6f1b7c8b844d8c82 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 16 Sep 2012 22:32:26 -0400 Subject: make use_tweens=False the default --- docs/narr/views.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 9e41464a6..07d018127 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -338,6 +338,16 @@ exception views which have a name will be ignored. Exception views can be configured with any view registration mechanism: ``@view_config`` decorator or imperative ``add_view`` styles. +.. note:: + + Pyramid's :term:`exception view` handling logic is implemented as a tween + factory function: :func:`pyramid.tweens.excview_tween_factory`. If + Pyramid exception view handling is desired, and tween factories are + specified via the ``pyramid.tweens`` configuration setting, the + :func:`pyramid.tweens.excview_tween_factory` function must be added to the + ``pyramid.tweens`` configuration setting list explicitly. If it is not + present, Pyramid will not perform exception view handling. + .. index:: single: view http redirect single: http redirect (from a view) -- cgit v1.2.3 From 043ccddb909327106264d10ed5d413760a51770d Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 2 Jan 2013 02:22:52 +0200 Subject: eliminate other repeated words --- docs/narr/views.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 07d018127..4f30bb7fa 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -180,7 +180,7 @@ All classes documented in the :mod:`pyramid.httpexceptions` module documented as inheriting from the :class:`pyramid.httpexceptions.HTTPException` are :term:`http exception` objects. Instances of an HTTP exception object may either be *returned* or *raised* from within view code. In either case -(return or raise) the instance will be used as as the view's response. +(return or raise) the instance will be used as the view's response. For example, the :class:`pyramid.httpexceptions.HTTPUnauthorized` exception can be raised. This will cause a response to be generated with a ``401 -- 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/views.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 4f30bb7fa..860c380f3 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -227,8 +227,8 @@ equivalent to ``raise HTTPUnauthorized()``. Documentation which maps each HTTP response code to its purpose and its associated HTTP exception object is provided within :mod:`pyramid.httpexceptions`. -.. note:: The :func:`~pyramid.httpexceptions.exception_response` function is - new as of Pyramid 1.1. +.. versionadded:: 1.1 + The :func:`~pyramid.httpexceptions.exception_response` function. How Pyramid Uses HTTP Exceptions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 5b966a49227cbb9702d2b085b3658e3c91d9eed7 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 23 Feb 2013 12:17:13 +0200 Subject: simplify sentence and fix its grammar --- docs/narr/views.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 860c380f3..b9330b881 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -176,7 +176,7 @@ exception` objects. HTTP Exceptions ~~~~~~~~~~~~~~~ -All classes documented in the :mod:`pyramid.httpexceptions` module documented +All :mod:`pyramid.httpexceptions` classes which are documented as inheriting from the :class:`pyramid.httpexceptions.HTTPException` are :term:`http exception` objects. Instances of an HTTP exception object may either be *returned* or *raised* from within view code. In either case -- cgit v1.2.3 From 2afc385f203be30638db41673b3a771772184c81 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 23 Feb 2013 12:36:06 +0200 Subject: make easier on the eyes Also fixes grammar, and removes repetition. --- docs/narr/views.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 860c380f3..7acec49e5 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -236,12 +236,11 @@ How Pyramid Uses HTTP Exceptions HTTP exceptions are meant to be used directly by application developers. However, Pyramid itself will raise two HTTP exceptions at various points during normal operations: -:exc:`pyramid.httpexceptions.HTTPNotFound` and -:exc:`pyramid.httpexceptions.HTTPForbidden`. Pyramid will raise the -:exc:`~pyramid.httpexceptions.HTTPNotFound` exception are raised when it -cannot find a view to service a request. Pyramid will raise the -:exc:`~pyramid.httpexceptions.Forbidden` exception or when authorization was -forbidden by a security policy. + +* :exc:`~pyramid.httpexceptions.HTTPNotFound` + gets raised when a view to service a request is not found. +* :exc:`~pyramid.httpexceptions.HTTPForbidden` + gets raised when authorization was forbidden by a security policy. If :exc:`~pyramid.httpexceptions.HTTPNotFound` is raised by Pyramid itself or within view code, the result of the :term:`Not Found View` will be returned -- cgit v1.2.3 From feee096963f9c64681210d1fd11de337a5c9afbc Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 23 Feb 2013 13:01:48 +0200 Subject: add missing word, add a :term: role where it was missing, improve readability --- docs/narr/views.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 8ebdfe219..afc2787ca 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -264,9 +264,9 @@ also be used by application developers to convert arbitrary exceptions to responses. To register a view that should be called whenever a particular exception is -raised from with :app:`Pyramid` view code, use the exception class or one of -its superclasses as the ``context`` of a view configuration which points at a -view callable you'd like to generate a response. +raised from within :app:`Pyramid` view code, use the exception class (or one of +its superclasses) as the :term:`context` of a view configuration which points +at a view callable you'd like to generate a response for. For example, given the following exception class in a module named ``helloworld.exceptions``: -- cgit v1.2.3 From bdbf854c95406c06c5b5e1bf85a89e5c961424f0 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 23 Feb 2013 18:26:32 +0200 Subject: we want 4-space indents --- docs/narr/views.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index afc2787ca..077d27366 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -542,7 +542,7 @@ The following types work as view callables in this style: from pyramid.response import Response def view(context, request): - return Response('OK') + return Response('OK') #. Classes that have an ``__init__`` method that accepts ``context, request`` and a ``__call__`` method which accepts no arguments, e.g.: @@ -553,12 +553,12 @@ The following types work as view callables in this style: from pyramid.response import Response class view(object): - def __init__(self, context, request): - self.context = context - self.request = request + def __init__(self, context, request): + self.context = context + self.request = request - def __call__(self): - return Response('OK') + def __call__(self): + return Response('OK') #. Arbitrary callables that have a ``__call__`` method that accepts ``context, request``, e.g.: @@ -569,8 +569,8 @@ The following types work as view callables in this style: from pyramid.response import Response class View(object): - def __call__(self, context, request): - return Response('OK') + 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 -- cgit v1.2.3 From 255cba2fde47f54ceae6ddf65174a6c02f308a16 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 23 Feb 2013 13:11:20 +0200 Subject: uncapitalize --- docs/narr/views.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 8ebdfe219..cc443eb25 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -353,7 +353,7 @@ Exception views can be configured with any view registration mechanism: .. _http_redirect: -Using a View Callable to Do an HTTP Redirect +Using a View Callable to do an HTTP Redirect -------------------------------------------- You can issue an HTTP redirect by using the -- cgit v1.2.3 From 55d81bb135834ec1c2b89860398d5b864ce90cae Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 23 Feb 2013 18:23:06 +0200 Subject: a touch of consistency --- docs/narr/views.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index cc443eb25..6120fa99f 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -524,7 +524,6 @@ 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`. -- cgit v1.2.3 From 2dfdecd4c7a8255702aa08f2807b4a3341b270f7 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 12 Mar 2013 22:40:08 +0200 Subject: fix whitespace issue... remove tabs --- docs/narr/views.rst | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 077d27366..90f6825c0 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -537,41 +537,41 @@ The following types work as view callables in this style: e.g.: .. code-block:: python - :linenos: + :linenos: - from pyramid.response import Response + from pyramid.response import Response - def view(context, request): - return Response('OK') + 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: + :linenos: - from pyramid.response import Response + from pyramid.response import Response - class view(object): - def __init__(self, context, request): - self.context = context - self.request = request + class view(object): + def __init__(self, context, request): + self.context = context + self.request = request - def __call__(self): - return Response('OK') + def __call__(self): + return Response('OK') #. Arbitrary callables that have a ``__call__`` method that accepts ``context, request``, e.g.: .. code-block:: python - :linenos: + :linenos: - from pyramid.response import Response + from pyramid.response import Response - class View(object): - def __call__(self, context, request): - return Response('OK') - view = View() # this is the view callable + 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 -- cgit v1.2.3 From 50218d2d443c8773af3f2312fd0df095f993d4a9 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 1 Apr 2013 09:44:59 +0200 Subject: fix some cross-references --- docs/narr/views.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 5a7be15b0..b2dd549ce 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -39,7 +39,7 @@ object. A request object represents a :term:`WSGI` environment provided to 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` +A view callable's ultimate responsibility is to create a :app:`Pyramid` :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. -- cgit v1.2.3 From 392a6c7df93b67d6889680133fda0f744970d61f Mon Sep 17 00:00:00 2001 From: Antti Haapala Date: Sun, 17 Nov 2013 00:11:37 +0200 Subject: Removed extra indentation from some examples (:linenos: should be indented with the same indentation as the rest of the code block) --- docs/narr/views.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index b2dd549ce..a746eb043 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -536,7 +536,7 @@ The following types work as view callables in this style: e.g.: .. code-block:: python - :linenos: + :linenos: from pyramid.response import Response -- cgit v1.2.3 From b8ceb465f08956b7ed594ef9d14940f8126eb37e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 9 Oct 2015 23:40:59 -0700 Subject: minor grammar, wrap 79 cols --- docs/narr/views.rst | 296 +++++++++++++++++++++++++--------------------------- 1 file changed, 145 insertions(+), 151 deletions(-) (limited to 'docs/narr/views.rst') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index a746eb043..770d27919 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -4,23 +4,22 @@ 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. They are the "meat" of any interesting web application. +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:: +.. note:: A :app:`Pyramid` :term:`view callable` is often referred to in - conversational shorthand as a :term:`view`. In this documentation, - however, we need to use less ambiguous terminology because there - are significant differences between view *configuration*, the code - that implements a view *callable*, and the process of view - *lookup*. + conversational shorthand as a :term:`view`. In this documentation, however, + we need to use less ambiguous terminology because there are significant + differences between view *configuration*, the code that implements a view + *callable*, and the process of view *lookup*. -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. +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. .. index:: single: view callables @@ -28,21 +27,21 @@ particular URL patterns and other request circumstances. 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 a ``__call__`` method (making the instance callable). +View callables are, at the risk of sounding obvious, callable Python objects. +Specifically, view callables can be functions, classes, or instances that +implement a ``__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 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. +View callables must, at a minimum, accept a single argument named ``request``. +This argument represents a :app:`Pyramid` :term:`Request` 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 :app:`Pyramid` -: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. +: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 @@ -76,17 +75,17 @@ Defining a View Callable as a Class ----------------------------------- A view callable may also be represented by a Python class instead of a -function. When a view callable is a class, the calling semantics are -slightly different than when it is a function or another non-class callable. -When a view callable is a class, the class' ``__init__`` method is called with a +function. When a view callable is a class, the calling semantics are slightly +different than when it is a function or another non-class callable. When a view +callable is a class, the class's ``__init__`` method is called with a ``request`` parameter. As a result, an instance of the class is created. Subsequently, that instance's ``__call__`` method is invoked with no -parameters. Views defined as classes must have the following traits: +parameters. Views defined as classes must have the following traits. -- an ``__init__`` method that accepts a ``request`` argument. +- an ``__init__`` method that accepts a ``request`` argument -- a ``__call__`` (or other) method that accepts no parameters and which - returns a response. +- a ``__call__`` (or other) method that accepts no parameters and which returns + a response For example: @@ -106,12 +105,12 @@ The request object passed to ``__init__`` is the same type of request object described in :ref:`function_as_view`. If you'd like to use a different attribute than ``__call__`` to represent the -method expected to return a response, you can use an ``attr`` value as part -of the configuration for the view. See :ref:`view_configuration_parameters`. -The same view callable class can be used in different view configuration -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. +method expected to return a response, you can use an ``attr`` value as part of +the configuration for the view. See :ref:`view_configuration_parameters`. The +same view callable class can be used in different view configuration 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. .. index:: single: view response @@ -135,11 +134,11 @@ implements the :term:`Response` interface is to return a def view(request): return Response('OK') -:app:`Pyramid` provides a range of different "exception" classes which -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`. +:app:`Pyramid` provides a range of different "exception" classes which 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`. .. note:: @@ -155,7 +154,7 @@ examples, see :ref:`http_exceptions` and :ref:`http_redirect`. .. _special_exceptions_in_callables: -Using Special Exceptions In View Callables +Using Special Exceptions in View Callables ------------------------------------------ Usually when a Python exception is raised within a view callable, @@ -176,14 +175,14 @@ exception` objects. HTTP Exceptions ~~~~~~~~~~~~~~~ -All :mod:`pyramid.httpexceptions` classes which are documented -as inheriting from the :class:`pyramid.httpexceptions.HTTPException` are -:term:`http exception` objects. Instances of an HTTP exception object may -either be *returned* or *raised* from within view code. In either case -(return or raise) the instance will be used as the view's response. +All :mod:`pyramid.httpexceptions` classes which are documented as inheriting +from the :class:`pyramid.httpexceptions.HTTPException` are :term:`http +exception` objects. Instances of an HTTP exception object may either be +*returned* or *raised* from within view code. In either case (return or raise) +the instance will be used as the view's response. -For example, the :class:`pyramid.httpexceptions.HTTPUnauthorized` exception -can be raised. This will cause a response to be generated with a ``401 +For example, the :class:`pyramid.httpexceptions.HTTPUnauthorized` exception can +be raised. This will cause a response to be generated with a ``401 Unauthorized`` status: .. code-block:: python @@ -194,8 +193,8 @@ Unauthorized`` status: def aview(request): raise HTTPUnauthorized() -An HTTP exception, instead of being raised, can alternately be *returned* -(HTTP exceptions are also valid response objects): +An HTTP exception, instead of being raised, can alternately be *returned* (HTTP +exceptions are also valid response objects): .. code-block:: python :linenos: @@ -207,11 +206,11 @@ An HTTP exception, instead of being raised, can alternately be *returned* A shortcut for creating an HTTP exception is the :func:`pyramid.httpexceptions.exception_response` function. This function -accepts an HTTP status code and returns the corresponding HTTP exception. -For example, instead of importing and constructing a -:class:`~pyramid.httpexceptions.HTTPUnauthorized` response object, you can -use the :func:`~pyramid.httpexceptions.exception_response` function to -construct and return the same object. +accepts an HTTP status code and returns the corresponding HTTP exception. For +example, instead of importing and constructing a +:class:`~pyramid.httpexceptions.HTTPUnauthorized` response object, you can use +the :func:`~pyramid.httpexceptions.exception_response` function to construct +and return the same object. .. code-block:: python :linenos: @@ -223,8 +222,8 @@ construct and return the same object. This is the case because ``401`` is the HTTP status code for "HTTP Unauthorized". Therefore, ``raise exception_response(401)`` is functionally -equivalent to ``raise HTTPUnauthorized()``. Documentation which maps each -HTTP response code to its purpose and its associated HTTP exception object is +equivalent to ``raise HTTPUnauthorized()``. Documentation which maps each HTTP +response code to its purpose and its associated HTTP exception object is provided within :mod:`pyramid.httpexceptions`. .. versionadded:: 1.1 @@ -233,22 +232,22 @@ provided within :mod:`pyramid.httpexceptions`. How Pyramid Uses HTTP Exceptions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -HTTP exceptions are meant to be used directly by application -developers. However, Pyramid itself will raise two HTTP exceptions at -various points during normal operations: +HTTP exceptions are meant to be used directly by application developers. +However, Pyramid itself will raise two HTTP exceptions at various points during +normal operations. -* :exc:`~pyramid.httpexceptions.HTTPNotFound` - gets raised when a view to service a request is not found. -* :exc:`~pyramid.httpexceptions.HTTPForbidden` - gets raised when authorization was forbidden by a security policy. +* :exc:`~pyramid.httpexceptions.HTTPNotFound` gets raised when a view to + service a request is not found. +* :exc:`~pyramid.httpexceptions.HTTPForbidden` gets raised when authorization + was forbidden by a security policy. If :exc:`~pyramid.httpexceptions.HTTPNotFound` is raised by Pyramid itself or -within view code, the result of the :term:`Not Found View` will be returned -to the user agent which performed the request. +within view code, the result of the :term:`Not Found View` will be returned to +the user agent which performed the request. If :exc:`~pyramid.httpexceptions.HTTPForbidden` is raised by Pyramid itself -within view code, the result of the :term:`Forbidden View` will be returned -to the user agent which performed the request. +within view code, the result of the :term:`Forbidden View` will be returned to +the user agent which performed the request. .. index:: single: exception views @@ -266,7 +265,7 @@ responses. To register a view that should be called whenever a particular exception is raised from within :app:`Pyramid` view code, use the exception class (or one of its superclasses) as the :term:`context` of a view configuration which points -at a view callable you'd like to generate a response for. +at a view callable for which you'd like to generate a response. For example, given the following exception class in a module named ``helloworld.exceptions``: @@ -300,8 +299,8 @@ view callable will be invoked whenever a view code. The same exception raised by a custom root factory, a custom traverser, or a custom view or route predicate is also caught and hooked. -Other normal view predicates can also be used in combination with an -exception view registration: +Other normal view predicates can also be used in combination with an exception +view registration: .. code-block:: python :linenos: @@ -315,24 +314,24 @@ exception view registration: response.status_int = 500 return response -The above exception view names the ``route_name`` of ``home``, meaning that -it will only be called when the route matched has a name of ``home``. You -can therefore have more than one exception view for any given exception in -the system: the "most specific" one will be called when the set of request +The above exception view names the ``route_name`` of ``home``, meaning that it +will only be called when the route matched has a name of ``home``. You can +therefore have more than one exception view for any given exception in the +system: the "most specific" one will be called when the set of request circumstances match the view registration. -The only view predicate that cannot be used successfully when creating -an exception view configuration is ``name``. The name used to look up -an exception view is always the empty string. Views registered as -exception views which have a name will be ignored. +The only view predicate that cannot be used successfully when creating an +exception view configuration is ``name``. The name used to look up an +exception view is always the empty string. Views registered as exception views +which have a name will be ignored. .. note:: - Normal (i.e., non-exception) views registered against a context resource - type which inherits from :exc:`Exception` will work normally. When an - exception view configuration is processed, *two* views are registered. One - as a "normal" view, the other as an "exception" view. This means that you - can use an exception as ``context`` for a normal view. + Normal (i.e., non-exception) views registered against a context resource type + which inherits from :exc:`Exception` will work normally. When an exception + view configuration is processed, *two* views are registered. One as a + "normal" view, the other as an "exception" view. This means that you can use + an exception as ``context`` for a normal view. Exception views can be configured with any view registration mechanism: ``@view_config`` decorator or imperative ``add_view`` styles. @@ -340,9 +339,9 @@ Exception views can be configured with any view registration mechanism: .. note:: Pyramid's :term:`exception view` handling logic is implemented as a tween - factory function: :func:`pyramid.tweens.excview_tween_factory`. If - Pyramid exception view handling is desired, and tween factories are - specified via the ``pyramid.tweens`` configuration setting, the + factory function: :func:`pyramid.tweens.excview_tween_factory`. If Pyramid + exception view handling is desired, and tween factories are specified via + the ``pyramid.tweens`` configuration setting, the :func:`pyramid.tweens.excview_tween_factory` function must be added to the ``pyramid.tweens`` configuration setting list explicitly. If it is not present, Pyramid will not perform exception view handling. @@ -358,11 +357,9 @@ Using a View Callable to do an HTTP Redirect You can issue an HTTP redirect by using the :class:`pyramid.httpexceptions.HTTPFound` class. Raising or returning an -instance of this class will cause the client to receive a "302 Found" -response. +instance of this class will cause the client to receive a "302 Found" response. -To do so, you can *return* a :class:`pyramid.httpexceptions.HTTPFound` -instance. +To do so, you can *return* a :class:`pyramid.httpexceptions.HTTPFound` instance. .. code-block:: python :linenos: @@ -400,32 +397,31 @@ submission data using the :term:`WebOb` API, see :ref:`webob_chapter` and `"Query and POST variables" within the WebOb documentation `_. :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 -understanding how to process form submission data. - -There are some defaults that you need to be aware of when trying to handle -form submission data in a :app:`Pyramid` view. Having high-order (i.e., -non-ASCII) characters in data contained within form submissions is -exceedingly common, and the UTF-8 encoding is the most common encoding used -on the web for character data. Since Unicode values are much saner than -working with and storing bytestrings, :app:`Pyramid` configures the -:term:`WebOb` request machinery to attempt to decode form submission values -into Unicode from UTF-8 implicitly. This implicit decoding happens when view -code obtains form field values via the ``request.params``, ``request.GET``, -or ``request.POST`` APIs (see :ref:`request_module` for details about these -APIs). +and handling form submission data is a property of the request implementation. +Understanding WebOb's request API is the key to understanding how to process +form submission data. + +There are some defaults that you need to be aware of when trying to handle form +submission data in a :app:`Pyramid` view. Having high-order (i.e., non-ASCII) +characters in data contained within form submissions is exceedingly common, and +the UTF-8 encoding is the most common encoding used on the web for character +data. Since Unicode values are much saner than working with and storing +bytestrings, :app:`Pyramid` configures the :term:`WebOb` request machinery to +attempt to decode form submission values into Unicode from UTF-8 implicitly. +This implicit decoding happens when view code obtains form field values via the +``request.params``, ``request.GET``, or ``request.POST`` APIs (see +:ref:`request_module` for details about these APIs). .. note:: - Many people find the difference between Unicode and UTF-8 confusing. - Unicode is a standard for representing text that supports most of the - world's writing systems. However, there are many ways that Unicode data - can be encoded into bytes for transit and storage. UTF-8 is a specific - encoding for Unicode, that is backwards-compatible with ASCII. This makes - UTF-8 very convenient for encoding data where a large subset of that data - is ASCII characters, which is largely true on the web. UTF-8 is also the - standard character encoding for URLs. + Many people find the difference between Unicode and UTF-8 confusing. Unicode + is a standard for representing text that supports most of the world's + writing systems. However, there are many ways that Unicode data can be + encoded into bytes for transit and storage. UTF-8 is a specific encoding for + Unicode that is backwards-compatible with ASCII. This makes UTF-8 very + convenient for encoding data where a large subset of that data is ASCII + characters, which is largely true on the web. UTF-8 is also the standard + character encoding for URLs. As an example, let's assume that the following form page is served up to a browser client, and its ``action`` points at some :app:`Pyramid` view code: @@ -450,8 +446,8 @@ browser client, and its ``action`` points at some :app:`Pyramid` view code: The ``myview`` view code in the :app:`Pyramid` application *must* expect that the values returned by ``request.params`` will be of type ``unicode``, as -opposed to type ``str``. The following will work to accept a form post from -the above form: +opposed to type ``str``. The following will work to accept a form post from the +above form: .. code-block:: python :linenos: @@ -479,31 +475,31 @@ encoding of UTF-8. This can be done via a response that has a with a ``meta http-equiv`` tag that implies that the charset is UTF-8 within the HTML ``head`` of the page containing the form. This must be done explicitly because all known browser clients assume that they should encode -form data in the same character set implied by ``Content-Type`` value of the -response containing the form when subsequently submitting that form. There is -no other generally accepted way to tell browser clients which charset to use -to encode form data. If you do not specify an encoding explicitly, the -browser client will choose to encode form data in its default character set -before submitting it, which may not be UTF-8 as the server expects. If a -request containing form data encoded in a non-UTF8 charset is handled by your -view code, eventually the request code accessed within your view will throw -an error when it can't decode some high-order character encoded in another -character set within form data, e.g., when ``request.params['somename']`` is -accessed. +form data in the same character set implied by the ``Content-Type`` value of +the response containing the form when subsequently submitting that form. There +is no other generally accepted way to tell browser clients which charset to use +to encode form data. If you do not specify an encoding explicitly, the browser +client will choose to encode form data in its default character set before +submitting it, which may not be UTF-8 as the server expects. If a request +containing form data encoded in a non-UTF-8 ``charset`` is handled by your view +code, eventually the request code accessed within your view will throw an error +when it can't decode some high-order character encoded in another character set +within form data, e.g., when ``request.params['somename']`` is accessed. If you are using the :class:`~pyramid.response.Response` class to generate a response, or if you use the ``render_template_*`` templating APIs, the UTF-8 -charset is set automatically as the default via the ``Content-Type`` header. -If you return a ``Content-Type`` header without an explicit charset, a -request will add a ``;charset=utf-8`` trailer to the ``Content-Type`` header -value for you, for response content types that are textual -(e.g. ``text/html``, ``application/xml``, etc) as it is rendered. If you are -using your own response object, you will need to ensure you do this yourself. +``charset`` is set automatically as the default via the ``Content-Type`` +header. If you return a ``Content-Type`` header without an explicit +``charset``, a request will add a ``;charset=utf-8`` trailer to the +``Content-Type`` header value for you for response content types that are +textual (e.g., ``text/html`` or ``application/xml``) as it is rendered. If you +are using your own response object, you will need to ensure you do this +yourself. -.. note:: Only the *values* of request params obtained via - ``request.params``, ``request.GET`` or ``request.POST`` are decoded - to Unicode objects implicitly in the :app:`Pyramid` default - configuration. The keys are still (byte) strings. +.. note:: Only the *values* of request params obtained via ``request.params``, + ``request.GET`` or ``request.POST`` are decoded to Unicode objects + implicitly in the :app:`Pyramid` default configuration. The keys are still + (byte) strings. .. index:: @@ -514,7 +510,7 @@ using your own response object, you will need to ensure you do this yourself. Alternate View Callable Argument/Calling Conventions ---------------------------------------------------- -Usually, view callables are defined to accept only a single argument: +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 @@ -532,8 +528,7 @@ request The following types work as view callables in this style: -#. Functions that accept two arguments: ``context``, and ``request``, - e.g.: +#. Functions that accept two arguments: ``context`` and ``request``, e.g.: .. code-block:: python :linenos: @@ -543,8 +538,8 @@ The following types work as view callables in this style: 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.: +#. Classes that have an ``__init__`` method that accepts ``context, request``, + and a ``__call__`` method which accepts no arguments, e.g.: .. code-block:: python :linenos: @@ -559,8 +554,8 @@ The following types work as view callables in this style: def __call__(self): return Response('OK') -#. Arbitrary callables that have a ``__call__`` method that accepts - ``context, request``, e.g.: +#. Arbitrary callables that have a ``__call__`` method that accepts ``context, + request``, e.g.: .. code-block:: python :linenos: @@ -597,7 +592,6 @@ 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. - +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. -- cgit v1.2.3