diff options
| -rw-r--r-- | CHANGES.txt | 17 | ||||
| -rw-r--r-- | docs/designdefense.rst | 41 |
2 files changed, 44 insertions, 14 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index 6a41f30fe..9a25a6b04 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -343,20 +343,9 @@ Behavior Changes (e.g. ``HTTPNotFound``) are no longer just import aliases for classes that actually live in ``webob.exc``. Instead, we've defined our own exception classes within the module that mirror and emulate the ``webob.exc`` - exception response objects almost entirely. We do this in order to a) - allow the exception responses to subclass ``pyramid.response.Response``, - which speeds up response generation slightly due to the way the Pyramid - router works, b) allows us to provide alternate __call__ logic which also - speeds up response generation, c) allows the exception classes to provide - for the proper value of ``self.RequestClass`` (pyramid.request.Request), d) - allows us freedom from having to think about backwards compatibility code - present in ``webob.exc`` having to do with Python 2.4, which we no longer - support, e) We change the behavior of two classes (HTTPNotFound and - HTTPForbidden) in the module so that they can be used internally for - notfound and forbidden exceptions, f) allows us to influence the docstrings - of the exception classes to provide Pyramid-specific documentation, and g) - allows us to silence a stupid deprecation warning under Python 2.6 when the - response objects are used as exceptions (related to ``self.message``). + exception response objects almost entirely. See the "Design Defense" doc + section named "Pyramid Uses its Own HTTP Exception Classes" for more + information. Backwards Incompatibilities --------------------------- diff --git a/docs/designdefense.rst b/docs/designdefense.rst index 77711016d..cfd395dd9 100644 --- a/docs/designdefense.rst +++ b/docs/designdefense.rst @@ -1011,6 +1011,47 @@ which returns Zope3-security-proxy-wrapped objects for each traversed object (including the :term:`context` and the :term:`root`). This would have the effect of creating a more Zope3-like environment without much effort. +Pyramid Uses its Own HTTP Exception Class Hierarchy Rather ``webob.exc`` +------------------------------------------------------------------------ + +.. note:: This defense is new as of Pyramid 1.1. + +The HTTP exception classes defined in :mod:`pyramid.httpexceptions` are very +much like the ones defined in ``webob.exc`` +(e.g. :class:`~pyramid.httpexceptions.HTTPNotFound`, +:class:`~pyramid.httpexceptions.HTTPForbidden`, etc). They have the same +names and largely the same behavior and all have a very similar +implementation, but not the same identity. Here's why they have a separate +identity: + +- Making them separate allows the HTTP exception classes to subclass + :class:`pyramid.response.Response`. This speeds up response generation + slightly due to the way the Pyramid router works. The same speedup could + be gained by monkeypatching ``webob.response.Response`` but it's usually + the case that monkeypatching turns out to be evil and wrong. + +- Making them separate allows them to provide alternate ``__call__`` logic + which also speeds up response generation. + +- Making them separate allows the exception classes to provide for the proper + value of ``RequestClass`` (:class:`pyramid.request.Request`). + +- Making them separate allows us freedom from having to think about backwards + compatibility code present in ``webob.exc`` having to do with Python 2.4, + which we no longer support in Pyramid 1.1+. + +- We change the behavior of two classes + (:class:`~pyramid.httpexceptions.HTTPNotFound` and + :class:`~pyramid.httpexceptions.HTTPForbidden`) in the module so that they + can be used by Pyramid internally for notfound and forbidden exceptions. + +- Making them separate allows us to influence the docstrings of the exception + classes to provide Pyramid-specific documentation. + +- Making them separate allows us to silence a stupid deprecation warning + under Python 2.6 when the response objects are used as exceptions (related + to ``self.message``). + .. _simpler_traversal_model: Pyramid has Simpler Traversal Machinery than Does Zope |