Changeset 12

Timestamp:

02/17/07 03:16:03

Author:

fumanchu

Message:

Added AttributeDocstrings? metaclass.

Files:

• trunk/geniusql/__init__.py (modified) (2 diffs)

trunk/geniusql/__init__.py

@@ -16 +16 @@
-
-__version__ = "1.0alpha"
+
+
+class _AttributeDocstrings(type):
+    """Metaclass for declaring docstrings for class attributes."""
+    # The full docstring for this type is down in the __init__ method so
+    # that it doesn't show up in help() for every consumer class.
+    
+    def __init__(cls, name, bases, dct):
+        '''Metaclass for declaring docstrings for class attributes.
+        
+        Base Python doesn't provide any syntax for setting docstrings on
+        'data attributes' (non-callables). This metaclass allows class
+        definitions to follow the declaration of a data attribute with
+        a docstring for that attribute; the attribute docstring will be
+        popped from the class dict and folded into the class docstring.
+        
+        The naming convention for attribute docstrings is: <attrname> + "__doc".
+        For example:
+        
+            class Thing(object):
+                """A thing and its properties."""
+                
+                __metaclass__ = cherrypy._AttributeDocstrings
+                
+                height = 50
+                height__doc = """The height of the Thing in inches."""
+        
+        In which case, help(Thing) starts like this:
+        
+            >>> help(mod.Thing)
+            Help on class Thing in module pkg.mod:
+            
+            class Thing(__builtin__.object)
+             |  A thing and its properties.
+             |  
+             |  height [= 50]:
+             |      The height of the Thing in inches.
+             | 
+        
+        The benefits of this approach over hand-edited class docstrings:
+            1. Places the docstring nearer to the attribute declaration.
+            2. Makes attribute docs more uniform ("name (default): doc").
+            3. Reduces mismatches of attribute _names_ between
+               the declaration and the documentation.
+            4. Reduces mismatches of attribute default _values_ between
+               the declaration and the documentation.
+        
+        The benefits of a metaclass approach over other approaches:
+            1. Simpler ("less magic") than interface-based solutions.
+            2. __metaclass__ can be specified at the module global level
+               for classic classes.
+        
+        The type of the attribute is intentionally not included, because
+        that's not How Python Works. Quack.
+        '''
+        
+        newdoc = [cls.__doc__ or ""]
+        
+        dctnames = dct.keys()
+        dctnames.sort()
+        
+        for name in dctnames:
+            if name.endswith("__doc"):
+                # Remove the magic doc attribute.
+                if hasattr(cls, name):
+                    delattr(cls, name)
+                
+                # Get an inspect-style docstring if possible (usually so).
+                val = dct[name]
+                try:
+                    import inspect
+                    val = inspect.getdoc(property(doc=val)).strip()
+                except:
+                    pass
+                
+                # Indent the docstring.
+                val = '\n'.join(['    ' + line.rstrip()
+                                 for line in val.split('\n')])
+                
+                # Get the default value.
+                attrname = name[:-5]
+                try:
+                    attrval = getattr(cls, attrname)
+                except AttributeError:
+                    attrval = "missing"
+                
+                # Add the complete attribute docstring to our list.
+                newdoc.append("%s [= %r]:\n%s" % (attrname, attrval, val))
+        
+        # Add our list of new docstrings to the class docstring.
+        cls.__doc__ = "\n\n".join(newdoc)
+
-
-import threading
@@ -738 +830 @@
-
-class Database(object):
+    
+    __metaclass__ = _AttributeDocstrings
-    
-    adaptertosql = AdapterToSQL()