docstring inheritance

[HughSW]

We've been trying to find an easy way to inherit docstrings when
overriding methods in subclasses, e.g. so that Sphinx does a nice job.

We used Shai's DocInherit code from this post:

http://groups.google.com/group/comp.lang.python/tree/browse_frm/thread/1e4075ba10dcbdd9/f63651cd9e76df63?rnum=1&_done=%2Fgroup%2Fcomp.lang.python%2Fbrowse_frm%2Fthread%2F1e4075ba10dcbdd9%2F%3F#doc_5f5963372b951d79

of this thread

http://groups.google.com/group/comp.lang.python/browse_frm/thread/1e4075ba10dcbdd9/

The DocInherit property works fine, except that all the logic for
adding the docstring to the method is evaluated every single time the
method is looked up.  I experimented with a simple caching scheme but
abandoned it.

I've tried a new approach -- it uses the same property mechanism as
Shai's code to delay doing anything until the class exists and the
method is used -- but it does its work only once, the first time the
method is looked up; it adds the docstring from the first mro parent,
and then the property *replaces itself* in the class's namespace with
the method that now has a docstring.  It appears to work in a large
project with extensive testing.

My question concerns whether it is risky to replace a class property
attribute to a method attribute after the class has been created, and
perhaps after the class has been used?  Does this kind of change
violate some subtle or internal expectations of the interpreter
runtime?

Thanks.
-Hugh

Here's the code and doctests:

class InheritDoc(object):
 
"""
    Docstring inheriting method
descriptor

    The class itself is used as a decorator that creates a class
property
for
    the method; the first time the property is used it installs the
method's
doc
    and then replaces itself as a class attribute with the
method!

 
Usage:

    >>> class
Foo(object):
    ...     def foo(self,
x):
    ...
'Frobber'
    ...         print 'Foo.foo()',
x

    Correct usage for overridden method foo(), incorrect usage for
method
bar()

    >>> class
Bar(Foo):
    ...
@inherit_doc
    ...     def foo(self,
x):
    ...         print 'Bar.foo()',
x
    ...
@inherit_doc
    ...     def
bar(self):
    ...         print
'Bar.bar()'

    >>> Bar.foo.__doc__ == Bar().foo.__doc__ == Foo.foo.__doc__ ==
'Frobber'
 
True

    >>>
Foo.foo
    <unbound method
Foo.foo>
    >>>
Foo().foo(10)
    Foo.foo()
10
    >>>
Bar.foo
    <unbound method
Bar.foo>
    >>>
Bar().foo(11)
    Bar.foo()
11

    >>>
Bar.bar
    Traceback (most recent call
last):
      ...
    NameError: inherit_doc cannot find method 'bar' in parents of
'__main__.Bar'

    >>>
Bar().bar
    Traceback (most recent call
last):
      ...
    NameError: inherit_doc cannot find method 'bar' in parents of
'__main__.Bar'
    """
    __slots__ = 'inherit_doc_unbound_method'
    def __init__(self, unbound_method):
        self.inherit_doc_unbound_method = unbound_method
    def __get__(self, obj, cls):
        # a self-destructing descriptor/
property:
        # the first and only time it's used, it fixes the method's doc
and
then
        # replaces itself with the
method

        # find the overridden method in mro sequence, skipping the
class
itself
        method_name = self.inherit_doc_unbound_method.__name__
        mro_iter = iter(cls.__mro__)
        mro_iter.next()
        for parent in mro_iter:
            overridden = getattr(parent, method_name, None)
            if overridden is not None: break
        if overridden is None:
            raise NameError('inherit_doc cannot find method %r in
parents of %r'
                            % (method_name, '%s.%s'%(cls.__module__,
cls.__name__)))

        # XXX next steps are not threadsafe, maybe not safe at
all!
        # set the
doc
        self.inherit_doc_unbound_method.__doc__ = overridden.__doc__
        # replace the property with the
function
        setattr(cls, method_name, self.inherit_doc_unbound_method)
        # use the
replacement
        return getattr(obj if obj is not None else cls, method_name)

inherit_doc = InheritDoc