move defense from changes to design defense document

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