blocks|key|323459|text|你不是唯一一个！不久前在comp.lang.python上有一个关于这方面的讨论，并创建了一个食谱。请查看。|type|unstyled|depth|inlineStyleRanges|offset|length|style|CODE|entityRanges|data|323460|"""
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+'%25s'+in+parents"%25self.name)
++++++++func.__doc__+=+source.__doc__
++++++++return+func

doc_inherit+=+DocInherit+|code-block|syntax|javascript|323461|entityMap^0|C|G|0|0^^$0|@$1|2|3|4|5|6|7|M|8|@$9|N|A|O|B|C]]|D|@]|E|$]]|$1|F|3|G|5|H|7|P|8|@]|D|@]|E|$I|J]]|$1|K|3|-4|5|6|7|Q|8|@]|D|@]|E|$]]]|L|$]]

You're not the only one! There was a discussion on <code>comp.lang.python</code> about this a while ago, and a recipe was created. Check it out <a href="http://code.activestate.com/recipes/576862/" rel="noreferrer">here</a>.

<pre><code>"""
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 
</code></pre>

blocks|key|321552|text|您可以轻松地连接文档字符串：|type|unstyled|depth|inlineStyleRanges|entityRanges|data|321553|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__+%2B=+Foo.__doc__
++++pass|code-block|syntax|javascript|321554|然而，这是无用的。大多数文档生成工具(包括Sphinx和Epydoc+)将已经提取父文档字符串，包括方法。所以你不需要做任何事。|offset|length|321555|entityMap|0|LINK|mutability|MUTABLE|url|http://sphinx.pocoo.org/|1|http://epydoc.sourceforge.net/^0|0|0|L|6|0|S|6|1|0^^$0|@$1|2|3|4|5|6|7|U|8|@]|9|@]|A|$]]|$1|B|3|C|5|D|7|V|8|@]|9|@]|A|$E|F]]|$1|G|3|H|5|6|7|W|8|@]|9|@$I|X|J|Y|1|Z]|$I|10|J|11|1|12]]|A|$]]|$1|K|3|-4|5|6|7|13|8|@]|9|@]|A|$]]]|L|$M|$5|N|O|P|A|$Q|R]]|S|$5|N|O|P|A|$Q|T]]]]

You can concatenate the docstrings easily:

<pre><code>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
</code></pre>

However, that is useless. Most documentation generation tool (<a href="http://sphinx.pocoo.org/" rel="noreferrer">Sphinx</a> and <a href="http://epydoc.sourceforge.net/" rel="noreferrer">Epydoc</a> included) will already pull parent docstring, including for methods. So you don't have to do anything.

blocks|key|3283385|text|不是特别优雅，但简单直接：|type|unstyled|depth|inlineStyleRanges|entityRanges|data|3283386|class+X(object):
++"""This+class+has+a+method+foo()."""
++def+foo():+pass

class+Y(X):
++__doc__+=+X.__doc__+%2B+'+Also+bar().'
++def+bar():+pass|code-block|syntax|javascript|3283387|现在：|3283388|>>>+print+Y.__doc__
This+class+has+a+method+foo().+Also+bar().|3283389|entityMap^0|0|0|0|0^^$0|@$1|2|3|4|5|6|7|M|8|@]|9|@]|A|$]]|$1|B|3|C|5|D|7|N|8|@]|9|@]|A|$E|F]]|$1|G|3|H|5|6|7|O|8|@]|9|@]|A|$]]|$1|I|3|J|5|D|7|P|8|@]|9|@]|A|$E|F]]|$1|K|3|-4|5|6|7|Q|8|@]|9|@]|A|$]]]|L|$]]

Not particularly elegant, but simple and direct:

<pre><code>class X(object):
 """This class has a method foo()."""
 def foo(): pass

class Y(X):
 __doc__ = X.__doc__ + ' Also bar().'
 def bar(): pass
</code></pre>

Now:

<pre><code>&gt;&gt;&gt; print Y.__doc__
This class has a method foo(). Also bar().
</code></pre>

blocks|key|318823|text|既可以保留继承的文档字符串语法又可以保留首选顺序的混合stile可以是：|type|unstyled|depth|inlineStyleRanges|entityRanges|data|318824|class+X(object):
++"""This+class+has+a+method+foo()."""
++def+foo():+pass

class+Y(X):
++"""+Also+bar()."""
++__doc__+=+X.__doc__+%2B+__doc__
++def+bar():+pass|code-block|syntax|javascript|318825|输出结果与Alex的输出相同：|318826|>>>+print+Y.__doc__
This+class+has+a+method+foo().+Also+bar().|318827|单薄的冰：玩弄docstring会使你的模块在python+-OO中不能使用，可以期待一些：|offset|length|style|BOLD|CODE|318828|TypeError:+cannot+concatenate+'str'+and+'NoneType'+objects|318829|entityMap^0|0|0|0|0|0|5|N|A|0|0^^$0|@$1|2|3|4|5|6|7|V|8|@]|9|@]|A|$]]|$1|B|3|C|5|D|7|W|8|@]|9|@]|A|$E|F]]|$1|G|3|H|5|6|7|X|8|@]|9|@]|A|$]]|$1|I|3|J|5|D|7|Y|8|@]|9|@]|A|$E|F]]|$1|K|3|L|5|6|7|Z|8|@$M|10|N|11|O|P]|$M|12|N|13|O|Q]]|9|@]|A|$]]|$1|R|3|S|5|D|7|14|8|@]|9|@]|A|$E|F]]|$1|T|3|-4|5|6|7|15|8|@]|9|@]|A|$]]]|U|$]]

A mixed stile that can preserve both the inherited docstring syntax and the preferred ordering can be:

<pre><code>class X(object):
 """This class has a method foo()."""
 def foo(): pass

class Y(X):
 """ Also bar()."""
 __doc__ = X.__doc__ + __doc__
 def bar(): pass
</code></pre>

With the same output as Alex's one:

<pre><code>&gt;&gt;&gt; print Y.__doc__
This class has a method foo(). Also bar().
</code></pre>

Thin ice: playing with docstring can make your module unusable with <code>python -OO</code>, expect some:

<pre><code>TypeError: cannot concatenate 'str' and 'NoneType' objects
</code></pre>

blocks|key|320664|text|我编写custom_inherit是为了提供一些简单、轻量级的工具来处理文档字符串继承。|type|unstyled|depth|inlineStyleRanges|entityRanges|offset|length|data|320665|它还提供了一些很好的默认样式，用于合并不同类型的文档字符串(例如，Numpy、Google和reST格式的文档字符串)。你也可以很容易地提供你自己的风格。|320666|重叠的文档字符串节将遵循子节，否则它们将合并在一起，并具有良好的格式。|320667|entityMap|0|LINK|mutability|MUTABLE|url|https://github.com/meowklaski/custom_inherit^0|3|E|0|0|0|0^^$0|@$1|2|3|4|5|6|7|P|8|@]|9|@$A|Q|B|R|1|S]]|C|$]]|$1|D|3|E|5|6|7|T|8|@]|9|@]|C|$]]|$1|F|3|G|5|6|7|U|8|@]|9|@]|C|$]]|$1|H|3|-4|5|6|7|V|8|@]|9|@]|C|$]]]|I|$J|$5|K|L|M|C|$N|O]]]]

I wrote <a href="https://github.com/meowklaski/custom_inherit" rel="noreferrer">custom_inherit</a> to provide some simple, light weight tools for handling docstring inheritance. 

It also comes with some nice default styles for merging different types of docstrings (e.g. Numpy, Google, and reST formatted docstrings). You can also provide your own style very easily.

Overlapping docstring sections will defer to the child's section, otherwise they are merged together with nice formatting.

I'm trying to do some class inheritance in Python. I'd like each class and inherited class to have good docstrings. So I think for the inherited class, I'd like it to:

<ul>
<li>inherit the base class docstring</li>
<li>maybe append relevant extra documentation to the docstring</li>
</ul>

Is there any (possibly elegant or pythonic) way of doing this sort of docstring manipulation in a class inheritance situation? How about for multiple inheritance?

Inherit docstrings in Python class inheritance

Python

我正在尝试用Python做一些类继承。我希望每个类和继承的类都有好的文档字符串。所以我认为对于继承的类，我希望它：继承基类docstringmaybe将相关的额外文档附加到docstring在类继承的情况下，有没有什么方法(可能是优雅的或者pythonic式的)来做这种文档字符串操作？那么多重继承呢？

问在Python类继承中继承文档字符串
EN

社区

活动

资源

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

问在Python类继承中继承文档字符串EN

社区

活动

资源

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

问在Python类继承中继承文档字符串
EN