在Python类继承中继承docstrings [英] Inherit docstrings in Python class inheritance

问题描述

我试图在Python中做一些类继承。我希望每个类和继承的类具有良好的文档格式。所以我认为继承的类，我想要：

• 继承基类docstring

是否有一些最佳做法用于在一个文本字符串中执行这种文本字符串操作类继承情况？多重继承如何？这个地方有没有什么好的讨论/教程？

解决方案

你不是唯一的！之前有关于 comp.lang.python 的讨论，并创建了一个配方。查看 此处 。

 
 doc_inherit decorator 
 
用法：
 
 class Foo（object）：
 def foo（self）：
Frobber
 pass 
 
 class Bar（Foo）：
 @doc_inherit 
 def foo（self） ：
 pass 
 
现在，Bar.foo .__ doc__ == Bar（）。foo .__ doc__ == Foo.foo .__ doc__ ==Frobber

 
从functools导入包裹
 
类DocInherit（对象）：

 Docstring继承方法描述符
 
类本身也用作装饰器

 
 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_i nst（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）：
 
为cls的父母.__ mro __ [1：]：
 overridden = getattr（parent，self.name，None）
如果被覆盖：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）：
如果源为None：
 raise NameError，（在父级中找不到'％s'％self.name）
 func .__ doc__ = source .__ doc__ 
 return func 
 
 doc_inherit = DocInherit 
  

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:

• inherit the base class docstring
• also append relevant extra documentation to the docstring

Is there some "best practice" for doing this sort of docstring manipulation in a class inheritance situation? How about for multiple inheritance? Is there any good discussion/tutorial for this somewhere already?

解决方案

You're not the only one! There was a discussion on comp.lang.python about this a while ago, and a recipe was created. Check it out 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 

这篇关于在Python类继承中继承docstrings的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！