我正在尝试在Python中进行一些类继承。我希望每个班级和继承的班级都有良好的文档字符串。所以我认为对于继承的类,我希望它:
在类继承情况下是否有任何(可能是优雅或pythonic)方式进行此类文档字符串操作?多重继承怎么样?
答案 0 :(得分:37)
你不是唯一一个!不久前就comp.lang.python
进行了讨论,并创建了一个食谱。请查看 here 。
"""
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
答案 1 :(得分:32)
您可以轻松地连接文档字符串:
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)已经拉出了父文档字符串,包括方法。所以你不必做任何事情。
答案 2 :(得分:5)
不是特别优雅,但简单直接:
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().
答案 3 :(得分:5)
可以保留继承的docstring语法和首选顺序的混合阶梯可以是:
class X(object):
"""This class has a method foo()."""
def foo(): pass
class Y(X):
""" Also bar()."""
__doc__ = X.__doc__ + __doc__
def bar(): pass
与Alex的一个输出相同:
>>> print Y.__doc__
This class has a method foo(). Also bar().
薄冰:使用docstring可以使您的模块无法使用python -OO
,期待一些:
TypeError: cannot concatenate 'str' and 'NoneType' objects
答案 4 :(得分:0)
我写了custom_inherit来提供一些简单,轻量级的工具来处理docstring继承。
它还附带了一些很好的默认样式,用于合并不同类型的文档字符串(例如Numpy,Google和reST格式的文档字符串)。您也可以非常轻松地提供自己的风格。
重叠的文档字符串部分将遵循子部分,否则它们将以良好的格式合并在一起。