diff options
Diffstat (limited to 'docs/designdefense.rst')
| -rw-r--r-- | docs/designdefense.rst | 41 |
1 files changed, 41 insertions, 0 deletions
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 |