diff options
Diffstat (limited to 'docs/narr/views.rst')
| -rw-r--r-- | docs/narr/views.rst | 515 |
1 files changed, 260 insertions, 255 deletions
diff --git a/docs/narr/views.rst b/docs/narr/views.rst index a746eb043..a53063f78 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 @@ -53,18 +52,18 @@ special kinds of exceptions from within the body of a view callable. Defining a View Callable as a Function -------------------------------------- -One of the easiest way to define a view callable is to create a function that +One of the easiest ways to define a view callable is to create a function that accepts a single argument named ``request``, and which returns a :term:`Response` object. For example, this is a "hello world" view callable implemented as a function: .. code-block:: python - :linenos: + :linenos: - from pyramid.response import Response + from pyramid.response import Response - def hello_world(request): - return Response('Hello world!') + def hello_world(request): + return Response('Hello world!') .. index:: single: view calling convention @@ -76,42 +75,42 @@ 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: .. code-block:: python - :linenos: + :linenos: - from pyramid.response import Response + from pyramid.response import Response - class MyView(object): - def __init__(self, request): - self.request = request + class MyView(object): + def __init__(self, request): + self.request = request - def __call__(self): - return Response('hello') + def __call__(self): + return Response('hello') 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 @@ -128,18 +127,18 @@ implements the :term:`Response` interface is to return a :class:`pyramid.response.Response` object instance directly. For example: .. code-block:: python - :linenos: + :linenos: - from pyramid.response import Response + from pyramid.response import Response - def view(request): - return Response('OK') + 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,55 +175,55 @@ 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 - :linenos: + :linenos: - from pyramid.httpexceptions import HTTPUnauthorized + from pyramid.httpexceptions import HTTPUnauthorized - def aview(request): - raise HTTPUnauthorized() + 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: + :linenos: - from pyramid.httpexceptions import HTTPUnauthorized + from pyramid.httpexceptions import HTTPUnauthorized - def aview(request): - return HTTPUnauthorized() + def aview(request): + return HTTPUnauthorized() 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: + :linenos: - from pyramid.httpexceptions import exception_response + from pyramid.httpexceptions import exception_response - def aview(request): - raise exception_response(401) + def aview(request): + raise exception_response(401) 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. +or 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 @@ -263,36 +262,41 @@ 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 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. +To register an :term:`exception view` that should be called whenever a +particular exception is raised from within :app:`Pyramid` view code, use +:meth:`pyramid.config.Configurator.add_exception_view` to register a view +configuration which matches the exception (or a subclass of the exception) and +points at a view callable for which you'd like to generate a response. The +exception will be passed as the ``context`` argument to any +:term:`view predicate` registered with the view, as well as to the view itself. +For convenience a new decorator exists, +:class:`pyramid.views.exception_view_config`, which may be used to easily +register exception views. For example, given the following exception class in a module named ``helloworld.exceptions``: .. code-block:: python - :linenos: - - class ValidationFailure(Exception): - def __init__(self, msg): - self.msg = msg + :linenos: + class ValidationFailure(Exception): + def __init__(self, msg): + self.msg = msg You can wire a view callable to be called whenever any of your *other* code raises a ``helloworld.exceptions.ValidationFailure`` exception: .. code-block:: python - :linenos: + :linenos: - from pyramid.view import view_config - from helloworld.exceptions import ValidationFailure + from pyramid.view import exception_view_config + from helloworld.exceptions import ValidationFailure - @view_config(context=ValidationFailure) - def failed_validation(exc, request): - response = Response('Failed validation: %s' % exc.msg) - response.status_int = 500 - return response + @exception_view_config(ValidationFailure) + def failed_validation(exc, request): + response = Response('Failed validation: %s' % exc.msg) + response.status_int = 500 + return response Assuming that a :term:`scan` was run to pick up this view registration, this view callable will be invoked whenever a @@ -300,49 +304,56 @@ 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: + :linenos: - from pyramid.view import view_config - from helloworld.exceptions import ValidationFailure + from pyramid.view import view_config + from helloworld.exceptions import ValidationFailure - @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 + @exception_view_config(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 -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. + In most cases, you should register an :term:`exception view` by using + :meth:`pyramid.config.Configurator.add_exception_view`. However, it is + possible to register "normal" (i.e., non-exception) views against a context + resource type which inherits from :exc:`Exception` (i.e., + ``config.add_view(context=Exception)``). When the view configuration is + processed, *two* views are registered. One as a "normal" view, the other + as an :term:`exception view`. This means that you can use an exception as + ``context`` for a normal view. + + The view derivers that wrap these two views may behave differently. + See :ref:`exception_view_derivers` for more information about this. Exception views can be configured with any view registration mechanism: -``@view_config`` decorator or imperative ``add_view`` styles. +``@exception_view_config`` decorator or imperative ``add_exception_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 + 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,29 +369,27 @@ 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: + :linenos: - from pyramid.httpexceptions import HTTPFound + from pyramid.httpexceptions import HTTPFound - def myview(request): - return HTTPFound(location='http://example.com') + def myview(request): + return HTTPFound(location='http://example.com') Alternately, you can *raise* an HTTPFound exception instead of returning one. .. code-block:: python - :linenos: + :linenos: - from pyramid.httpexceptions import HTTPFound + from pyramid.httpexceptions import HTTPFound - def myview(request): - raise HTTPFound(location='http://example.com') + def myview(request): + raise HTTPFound(location='http://example.com') When the instance is raised, it is caught by the default :term:`exception response` handler and turned into a response. @@ -398,79 +407,78 @@ various other clients. In :app:`Pyramid`, form submission handling logic is always part of a :term:`view`. For a general overview of how to handle form submission data using the :term:`WebOb` API, see :ref:`webob_chapter` and `"Query and POST variables" within the WebOb documentation -<http://docs.webob.org/en/latest/reference.html#query-post-variables>`_. +<https://docs.pylonsproject.org/projects/webob/en/latest/reference.html#query-post-variables>`_. :app:`Pyramid` defers to WebOb for its request and response implementations, -and handling form submission data is a property of the request -implementation. Understanding WebOb's request API is the key to -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: .. code-block:: xml - :linenos: - - <html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> - </head> - <form method="POST" action="myview"> - <div> - <input type="text" name="firstname"/> - </div> - <div> - <input type="text" name="lastname"/> - </div> - <input type="submit" value="Submit"/> - </form> - </html> + :linenos: + + <html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> + </head> + <form method="POST" action="myview"> + <div> + <input type="text" name="firstname"/> + </div> + <div> + <input type="text" name="lastname"/> + </div> + <input type="submit" value="Submit"/> + </form> + </html> 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: + :linenos: - def myview(request): - firstname = request.params['firstname'] - lastname = request.params['lastname'] + def myview(request): + firstname = request.params['firstname'] + lastname = request.params['lastname'] But the following ``myview`` view code *may not* work, as it tries to decode already-decoded (``unicode``) values obtained from ``request.params``: .. code-block:: python - :linenos: + :linenos: - def myview(request): - # the .decode('utf-8') will break below if there are any high-order - # characters in the firstname or lastname - firstname = request.params['firstname'].decode('utf-8') - lastname = request.params['lastname'].decode('utf-8') + def myview(request): + # the .decode('utf-8') will break below if there are any high-order + # characters in the firstname or lastname + firstname = request.params['firstname'].decode('utf-8') + lastname = request.params['lastname'].decode('utf-8') For implicit decoding to work reliably, you should ensure that every form you render that posts to a :app:`Pyramid` view explicitly defines a charset @@ -479,31 +487,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,9 +522,8 @@ 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: -``request``. However, view callables may alternately be defined as classes, -functions, or any callable that accept *two* positional arguments: a +Usually view callables are defined to accept only a single argument: +``request``. However, a view callable may alternately be defined as any class, function, or callable that accepts *two* positional arguments: a :term:`context` resource as the first argument and a :term:`request` as the second argument. @@ -532,8 +539,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,34 +549,34 @@ 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: + :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.: +#. 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 @@ -597,7 +603,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. |