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__, __delattr__, __eq__, __ge__, __getattribute__, __gt__, __hash__, __instancecheck__, __le__, __lt__, __ne__, __new__, __repr__, __setattr__, __subclasscheck__, __subclasses__, mro

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

Properties [hide private]

Inherited from type: __abstractmethods__, __base__, __bases__, __basicsize__, __dictoffset__, __flags__, __itemsize__, __mro__, __name__, __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.

For various formatting reasons, you should write multiline docs
with a leading newline and not a trailing one:
    
    response__doc = """
    The response object for the current thread. In the main thread,
    and any threads which are not HTTP requests, this is None."""

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__