Успадковувати документи у спадкуванні класу Python

Я намагаюся зробити успадкування класу в Python. Я хотів би, щоб кожен клас та успадкований клас мали хороші документи. Тому я думаю, що для успадкованого класу я хотів би:

• успадкувати документацію базового класу
• можливо, додати відповідну додаткову документацію до документації

Чи існує якийсь (можливо, елегантний чи пітонічний) спосіб здійснення такого роду маніпуляцій із документами у ситуації успадкування класу? Як щодо багаторазового успадкування?

Ти не єдиний! Нещодавно comp.lang.pythonпро це йшла дискусія , і був створений рецепт. Перевірте тут .

"""
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 

Ви можете легко об’єднати документи:

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

Однак це марно. Більшість інструментів для генерації документації ( включаючи Sphinx та Epydoc ) вже буде витягувати батьківський документ, включаючи методи. Тож вам не потрібно нічого робити.

Не особливо елегантно, але просто і прямо:

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

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

Зараз:

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

Змішаним стилем, який може зберегти як успадкований синтаксис документації, так і бажаний порядок може бути:

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

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

З тим самим результатом, що й у Алекса:

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

Тонкий лід: гра з документацією може зробити ваш модуль непридатним для використання python -OO, очікуйте:

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

Я написав custom_inherit, щоб надати кілька простих, легких інструментів для обробки спадщини docstring.

Він також постачається з декількома приємними стилями за замовчуванням для об’єднання різних типів текстових рядків (наприклад, Numpy, Google та форматовані текстові рядки reST). Ви також можете дуже легко надати свій власний стиль.

Накладання розділів документації переноситься на розділ дитини, інакше вони поєднуються разом із приємним форматуванням.