diff options
| -rw-r--r-- | CHANGES.txt | 9 | ||||
| -rw-r--r-- | TODO.txt | 4 | ||||
| -rw-r--r-- | docs/api.rst | 1 | ||||
| -rw-r--r-- | docs/api/response.rst | 10 | ||||
| -rw-r--r-- | docs/narr/configuration.rst | 10 | ||||
| -rw-r--r-- | docs/narr/firstapp.rst | 52 | ||||
| -rw-r--r-- | docs/narr/hooks.rst | 2 | ||||
| -rw-r--r-- | docs/narr/sessions.rst | 2 | ||||
| -rw-r--r-- | docs/narr/templates.rst | 17 | ||||
| -rw-r--r-- | docs/narr/urldispatch.rst | 2 | ||||
| -rw-r--r-- | docs/narr/views.rst | 238 | ||||
| -rw-r--r-- | docs/narr/webob.rst | 66 | ||||
| -rw-r--r-- | pyramid/interfaces.py | 10 | ||||
| -rw-r--r-- | pyramid/renderers.py | 3 | ||||
| -rw-r--r-- | pyramid/response.py | 2 | ||||
| -rw-r--r-- | pyramid/testing.py | 3 | ||||
| -rw-r--r-- | pyramid/view.py | 11 |
17 files changed, 216 insertions, 226 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index 9e52aaab5..29f8e4897 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -72,6 +72,10 @@ Features (delta from BFG 1.3.X) keys added to the renderer globals dictionary by all subscribers and app-level globals factories must be unique. +- New class: ``pyramid.response.Response`. This is a pure facade for + ``webob.Response` (old code need not change to use this facade, it's + existence is mostly for vanity and documentation-generation purposes). + Documentation (delta from BFG 1.3) ----------------------------------- @@ -83,6 +87,11 @@ Documentation (delta from BFG 1.3) - Added an API chapter for the ``pyramid.personality`` module. +- Added an API chapter for the ``pyramid.response`` module. + +- All documentation which previously referred to ``webob.Response`` now uses + ``pyramid.response.Response`` instead. + Backwards Incompatibilities (with BFG 1.3.X) -------------------------------------------- @@ -84,10 +84,6 @@ - Test on GAE, Jython, PyPy, IronPython. -- Remove references to 'WebOb' Response and just call it 'Response', and note - that it is imported from pyramid. API docs can mention its inheritance from - webob (aka "Provide a webob.Response class facade for forward compat"). - - Add docs for httpexceptions. - RendererHelper -> RendererInfo? diff --git a/docs/api.rst b/docs/api.rst index e457d28f0..805accd50 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -23,6 +23,7 @@ documentation is organized alphabetically by module name. api/personality api/renderers api/request + api/response api/router api/scripting api/security diff --git a/docs/api/response.rst b/docs/api/response.rst new file mode 100644 index 000000000..c545b4977 --- /dev/null +++ b/docs/api/response.rst @@ -0,0 +1,10 @@ +.. _response_module: + +:mod:`pyramid.response` +--------------------------- + +.. module:: pyramid.response + +.. autoclass:: Response + :members: + :inherited-members: diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index a62cf76ff..cbc49d94b 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -52,9 +52,9 @@ imperatively: .. code-block:: python :linenos: - from webob import Response from paste.httpserver import serve from pyramid.configuration import Configurator + from pyramid.response import Response def hello_world(request): return Response('Hello world!') @@ -98,8 +98,8 @@ In a file named ``helloworld.py``: .. code-block:: python :linenos: - from webob import Response from paste.httpserver import serve + from pyramid.response import Response from pyramid.configuration import Configurator def hello_world(request): @@ -277,8 +277,8 @@ referred to by the declaration itself. For example: .. code-block:: python :linenos: + from pyramid.response import Response from pyramid.view import view_config - from webob import Response @view_config(name='hello', request_method='GET') def hello(request): @@ -306,8 +306,8 @@ and its subpackages. For example: :linenos: from paste.httpserver import serve + from pyramid.response import Response from pyramid.view import view_config - from webob import Response @view_config() def hello(request): @@ -334,8 +334,8 @@ directive, the package the ZCML file points to is scanned. # helloworld.py from paste.httpserver import serve + from pyramid.response import Response from pyramid.view import view_config - from webob import Response @view_config() def hello(request): diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 16410d07f..71219689d 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -26,9 +26,9 @@ configured imperatively: .. code-block:: python :linenos: - from webob import Response - from paste.httpserver import serve from pyramid.configuration import Configurator + from pyramid.response import Response + from paste.httpserver import serve def hello_world(request): return Response('Hello world!') @@ -64,26 +64,23 @@ The above script defines the following set of imports: .. code-block:: python :linenos: - from webob import Response - from paste.httpserver import serve from pyramid.configuration import Configurator + from pyramid.response import Response + from paste.httpserver import serve -:mod:`pyramid` uses the :term:`WebOb` library as the basis for its -:term:`request` and :term:`response` objects. The script uses the -:class:`webob.Response` class later in the script to create a -:term:`response` object. +The script imports the ``Configurator`` class from the +``pyramid.configuration`` module. This class is used to configure +:mod:`pyramid` for a particular application. An instance of this class +provides methods which help configure various parts of :mod:`pyramid` for a +given application deployment. -Like many other Python web frameworks, :mod:`pyramid` uses the -:term:`WSGI` protocol to connect an application and a web server -together. The :mod:`paste.httpserver` server is used in this example -as a WSGI server for convenience, as the ``paste`` package is a -dependency of :mod:`pyramid` itself. +The script uses the :class:`pyramid.response.Response` class later in the +script to create a :term:`response` object. -The script also imports the ``Configurator`` class from the -``pyramid.configuration`` module. This class is used to configure -:mod:`pyramid` for a particular application. An instance of this -class provides methods which help configure various parts of -:mod:`pyramid` for a given application deployment. +Like many other Python web frameworks, :mod:`pyramid` uses the :term:`WSGI` +protocol to connect an application and a web server together. The +:mod:`paste.httpserver` server is used in this example as a WSGI server for +convenience, as the ``paste`` package is a dependency of :mod:`pyramid` itself. View Callable Declarations ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -117,14 +114,13 @@ A view callable is always called with a :term:`request` object. A request object is a representation of an HTTP request sent to :mod:`pyramid` via the active :term:`WSGI` server. -A view callable is required to return a :term:`response` object -because a response object has all the information necessary to -formulate an actual HTTP response; this object is then converted to -text by the upstream :term:`WSGI` server and sent back to the -requesting browser. To return a response, each view callable creates -an instance of the :class:`webob.Response` class. In the -``hello_world`` function, the string ``'Hello world!'`` is passed to -the ``Response`` constructor as the *body* of the response. In the +A view callable is required to return a :term:`response` object because a +response object has all the information necessary to formulate an actual HTTP +response; this object is then converted to text by the upstream :term:`WSGI` +server and sent back to the requesting browser. To return a response, each +view callable creates an instance of the :class:`pyramid.response.Response` +class. In the ``hello_world`` function, the string ``'Hello world!'`` is +passed to the ``Response`` constructor as the *body* of the response. In the ``goodbye_world`` function, the string ``'Goodbye world!'`` is passed. .. index:: @@ -385,9 +381,9 @@ To do so, first, create a file named ``helloworld.py``: .. code-block:: python :linenos: - from webob import Response - from paste.httpserver import serve from pyramid.configuration import Configurator + from pyramid.response import Response + from paste.httpserver import serve def hello_world(request): return Response('Hello world!') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 130dd8acd..701cab17c 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -72,7 +72,7 @@ callable: .. code-block:: python :linenos: - from webob.exc import HTTPNotFound + from pyramid.httpexceptions import HTTPNotFound def notfound_view(request): return HTTPNotFound() diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index df164e684..f27669738 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -70,7 +70,7 @@ example: .. code-block:: python :linenos: - from webob import Response + from pyramid.response import Response def myview(request): session = request.session diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 736e6a185..efe631f3a 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -130,7 +130,7 @@ the body of the response: :linenos: from pyramid.renderers import render - from webob import Response + from pyramid.response import Response def sample_view(request): result = render('mypackage:templates/foo.pt', @@ -140,12 +140,11 @@ the body of the response: return response Because :term:`view callable` functions are typically the only code in -:mod:`pyramid` that need to know anything about templates, and -because view functions are very simple Python, you can use whatever -templating system you're most comfortable with within -:mod:`pyramid`. Install the templating system, import its API -functions into your views module, use those APIs to generate a string, -then return that string as the body of a :term:`WebOb` +:mod:`pyramid` that need to know anything about templates, and because view +functions are very simple Python, you can use whatever templating system you're +most comfortable with within :mod:`pyramid`. Install the templating system, +import its API functions into your views module, use those APIs to generate a +string, then return that string as the body of a :mod:`pyramid` :term:`Response` object. For example, here's an example of using raw `Mako @@ -157,7 +156,7 @@ For example, here's an example of using raw `Mako :linenos: from mako.template import Template - from webob import Response + from pyramid.response import Response def make_view(request): template = Template(filename='/templates/template.mak') @@ -215,7 +214,7 @@ of :func:`pyramid.renderers.render` (a string): :linenos: from pyramid.renderers import render - from webob import Response + from pyramid.response import Response def sample_view(request): result = render('mypackage:templates/foo.pt', {'foo':1, 'bar':2}, diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 6e7c82f56..f5fa87fce 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -871,7 +871,7 @@ The ``mypackage.views`` module referred to above might look like so: .. code-block:: python :linenos: - from webob import Response + from pyramid.response import Response def site_view(request): return Response(request.matchdict['id']) diff --git a/docs/narr/views.rst b/docs/narr/views.rst index fb500d914..b81ea9807 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -42,15 +42,16 @@ No matter how a view callable is eventually found, all view callables used by :mod:`pyramid` must be constructed in the same way, and must return the same kind of return value. -Most view callables accept a single argument named ``request``. This -argument represents a :term:`WebOb` :term:`Request` object as -represented to :mod:`pyramid` by the upstream :term:`WSGI` server. +Most view callables accept a single argument named ``request``. This argument +represents a :mod:`pyramid` :term:`Request` object. A request object +encapsulates a WSGI environment as represented to :mod:`pyramid` by the +upstream :term:`WSGI` server. -A view callable may always return a :term:`WebOb` :term:`Response` -object directly. It may optionally return another arbitrary -non-Response value: if a view callable returns a non-Response result, -the result must be converted into a response by the :term:`renderer` -associated with the :term:`view configuration` for the view. +A view callable may always return a :mod:`Pyramid` :term:`Response` object +directly. It may optionally return another arbitrary non-Response value: if a +view callable returns a non-Response result, the result must be converted into +a response by the :term:`renderer` associated with the :term:`view +configuration` for the view. View callables can be functions, instances, or classes. View callables can optionally be defined with an alternate calling @@ -73,7 +74,7 @@ callable implemented as a function: .. code-block:: python :linenos: - from webob import Response + from pyramid.response import Response def hello_world(request): return Response('Hello world!') @@ -109,7 +110,7 @@ For example: .. code-block:: python :linenos: - from webob import Response + from pyramid.response import Response class MyView(object): def __init__(self, request): @@ -149,7 +150,7 @@ context will be a :term:`model` object. request - A :term:`WebOb` Request object representing the current WSGI + A :mod:`pyramid` Request object representing the current WSGI request. The following types work as view callables in this style: @@ -160,7 +161,7 @@ The following types work as view callables in this style: .. code-block:: python :linenos: - from webob import Response + from pyramid.response import Response def view(context, request): return Response('OK') @@ -171,7 +172,7 @@ The following types work as view callables in this style: .. code-block:: python :linenos: - from webob import Response + from pyramid.response import Response class view(object): def __init__(self, context, request): @@ -187,7 +188,7 @@ The following types work as view callables in this style: .. code-block:: python :linenos: - from webob import Response + from pyramid.response import Response class View(object): def __call__(self, context, request): @@ -210,26 +211,25 @@ has access to the context via ``request.context``. View Callable Responses ~~~~~~~~~~~~~~~~~~~~~~~ -A view callable may always return an object that implements the -:term:`WebOb` :term:`Response` interface. The easiest way to return -something that implements the :term:`Response` interface is to return -a :class:`webob.Response` object instance directly. For example: +A view callable may always return an object that implements the :mod:`pyramid` +:term:`Response` interface. The easiest way to return something that +implements the :term:`Response` interface is to return a +:class:`pyramid.response.Response` object instance directly. For example: .. code-block:: python :linenos: - from webob import Response + from pyramid.response import Response def view(request): return Response('OK') -You don't need to always use :class:`webob.Response` to represent a -response. :term:`WebOb` provides a range of different "exception" -classes which can act as response objects too. For example, an -instance of the class :class:`webob.exc.HTTPFound` is also a valid -response object (see :ref:`http_redirect`). A view can actually any -object that has the following attributes (these attributes form the -notional "WebOb Response interface"): +You don't need to always use :class:`pyramid.response.Response` to represent a +response. :mod:`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 any object that has the following +attributes (these attributes form the notional "Pyramid Response interface"): status The HTTP status code (including the name) for the response as a string. @@ -246,38 +246,36 @@ app_iter world!</body></html>']`` or it can be a file-like object, or any other sort of iterable. -Furthermore, a view needn't *always* return a Response object. If a -view happens to return something which does not implement the WebOb -Response interface, :mod:`pyramid` will attempt to use a -:term:`renderer` to construct a response. For example: +Furthermore, a view needn't *always* return a Response object. If a view +happens to return something which does not implement the Pyramid Response +interface, :mod:`pyramid` will attempt to use a :term:`renderer` to construct a +response. For example: .. code-block:: python :linenos: - from webob import Response + from pyramid.response import Response from pyramid.view import view_config @view_config(renderer='json') def hello_world(request): return {'content':'Hello!'} -The above example returns a *dictionary* from the view callable. A -dictionary does not implement the :term:`WebOb` response interface, so -you might believe that this example would fail. However, since a -``renderer`` is associated with the view callable through its -:term:`view configuration` (in this case, using a ``renderer`` -argument passed to :func:`pyramid.view.view_config`), if the view does -*not* return a Response object, the renderer will attempt to convert -the result of the view to a response on the developer's behalf. Of -course, if no renderer is associated with a view's configuration, -returning anything except an object which implements the WebOb -Response interface will result in an error. And, if a renderer *is* -used, whatever is returned by the view must be compatible with the -particular kind of renderer used, or an error may occur during view -invocation. One exception exists: it is *always* OK to return a WebOb -Response object, even when a ``renderer`` is configured. If a view -callable returns a response object from a view that is configured with -a renderer, the renderer is bypassed entirely. +The above example returns a *dictionary* from the view callable. A dictionary +does not implement the Pyramid response interface, so you might believe that +this example would fail. However, since a ``renderer`` is associated with the +view callable through its :term:`view configuration` (in this case, using a +``renderer`` argument passed to :func:`pyramid.view.view_config`), if the view +does *not* return a Response object, the renderer will attempt to convert the +result of the view to a response on the developer's behalf. Of course, if no +renderer is associated with a view's configuration, returning anything except +an object which implements the Response interface will result in an error. +And, if a renderer *is* used, whatever is returned by the view must be +compatible with the particular kind of renderer used, or an error may occur +during view invocation. One exception exists: it is *always* OK to return a +Response object, even when a ``renderer`` is configured. If a view callable +returns a response object from a view that is configured with a renderer, the +renderer is bypassed entirely. Various types of renderers exist, including serialization renderers and renderers which use templating systems. See also @@ -303,12 +301,11 @@ particular kind of response. def myview(request): return HTTPFound(location='http://example.com') -All exception types from the :mod:`webob.exc` module implement the -WebOb :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``. +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``. .. index:: single: renderer @@ -319,19 +316,17 @@ that imply other HTTP response codes, such as ``HTTPUnauthorized`` for Writing View Callables Which Use a Renderer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -View callables needn't always return a WebOb Response object. -Instead, they may return an arbitrary Python object, with the -expectation that a :term:`renderer` will convert that object into a -response instance on behalf of the developer. Some renderers use a -templating system; other renderers use object serialization -techniques. +View callables needn't always return a Response object. Instead, they may +return an arbitrary Python object, with the expectation that a :term:`renderer` +will convert that object into a response instance on behalf of the developer. +Some renderers use a templating system; other renderers use object +serialization techniques. -If you do not define a ``renderer`` attribute in :term:`view -configuration` for an associated :term:`view callable`, no renderer is -associated with the view. In such a configuration, an error is raised -when a view callable does not return an object which implements the -WebOb :term:`Response` interface, documented within -:ref:`the_response`. +If you do not define a ``renderer`` attribute in :term:`view configuration` for +an associated :term:`view callable`, no renderer is associated with the view. +In such a configuration, an error is raised when a view callable does not +return an object which implements the :term:`Response` interface, documented +within :ref:`the_response`. View configuration can vary the renderer associated with a view callable via the ``renderer`` attribute. For example, this ZCML @@ -353,18 +348,18 @@ Other built-in renderers include renderers which use the :term:`Chameleon` templating language to render a dictionary to a response. -If the :term:`view callable` associated with a :term:`view -configuration` returns a Response object directly (an object with the -attributes ``status``, ``headerlist`` and ``app_iter``), any renderer -associated with the view configuration is ignored, and the response is -passed back to :mod:`pyramid` unmolested. For example, if your -view callable returns an instance of the :class:`webob.exc.HTTPFound` -class as a response, no renderer will be employed. +If the :term:`view callable` associated with a :term:`view configuration` +returns a Response object directly (an object with the attributes ``status``, +``headerlist`` and ``app_iter``), any renderer associated with the view +configuration is ignored, and the response is passed back to :mod:`pyramid` +unmolested. For example, if your view callable returns an instance of the +:class:`pyramid.httpexceptions.HTTPFound` class as a response, no renderer will +be employed. .. code-block:: python :linenos: - from webob.exc import HTTPFound + from pyramid.httpexceptions import HTTPFound def view(request): return HTTPFound(location='http://example.com') # renderer avoided @@ -410,7 +405,7 @@ representation of the dictionary: .. code-block:: python :linenos: - from webob import Response + from pyramid.response import Response from pyramid.view import view_config @view_config(renderer='string') @@ -449,7 +444,7 @@ view will render the returned dictionary to a JSON serialization: .. code-block:: python :linenos: - from webob import Response + from pyramid.response import Response from pyramid.view import view_config @view_config(renderer='json') @@ -1008,7 +1003,7 @@ exception view registration: from pyramid.view import view_config from pyramid.exceptions import NotFound - from webob.exc import HTTPNotFound + from pyramid.httpexceptions import HTTPNotFound @view_config(context=NotFound, route_name='home') def notfound_view(request): @@ -1058,19 +1053,17 @@ 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 :mod:`pyramid` view. Because -having high-order (non-ASCII) characters in data contained within form -submissions is exceedingly common, and because the UTF-8 encoding is -the most common encoding used on the web for non-ASCII character data, -and because working and storing Unicode values is much saner than -working with and storing bytestrings, :mod:`pyramid` configures the -:term:`WebOb` request machinery to attempt to decode form submission -values into Unicode from the UTF-8 character set implicitly. This -implicit decoding happens when view code obtains form field values via -the :term:`WebOb` ``request.params``, ``request.GET``, or -``request.POST`` APIs (see :ref:`request_module` for details about -these APIs). +There are some defaults that you need to be aware of when trying to handle form +submission data in a :mod:`pyramid` view. Because having high-order +(non-ASCII) characters in data contained within form submissions is exceedingly +common, and because the UTF-8 encoding is the most common encoding used on the +web for non-ASCII character data, and because working and storing Unicode +values is much saner than working with and storing bytestrings, :mod:`pyramid` +configures the :term:`WebOb` request machinery to attempt to decode form +submission values into Unicode from the UTF-8 character set 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). For example, let's assume that the following form page is served up to a browser client, and its ``action`` points at some :mod:`pyramid` @@ -1119,35 +1112,32 @@ decode already-decoded (``unicode``) values obtained from firstname = request.params['firstname'].decode('utf-8') lastname = request.params['lastname'].decode('utf-8') -For implicit decoding to work reliably, youshould ensure that every -form you render that posts to a :mod:`pyramid` view is rendered via -a response that has a ``;charset=UTF-8`` in its ``Content-Type`` -header; or, as in the form above, 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 -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. The browser client may -have a non-UTF-8 default encoding. If such a request is handled by -your view code, when the form submission data is encoded in a non-UTF8 -charset, eventually the WebOb 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 +For implicit decoding to work reliably, youshould ensure that every form you +render that posts to a :mod:`pyramid` view is rendered via a response that has +a ``;charset=UTF-8`` in its ``Content-Type`` header; or, as in the form above, +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 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. The browser client may have a non-UTF-8 default encoding. If +such a request is handled by your view code, when the form submission data is +encoded in a non-UTF8 charset, 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:`webob.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 WebOb request will add a -``;charset=utf-8`` trailer to the ``Content-Type`` header value for +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. +``application/xml``, etc) 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 @@ -1632,7 +1622,7 @@ All arguments to ``view_config`` may be omitted. For example: .. code-block:: python :linenos: - from webob import Response + from pyramid.response import Response from pyramid.view import view_config @view_config() @@ -1692,7 +1682,7 @@ decorator: :linenos: from pyramid.view import view_config - from webob import Response + from pyramid.response import Response @view_config(name='edit') def edit(request): @@ -1707,7 +1697,7 @@ function. For example: .. code-block:: python :linenos: - from webob import Response + from pyramid.response import Response from pyramid.view import view_config @view_config() @@ -1725,7 +1715,7 @@ without the decorator syntactic sugar, if you wish: .. code-block:: python :linenos: - from webob import Response + from pyramid.response import Response from pyramid.view import view_config class MyView(object): @@ -1745,7 +1735,7 @@ separate view registration. For example: :linenos: from pyramid.view import view_config - from webob import Response + from pyramid.response import Response @view_config(name='edit') @view_config(name='change') @@ -1759,7 +1749,7 @@ The decorator can also be used against class methods: .. code-block:: python :linenos: - from webob import Response + from pyramid.response import Response from pyramid.view import view_config class MyView(object): @@ -1788,7 +1778,7 @@ equivalently as the below: .. code-block:: python :linenos: - from webob import Response + from pyramid.response import Response from pyramid.view import view_config @view_config(attr='amethod', name='hello') @@ -1816,7 +1806,7 @@ example: .. code-block:: python :linenos: - from webob import Response + from pyramid.response import Response def hello_world(request): return Response('hello!') diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst index b41979a1f..b496db41e 100644 --- a/docs/narr/webob.rst +++ b/docs/narr/webob.rst @@ -186,9 +186,6 @@ If it is set, then ``req.POST``, ``req.GET``, ``req.params``, and corresponding ``req.str_*`` (like ``req.str_POST``) that is always ``str`` and never unicode. -.. index:: - single: response object - More Details ++++++++++++ @@ -201,13 +198,17 @@ More detail about the request object API is available in: WebOb documentation will work against request objects created by :mod:`pyramid`. +.. index:: + single: response object + Response ~~~~~~~~ -The response object looks a lot like the request object, though with -some differences. The request object wraps a single ``environ`` -object; the response object has three fundamental parts (based on -WSGI): +The :mod:`pyramid` response object can be imported as +:class:`pyramid.response.Response`. This import location is merely a facade +for its original location: ``webob.Response``. + +A response object has three fundamental parts: ``response.status``: The response code plus message, like ``'200 OK'``. To set the @@ -230,12 +231,9 @@ WSGI): Everything else in the object derives from this underlying state. Here's the highlights: -``response.content_type``: +``response.content_type`` The content type *not* including the ``charset`` parameter. - Typical use: ``response.content_type = 'text/html'``. You can - subclass ``Response`` and add a class-level attribute - ``default_content_type`` to set this automatically on - instantiation. + Typical use: ``response.content_type = 'text/html'``. ``response.charset``: The ``charset`` parameter of the content-type, it also informs @@ -243,10 +241,6 @@ Here's the highlights: ``response.content_type_params`` is a dictionary of all the parameters. -``response.request``: - This optional attribute can point to the request object associated - with this response object. - ``response.set_cookie(key, value, max_age=None, path='/', ...)``: Set a cookie. The keyword arguments control the various cookie parameters. The ``max_age`` argument is the length for the cookie @@ -295,31 +289,30 @@ argument to the class; e.g.: .. code-block:: python - from webob import Response - + from pyramid.response import Response response = Response(body='hello world!', content_type='text/plain') -The status defaults to ``'200 OK'``. The content_type does not -default to anything, though if you subclass ``Response`` and set +The status defaults to ``'200 OK'``. The content_type does not default to +anything, though if you subclass :class:`pyramid.response.Response` and set ``default_content_type`` you can override this behavior. .. index:: single: response exceptions -Exceptions -++++++++++ +Exception Responses ++++++++++++++++++++ To facilitate error responses like ``404 Not Found``, the module -:mod:`webob.exc` contains classes for each kind of error response. -These include boring but appropriate error bodies. The exceptions -exposed by this module, when used under :mod:`pyramid`, should be -imported from the :mod:`pyramid.httpexceptions` "facade" module. +:mod:`webob.exc` contains classes for each kind of error response. These +include boring but appropriate error bodies. The exceptions exposed by this +module, when used under :mod:`pyramid`, should be imported from the +:mod:`pyramid.httpexceptions` "facade" module. This import location is merely +a facade for the original location of these exceptions: ``webob.exc``. -Each class is named ``pyramid.httpexceptions.HTTP*``, where ``*`` is -the reason for the error. For instance, -``pyramid.httpexceptions.HTTPNotFound``. It subclasses ``Response``, -so you can manipulate the instances in the same way. A typical -example is: +Each class is named ``pyramid.httpexceptions.HTTP*``, where ``*`` is the reason +for the error. For instance, :class:`pyramid.httpexceptions.HTTPNotFound`. It +subclasses :class:`pyramid.Response`, so you can manipulate the instances in +the same way. A typical example is: .. ignore-next-block .. code-block:: python @@ -359,13 +352,10 @@ objects. More Details ++++++++++++ -More details about the response object API are available in the `WebOb -documentation <http://pythonpaste.org/webob>`_ . All methods and -attributes of a ``webob.Response`` documented within the WebOb -documentation will work against response objects created by -:mod:`pyramid`. :mod:`pyramid` does not use a Webob Response -object subclass to represent a response, it uses WebOb's Response -class directly. +More details about the response object API are available in the +:mod:`pyramid.response` documentation. More details about exception responses +are in the :mod:`pyramid.httpexceptions` API documentation. The `WebOb +documentation <http://pythonpaste.org/webob>`_ is also useful. Multidict ~~~~~~~~~ diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py index 294613c13..5bb6b25fc 100644 --- a/pyramid/interfaces.py +++ b/pyramid/interfaces.py @@ -153,10 +153,10 @@ class IStaticURLInfo(Interface): class IResponseFactory(Interface): """ A utility which generates a response factory """ def __call__(): - """ Return a response factory (e.g. a callable that returns an - object implementing IResponse, e.g. ``webob.Response``; it - should accept all the arguments that the webob.Response class - accepts)""" + """ Return a response factory (e.g. a callable that returns an object + implementing IResponse, e.g. :class:`pyramid.response.Response`). It + should accept all the arguments that the Pyramid Response class + accepts.""" class IRequestFactory(Interface): """ A utility which generates a request """ @@ -166,7 +166,7 @@ class IRequestFactory(Interface): def blank(path): """ Return an empty request object (see - ``webob.Request.blank``)""" + :meth:`pyramid.request.Request.blank``)""" class IViewClassifier(Interface): """ *Internal only* marker interface for views.""" diff --git a/pyramid/renderers.py b/pyramid/renderers.py index 4854041c8..2b6f675df 100644 --- a/pyramid/renderers.py +++ b/pyramid/renderers.py @@ -2,8 +2,6 @@ import os import pkg_resources import threading -from webob import Response - from zope.interface import implements from pyramid.interfaces import IRendererGlobalsFactory @@ -18,6 +16,7 @@ from pyramid.decorator import reify from pyramid.events import BeforeRender from pyramid.path import caller_package from pyramid.path import package_path +from pyramid.response import Response from pyramid.resource import resource_spec_from_abspath from pyramid.threadlocal import get_current_registry diff --git a/pyramid/response.py b/pyramid/response.py new file mode 100644 index 000000000..26f27b142 --- /dev/null +++ b/pyramid/response.py @@ -0,0 +1,2 @@ +from webob import Response +Response = Response # pyflakes diff --git a/pyramid/testing.py b/pyramid/testing.py index 11cb63ad4..b2a5b3b85 100644 --- a/pyramid/testing.py +++ b/pyramid/testing.py @@ -1,7 +1,5 @@ import copy -from webob import Response - from zope.configuration.xmlconfig import _clearContext from zope.interface import implements @@ -15,6 +13,7 @@ from pyramid.interfaces import IViewClassifier from pyramid.configuration import Configurator from pyramid.exceptions import Forbidden +from pyramid.response import Response from pyramid.registry import Registry from pyramid.security import Authenticated from pyramid.security import Everyone diff --git a/pyramid/view.py b/pyramid/view.py index 4b1eb94ed..765bd4458 100644 --- a/pyramid/view.py +++ b/pyramid/view.py @@ -10,8 +10,6 @@ import mimetypes if hasattr(mimetypes, 'init'): mimetypes.init() -from webob.exc import HTTPFound - import venusian from zope.interface import providedBy @@ -20,6 +18,7 @@ from pyramid.interfaces import IRoutesMapper from pyramid.interfaces import IView from pyramid.interfaces import IViewClassifier +from pyramid.httpexceptions import HTTPFound from pyramid.static import static_view as static # B/C from pyramid.threadlocal import get_current_registry @@ -291,7 +290,7 @@ class view_config(object): in Python 2.6 and better (Python 2.5 and below do not support class decorators):: - from webob import Response + from pyramid.response import Response from pyramid.view import view_config @view_config() @@ -305,7 +304,7 @@ class view_config(object): In Python 2.5 and below, the ``view_config`` decorator can still be used against a class, although not in decorator form:: - from webob import Response + from pyramid.response import Response from pyramid.view import view_config class MyView(object): @@ -327,7 +326,7 @@ class view_config(object): The ``view_config`` decorator can also be used against a class method:: - from webob import Response + from pyramid.response import Response from pyramid.view import view_config class MyView(object): @@ -350,7 +349,7 @@ class view_config(object): decorator being used against the ``amethod`` method could be spelled equivalently as:: - from webob import Response + from pyramid.response import Response from pyramid.view import view_config @view_config(attr='amethod', name='hello') |