2

背景

我有一个库，其中包含多个读取或写入文件的函数。每个函数都接受文件作为第一个参数，可以是文件对象，也可以是文件名。因此，所有函数在开头都有相同的代码，类似于以下内容：

if isinstance(f, str):
    file_obj = open(f, 'w')
else:
    file_obj = f

现在我想我可以在装饰器中编写一次并将所有功能包装在其中，而不是重复自己。（我也在考虑在同一个装饰器中实现上下文管理器接口。）

因此，如果我这样做，函数将如下所示：

@file_aware('w')
def function(f, *args, **kwargs):
    """Do stuff. `f` can be file object or file name"""
    for line in f:
       ....

问题

我担心的是现在函数的文档字符串与下面的代码不对应。（我打算用 . 保留装饰函数的文档字符串functools.wraps。）它会降低代码的可读性/可维护性/透明度吗？据我了解，装饰器可以很容易地来来去去，但同时这有点改变了 API（我不打算删除该功能）。这种情况下的“最佳实践”方式是什么？

我可以考虑在装饰器中自动处理文档字符串，但是：

  • 这不是最自然的事情；
  • 这仅对在线文档有意义，并且不会帮助（相反）阅读源代码的人。
4

1 回答 1

3

一种选择是将文档字符串传递给装饰器。这样，您仍然可以通过函数定义获得一个文档字符串来读取源代码，但是如果您要更改或删除装饰器，您最终不会得到一个不正确的文档字符串。

例如：

@file_aware(docstring="Do stuff. `f` can be file object or file name", mode="r")
def function(f, *args, **kwargs):
    for line in f:
       ....

你的file_aware装饰器可能看起来像这样：

def file_aware(docstring, mode):
    def deco(func):
        @functools.wraps(func)
        def wrapped(f, *args, **kwargs):
            if isinstance(f, str):
                file_obj = open(f, mode)
            else:
                file_obj = f
            return func(file_obj, *args, **kwargs)
        wrapped.__doc__ = docstring
        return wrapped
    return deco
于 2012-12-18T17:34:41.720 回答