Heredar cadenas de documentos en la herencia de clases de Python

Estoy tratando de hacer algo de herencia de clases en Python. Me gustaría que cada clase y clase heredada tenga buenas cadenas de documentación. Así que creo que para la clase heredada, me gustaría:

• heredar la clase base docstring
• tal vez agregar documentación adicional relevante a la cadena de documentos

¿Hay alguna forma (posiblemente elegante o pitónica) de hacer este tipo de manipulación de cadenas de documentos en una situación de herencia de clases? ¿Qué tal la herencia múltiple?

¡No eres el único! Hubo una discusión comp.lang.pythonsobre esto hace un tiempo y se creó una receta. Compruébalo aquí .

"""
doc_inherit decorator

Usage:

class Foo(object):
    def foo(self):
        "Frobber"
        pass

class Bar(Foo):
    @doc_inherit
    def foo(self):
        pass 

Now, Bar.foo.__doc__ == Bar().foo.__doc__ == Foo.foo.__doc__ == "Frobber"
"""

from functools import wraps

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

    The class itself is also used as a decorator
    """

    def __init__(self, mthd):
        self.mthd = mthd
        self.name = mthd.__name__

    def __get__(self, obj, cls):
        if obj:
            return self.get_with_inst(obj, cls)
        else:
            return self.get_no_inst(cls)

    def get_with_inst(self, obj, cls):

        overridden = getattr(super(cls, obj), self.name, None)

        @wraps(self.mthd, assigned=('__name__','__module__'))
        def f(*args, **kwargs):
            return self.mthd(obj, *args, **kwargs)

        return self.use_parent_doc(f, overridden)

    def get_no_inst(self, cls):

        for parent in cls.__mro__[1:]:
            overridden = getattr(parent, self.name, None)
            if overridden: break

        @wraps(self.mthd, assigned=('__name__','__module__'))
        def f(*args, **kwargs):
            return self.mthd(*args, **kwargs)

        return self.use_parent_doc(f, overridden)

    def use_parent_doc(self, func, source):
        if source is None:
            raise NameError, ("Can't find '%s' in parents"%self.name)
        func.__doc__ = source.__doc__
        return func

doc_inherit = DocInherit 

Puede concatenar las cadenas de documentos fácilmente:

class Foo(object):
    """
    Foo Class.
    This class foos around.
    """
    pass

class Bar(Foo):
    """
    Bar class, children of Foo
    Use this when you want to Bar around.
    parent:
    """ 
    __doc__ += Foo.__doc__
    pass

Sin embargo, eso es inútil. La mayoría de las herramientas de generación de documentación ( incluidas Sphinx y Epydoc ) ya extraerán la cadena de documentos principal, incluidos los métodos. Entonces no tienes que hacer nada.

No particularmente elegante, pero simple y directo:

class X(object):
  """This class has a method foo()."""
  def foo(): pass

class Y(X):
  __doc__ = X.__doc__ + ' Also bar().'
  def bar(): pass

Ahora:

>>> print Y.__doc__
This class has a method foo(). Also bar().

Un estilo mixto que puede preservar tanto la sintaxis de la cadena de documentos heredada como el orden preferido puede ser:

class X(object):
  """This class has a method foo()."""
  def foo(): pass

class Y(X):
  """ Also bar()."""
  __doc__ = X.__doc__ + __doc__
  def bar(): pass

Con el mismo resultado que el de Alex:

>>> print Y.__doc__
This class has a method foo(). Also bar().

Hielo fino: jugar con docstring puede inutilizar su módulo con python -OO, espere algo:

TypeError: cannot concatenate 'str' and 'NoneType' objects

Escribí custom_inherit para proporcionar algunas herramientas simples y ligeras para manejar la herencia de cadenas de documentos.

También viene con algunos estilos predeterminados agradables para fusionar diferentes tipos de cadenas de documentos (por ejemplo, cadenas de documentos con formato Numpy, Google y reST). También puede proporcionar su propio estilo con mucha facilidad.

Las secciones de cadenas de documentos superpuestas se transferirán a la sección del niño, de lo contrario, se fusionarán con un formato agradable.