Package cherrypy :: Class _AttributeDocstrings
[hide private]
[frames] | no frames]

Type _AttributeDocstrings

source code

object --+    
         |    
      type --+
             |
            _AttributeDocstrings

Metaclass for declaring docstrings for class attributes.

Instance Methods [hide private]
the object's type
__init__(cls, name, bases, dct)
Metaclass for declaring docstrings for class attributes.
source code

Inherited from type: __call__, __cmp__, __delattr__, __eq__, __ge__, __getattribute__, __gt__, __hash__, __le__, __lt__, __ne__, __new__, __repr__, __setattr__, __subclasses__, mro

Inherited from object: __format__, __reduce__, __reduce_ex__, __sizeof__, __str__, __subclasshook__

Properties [hide private]

Inherited from type: __abstractmethods__, __base__, __bases__, __basicsize__, __dictoffset__, __flags__, __instancecheck__, __itemsize__, __mro__, __name__, __subclasscheck__, __weakrefoffset__

Inherited from object: __class__

Method Details [hide private]

__init__(cls, name, bases, dct)
(Constructor)

source code 
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.

Returns: the object's type
Overrides: object.__init__