- 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").

10 files changed, 193 insertions, 207 deletions

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
 ~~~~~~~~~