From 2e6905e15221691e645e5ff4ba0378a6d9438c29 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 25 Oct 2010 23:09:02 -0400 Subject: add httpexceptions docs --- docs/api.rst | 1 + docs/api/httpexceptions.rst | 98 ++++++++++++++++++++++ docs/narr/views.rst | 11 +-- docs/narr/webob.rst | 27 +++--- docs/tutorials/wiki/definingviews.rst | 10 +-- .../wiki/src/authorization/tutorial/login.py | 2 +- .../wiki/src/authorization/tutorial/views.py | 2 +- .../wiki/src/viewdecorators/tutorial/views.py | 2 +- docs/tutorials/wiki/src/views/tutorial/views.py | 2 +- docs/tutorials/wiki2/definingviews.rst | 4 +- .../wiki2/src/authorization/tutorial/login.py | 3 +- .../wiki2/src/authorization/tutorial/views.py | 3 +- docs/tutorials/wiki2/src/views/tutorial/views.py | 3 +- 13 files changed, 134 insertions(+), 34 deletions(-) create mode 100644 docs/api/httpexceptions.rst (limited to 'docs') diff --git a/docs/api.rst b/docs/api.rst index 5bd24d6b2..a4d853942 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -15,6 +15,7 @@ documentation is organized alphabetically by module name. api/configuration api/events api/exceptions + api/httpexceptions api/i18n api/interfaces api/location diff --git a/docs/api/httpexceptions.rst b/docs/api/httpexceptions.rst new file mode 100644 index 000000000..57ca8092c --- /dev/null +++ b/docs/api/httpexceptions.rst @@ -0,0 +1,98 @@ +.. _httpexceptions_module: + +:mod:`pyramid.httpexceptions` +-------------------------------- + +.. automodule:: pyramid.httpexceptions + + .. attribute:: status_map + + A mapping of integer status code to exception class (eg. the + integer "401" maps to + :class:`pyramid.httpexceptions.HTTPUnauthorized`). + + .. autoclass:: HTTPException + + .. autoclass:: HTTPOk + + .. autoclass:: HTTPRedirection + + .. autoclass:: HTTPError + + .. autoclass:: HTTPClientError + + .. autoclass:: HTTPServerError + + .. autoclass:: HTTPCreated + + .. autoclass:: HTTPAccepted + + .. autoclass:: HTTPNonAuthoritativeInformation + + .. autoclass:: HTTPNoContent + + .. autoclass:: HTTPResetContent + + .. autoclass:: HTTPPartialContent + + .. autoclass:: HTTPMultipleChoices + + .. autoclass:: HTTPMovedPermanently + + .. autoclass:: HTTPFound + + .. autoclass:: HTTPSeeOther + + .. autoclass:: HTTPNotModified + + .. autoclass:: HTTPUseProxy + + .. autoclass:: HTTPTemporaryRedirect + + .. autoclass:: HTTPBadRequest + + .. autoclass:: HTTPUnauthorized + + .. autoclass:: HTTPPaymentRequired + + .. autoclass:: HTTPForbidden + + .. autoclass:: HTTPNotFound + + .. autoclass:: HTTPMethodNotAllowed + + .. autoclass:: HTTPNotAcceptable + + .. autoclass:: HTTPProxyAuthenticationRequired + + .. autoclass:: HTTPRequestTimeout + + .. autoclass:: HTTPConflict + + .. autoclass:: HTTPGone + + .. autoclass:: HTTPLengthRequired + + .. autoclass:: HTTPPreconditionFailed + + .. autoclass:: HTTPRequestEntityTooLarge + + .. autoclass:: HTTPRequestURITooLong + + .. autoclass:: HTTPUnsupportedMediaType + + .. autoclass:: HTTPRequestRangeNotSatisfiable + + .. autoclass:: HTTPExpectationFailed + + .. autoclass:: HTTPInternalServerError + + .. autoclass:: HTTPNotImplemented + + .. autoclass:: HTTPBadGateway + + .. autoclass:: HTTPServiceUnavailable + + .. autoclass:: HTTPGatewayTimeout + + .. autoclass:: HTTPVersionNotSupported diff --git a/docs/narr/views.rst b/docs/narr/views.rst index f52df9557..2969487d3 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -298,16 +298,17 @@ particular kind of response. .. code-block:: python :linenos: - from webob.exc import HTTPFound + from pyramid.httpexceptions import HTTPFound 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 :term:`WebOb` for the documentation for this module; -it includes other response types that imply other HTTP response codes, -such as ``401 Unauthorized``. +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``. .. index:: single: renderer diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst index 82416a44d..b3bec882e 100644 --- a/docs/narr/webob.rst +++ b/docs/narr/webob.rst @@ -309,20 +309,23 @@ default to anything, though if you subclass ``Response`` and set Exceptions ++++++++++ -To facilitate error responses like 404 Not Found, the module -``webob.exc`` contains classes for each kind of error response. These -include boring but appropriate error bodies. - -Each class is named ``webob.exc.HTTP*``, where ``*`` is the reason for -the error. For instance, ``webob.exc.HTTPNotFound``. It subclasses -``Response``, so you can manipulate the instances in the same way. A -typical example is: +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. + +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: .. ignore-next-block .. code-block:: python - from webob.exc import HTTPNotFound - from webob.exc import HTTPMovedPermanently + from pyramid.httpexceptions import HTTPNotFound + from pyramid.httpexceptions import HTTPMovedPermanently response = HTTPNotFound('There is no such resource') # or: @@ -336,8 +339,8 @@ You can use this like: .. code-block:: python :linenos: - from webob.exc import HTTPException - from webob.exc import HTTPNotFound + from pyramid.httpexceptions import HTTPException + from pyramid.httpexceptions import HTTPNotFound def aview(request): try: diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst index f4d92371a..41a9ad373 100644 --- a/docs/tutorials/wiki/definingviews.rst +++ b/docs/tutorials/wiki/definingviews.rst @@ -54,11 +54,11 @@ The ``view_wiki`` view function The ``view_wiki`` function will be configured to respond as the default view of a ``Wiki`` model object. It always redirects to the ``Page`` object named "FrontPage". It returns an instance of the -:class:`webob.exc.HTTPFound` class (instances of which implement the -WebOb :term:`response` interface), and the -:func:`pyramid.url.model_url` API. -:func:`pyramid.url.model_url` constructs a URL to the ``FrontPage`` -page (e.g. ``http://localhost:6543/FrontPage``), and uses it as the +:class:`pyramid.httpexceptions.HTTPFound` class (instances of which +implement the WebOb :term:`response` interface), and the +:func:`pyramid.url.model_url` API. :func:`pyramid.url.model_url` +constructs a URL to the ``FrontPage`` page +(e.g. ``http://localhost:6543/FrontPage``), and uses it as the "location" of the HTTPFound response, forming an HTTP redirect. The ``view_page`` view function diff --git a/docs/tutorials/wiki/src/authorization/tutorial/login.py b/docs/tutorials/wiki/src/authorization/tutorial/login.py index c029f25ce..ee67d9a5e 100644 --- a/docs/tutorials/wiki/src/authorization/tutorial/login.py +++ b/docs/tutorials/wiki/src/authorization/tutorial/login.py @@ -1,4 +1,4 @@ -from webob.exc import HTTPFound +from pyramid.httpexceptions import HTTPFound from pyramid.view import bfg_view from pyramid.url import model_url diff --git a/docs/tutorials/wiki/src/authorization/tutorial/views.py b/docs/tutorials/wiki/src/authorization/tutorial/views.py index f0fef5d81..8c35afcd6 100644 --- a/docs/tutorials/wiki/src/authorization/tutorial/views.py +++ b/docs/tutorials/wiki/src/authorization/tutorial/views.py @@ -1,7 +1,7 @@ from docutils.core import publish_parts import re -from webob.exc import HTTPFound +from pyramid.httpexceptions import HTTPFound from pyramid.url import model_url from pyramid.security import authenticated_userid diff --git a/docs/tutorials/wiki/src/viewdecorators/tutorial/views.py b/docs/tutorials/wiki/src/viewdecorators/tutorial/views.py index 60cb49faa..937a67344 100644 --- a/docs/tutorials/wiki/src/viewdecorators/tutorial/views.py +++ b/docs/tutorials/wiki/src/viewdecorators/tutorial/views.py @@ -1,7 +1,7 @@ from docutils.core import publish_parts import re -from webob.exc import HTTPFound +from pyramid.httpexceptions import HTTPFound from pyramid.url import model_url from pyramid.view import bfg_view diff --git a/docs/tutorials/wiki/src/views/tutorial/views.py b/docs/tutorials/wiki/src/views/tutorial/views.py index f13ed0381..acc1bbb57 100644 --- a/docs/tutorials/wiki/src/views/tutorial/views.py +++ b/docs/tutorials/wiki/src/views/tutorial/views.py @@ -1,7 +1,7 @@ from docutils.core import publish_parts import re -from webob.exc import HTTPFound +from pyramid.httpexceptions import HTTPFound from pyramid.url import model_url from tutorial.models import Page diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index 1bba7efea..559e6df2f 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -85,8 +85,8 @@ The ``view_wiki`` view function The ``view_wiki`` function will respond as the :term:`default view` of a ``Wiki`` model object. It always redirects to a URL which represents the path to our "FrontPage". It returns an instance of the -:class:`webob.exc.HTTPFound` class (instances of which implement the -WebOb :term:`response` interface), It will use the +:class:`pyramid.httpexceptions.HTTPFound` class (instances of which +implement the WebOb :term:`response` interface), It will use the :func:`pyramid.url.route_url` API to construct a URL to the ``FrontPage`` page (e.g. ``http://localhost:6543/FrontPage``), and will use it as the "location" of the HTTPFound response, forming an diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/login.py b/docs/tutorials/wiki2/src/authorization/tutorial/login.py index 1a54d575c..7a1d1f663 100644 --- a/docs/tutorials/wiki2/src/authorization/tutorial/login.py +++ b/docs/tutorials/wiki2/src/authorization/tutorial/login.py @@ -1,5 +1,4 @@ -from webob.exc import HTTPFound - +from pyramid.httpexceptions import HTTPFound from pyramid.security import remember from pyramid.security import forget from pyramid.url import route_url diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/views.py b/docs/tutorials/wiki2/src/authorization/tutorial/views.py index a7e7a57c7..5abd8391e 100644 --- a/docs/tutorials/wiki2/src/authorization/tutorial/views.py +++ b/docs/tutorials/wiki2/src/authorization/tutorial/views.py @@ -2,8 +2,7 @@ import re from docutils.core import publish_parts -from webob.exc import HTTPFound - +from pyramid.httpexceptions import HTTPFound from pyramid.security import authenticated_userid from pyramid.url import route_url diff --git a/docs/tutorials/wiki2/src/views/tutorial/views.py b/docs/tutorials/wiki2/src/views/tutorial/views.py index c0d793d38..b8896abe7 100644 --- a/docs/tutorials/wiki2/src/views/tutorial/views.py +++ b/docs/tutorials/wiki2/src/views/tutorial/views.py @@ -2,8 +2,7 @@ import re from docutils.core import publish_parts -from webob.exc import HTTPFound - +from pyramid.httpexceptions import HTTPFound from pyramid.url import route_url from tutorial.models import DBSession -- cgit v1.2.3