move defense from changes to design defense document

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