Kế thừa docstrings trong kế thừa lớp Python

Tôi đang cố gắng thực hiện một số kế thừa lớp trong Python. Tôi muốn mỗi lớp và lớp kế thừa có docstrings tốt. Vì vậy, tôi nghĩ đối với lớp kế thừa, tôi muốn nó:

• kế thừa docstring lớp cơ sở
• có thể thêm tài liệu bổ sung có liên quan vào docstring

Có cách nào (có thể thanh lịch hoặc lạ lùng) để thực hiện loại thao tác chuỗi doc này trong tình huống kế thừa lớp không? Làm thế nào về đa kế thừa?

Bạn không phải là người duy nhất! Đã có một cuộc thảo luận comp.lang.pythonvề điều này một thời gian trước, và một công thức đã được tạo ra. Kiểm tra nó ra ở đây .

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

Bạn có thể nối các docstrings một cách dễ dàng:

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

Tuy nhiên, điều đó là vô ích. Hầu hết công cụ tạo tài liệu ( bao gồm cả Sphinx và Epydoc ) sẽ kéo chuỗi tài liệu gốc, bao gồm cả các phương thức. Vì vậy, bạn không phải làm bất cứ điều gì.

Không đặc biệt thanh lịch, nhưng đơn giản và trực tiếp:

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

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

Hiện nay:

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

Một giai đoạn hỗn hợp có thể bảo tồn cả cú pháp docstring kế thừa và thứ tự ưu tiên có thể là:

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

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

Với đầu ra tương tự như của Alex:

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

Đá mỏng: chơi với docstring có thể khiến mô-đun của bạn không sử dụng được python -OO, mong đợi một số:

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

Tôi đã viết custom_inherit để cung cấp một số công cụ đơn giản, trọng lượng nhẹ để xử lý kế thừa docstring.

Nó cũng đi kèm với một số kiểu mặc định đẹp mắt để hợp nhất các loại docstrings khác nhau (ví dụ: Numpy, Google và docstrings được định dạng reST). Bạn cũng có thể cung cấp phong cách của riêng bạn rất dễ dàng.

Các phần chuỗi tài liệu chồng chéo sẽ chuyển sang phần của trẻ, nếu không, chúng được hợp nhất với nhau với định dạng đẹp.