Logo Search packages:      
Sourcecode: calibre version File versions

def cherrypy::_AttributeDocstrings::__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.

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.

Definition at line 70 of file __init__.py.

00070                                        :
        '''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.
        '''
        
        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)
                
                # Make a uniformly-indented docstring from it.
                val = '\n'.join(['    ' + line.strip()
                                 for line in dct[name].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)


from cherrypy._cperror import HTTPError, HTTPRedirect, InternalRedirect


Generated by  Doxygen 1.6.0   Back to index