使用Python 3函数注释的开源项目示例

Question

有人能给我一些使用Python3中引入的函数注释的Python开源项目的示例吗？

我想看看这个特性的一些实际用法，看看我是否可以在自己的项目中使用它。

Answer 1

我从来没有见过这个功能在野外使用过。但是，我在为USENIX ;Login:撰写的一篇关于Python3的文章中探讨了函数注释的一个潜在用途，那就是执行合同。例如，您可以这样做：

from functools import wraps

def positive(x):
    'must be positive'
    return x > 0

def negative(x):
    'must be negative'
    return x < 0

def ensure(func):
    'Decorator that enforces contracts on function arguments (if present)'
    return_check = func.__annotations__.get('return',None)
    arg_checks = [(name,func.__annotations__.get(name))
                   for name in func.__code__.co_varnames]

    @wraps(func)
    def assert_call(*args):
        for (name,check),value in zip(arg_checks,args):
            if check: 
                assert check(value),"%s %s" % (name, check.__doc__)
        result = func(*args)
        if return_check:
            assert return_check(result),"return %s" % (return_check.__doc__)
        return result
    return assert_call

# Example use
@ensure
def foo(a:positive, b:negative) -> positive:
    return a-b

如果你这样做，你会看到类似这样的行为：

>>> foo(2,-3)
5
>>> foo(2,3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "ensure.py", line 22, in assert_call
    assert check(value),"%s %s" % (name, check.__doc__)
AssertionError: b must be negative

我应该指出的是，上面的例子需要更多的充实，才能正确地使用默认参数、关键字参数和其他细节。这只是一个想法的草图。

现在，这是不是一个好主意，我只是不知道。我倾向于同意Brandon的观点，即缺乏可组合性是一个问题--特别是当注释开始被不同的库用于不同的目的时。我也想知道，像这样的契约理念是否不能通过装饰器来实现。例如，制作一个像这样使用的装饰器(实现留作练习)：

@ensure(a=positive,b=negative)
def foo(a,b):
    return a-b

作为一个历史记录，我一直觉得函数注释是10多年前Python社区关于“可选静态类型”讨论的产物。无论这是不是最初的动机，我只是不知道。

Answer 2

我将扮演脾气暴躁的角色，并建议不要使用该功能。希望有一天它会被移除。到目前为止，Python在部署吸引人的、正交的、可以堆叠的特性方面做得很好-函数装饰器就是一个很好的例子:如果我使用三个不同的库来装饰我的函数，结果看起来相当干净：

@lru_cache(max_items=5)
@require_basic_auth
@view('index.html')
def index(…):
    ⋮

但是这个新奇而笨拙的“注释”特性却把Python带到了相反的方向:因为一个给定的函数只能注释一次，所以它完全破坏了从不同片段中组合解决方案的能力。如果您有两个库，每个库都希望您代表它们注释相同的函数，那么，在我看来，您将完全受阻。