Added documentation to httpexceptions, and a special extractor for HTTPException subclasses

2 files changed, 31 insertions, 2 deletions

diff --git a/paste/docsupport/extract.py b/paste/docsupport/extract.py
index e0836df..4e2efe3 100644
--- a/paste/docsupport/extract.py
+++ b/paste/docsupport/extract.py
@@ -5,6 +5,7 @@ import textwrap
 import findmodules
 from paste.docsupport import metadata
 from paste.util.classinit import ClassInitMeta
+from paste.httpexceptions import HTTPException
 
 extractors = []
 
@@ -12,10 +13,14 @@ class Extractor(object):
 
     __metaclass__ = ClassInitMeta
     match_type = None
+    match_level = None
 
     def __classinit__(cls, new_attrs):
         if cls.__bases__ != (object,):
-            extractors.append(cls)
+            if cls.match_level is None:
+                extractors.append(cls)
+            else:
+                extractors.insert(cls.match_level, cls)
 
     def __init__(self, obj, context):
         self.obj = obj
@@ -46,7 +51,7 @@ class ModuleExtractor(Extractor):
 
 class ClassExtractor(Extractor):
 
-    match_type = type
+    match_type = (type, types.ClassType)
         
     def extract(self):
         self.context.writeheader(self.context.last_name, type='Class')
@@ -155,6 +160,20 @@ class MethodExtractor(Extractor):
             value = self.obj.func_globals[value]
         return value
 
+class HTTPExtractor(Extractor):
+
+    match_level = 0
+
+    def extract(self):
+        self.context.writekey(self.obj.__name__)
+        self.context.write('%s %s\n' % (self.obj.code, self.obj.title))
+        self.context.endkey()
+
+    def applies(cls, obj, context):
+        return (isinstance(obj, types.ClassType)
+                and issubclass(obj, HTTPException))
+    applies = classmethod(applies)
+
 ############################################################
 ## Context
 ############################################################
diff --git a/paste/httpexceptions.py b/paste/httpexceptions.py
index 01d68f5..16fca6f 100644
--- a/paste/httpexceptions.py
+++ b/paste/httpexceptions.py
@@ -196,12 +196,14 @@ class HTTPHttpVersionNotSupported(HTTPException):
     title = 'HTTP Version Not Supported'
     message = ('The HTTP version is not supported.')
 
+__all__ = []
 _exceptions = {}
 for name, value in globals().items():
     if (isinstance(value, (type, types.ClassType)) and
         issubclass(value, HTTPException) and
         value.code):
         _exceptions[value.code] = value
+        __all__.append(name)
 def get_exception(code):
     return _exceptions[code]
 
@@ -211,6 +213,11 @@ def get_exception(code):
 
 def middleware(application):
 
+    """
+    This middleware catches any exceptions (which are subclasses of
+    `HTTPException`) and turns them into proper HTTP responses.
+    """
+
     def start_application(environ, start_response):
         app_started = []
         def checked_start_response(status, headers, exc_info=None):
@@ -232,3 +239,6 @@ def middleware(application):
             return [e.html(environ)]
         
     return start_application
+
+__all__.extend(['middleware', 'get_exception'])
+