测试python对象是否有书面文档

Question

某些上下文

我正在编写一个Python应用程序，我想保证没有人忘记编写类，模块和公共函数/方法的文档。为此，我创建了一个单元测试，并且为了问题，断言部分如下所示（需要测试的过滤部分更复杂，我避免将其放在这里）：

...
assertIsNotNone(item.__doc__, msg="%s has no documentation" % name(item))
assertGreaterEqual(len(item.__doc__.strip()), 10, msg="%s should have more documentation" % name(item))
...

name(item)只是一个辅助函数，它为正在检查的对象返回一个正确的名称

问题

并非所有函数或类实际上都需要文档（例如单元测试中的setUp和tearDown方法）。在这些情况下，我想明确表示不会为相关项目编写任何文档。我的单元测试的目标是检查是否遗忘了任何文档，因此测试应该跳过这些情况

我的解决方案

我编写了以下装饰器来应用于这些案例：

import inspect

def no_doc(item):
    """
    Decorator that makes explicit that the function/method 
    or class in question has no documentation 
    """

    result = None

    if inspect.isclass(item):
        class wrapper (item):
            "Class intentionally with no documentation"
            pass

        result = wrapper

    elif inspect.isfunction(item):
        def wrapper(*args, **kwargs):
            "Function intentionally with no documentation"
            return item(*args, **kwargs)

        result = wrapper

    return result

关注

作为装饰器的目标，它只改变 doc 字符串而已，我的装饰函数/方法/类必须尽可能地保持它们的行为。我担心用@no_doc来装饰它们以解决开发问题可能会导致错误或行为更改为生产代码。

最后，问题

我问你我的装饰器方法是否是解决问题的好方法，以及装饰器本身是否安全实施

由于

Answer 1

你不应该对你所拥有的东西（我能想到的）有任何重大问题。但是，您可以通过显式修改__doc__：

来避免新的子类/函数

def no_doc(item):
    """A decorator to add the no-doc docstring
     objects that don't need any other documentation"""

    t = "class" if inspect.isclass(item) else "function"
    item.__doc__ = "This {} intentionally has no documentation".format(t)

    return item

这样做可以确保您获得完全相同的类型（对于类）和函数的完全相同的函数签名，并避免任何这些情况可能导致的任何问题。