0

一些上下文

我正在编写一个 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)只是一个辅助函数，它为被检查的对象返回一个正确的名称

问题

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

我的解决方案

我编写了以下装饰器以应用于这些情况：

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

关注点

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

最后，问题

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

谢谢

4

1 回答 1

2

你不应该对那里的东西有任何重大问题（我能想到的）。但是，您可以通过显式修改来避免新的子类/函数__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

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

于 2013-05-31T17:27:27.390 回答