PEP 3107 -- 函數注解（Function Annotations）

英文原文：https://www.python.org/dev/peps/pep-3107
采集日期：2020-01-22

PEP: 3107
Title: Function Annotations
Version: $Revision$
Last-Modified: $Date$
Author: Collin Winter collinwinter@google.com, Tony Lownds tony@lownds.com
Status: Final
Type: Standards Track
Content-Type: text/x-rst
Created: 2-Dec-2006
Python-Version: 3.0
Post-History:

摘要（Abstract）
原由（Rationale）
函數注解的基礎（Fundamentals of Function Annotations）
語法（Syntax）
函數注解的讀取（Accessing Function Annotations）
應用案例（Use Cases）
標准庫（Standard Library）
- pydoc 和 inspect
與其他 PEP 的關聯（Relation to Other PEPs）
- 函數簽名對象（Function Signature Objects）
實現（Implementation）
未被接受的提案（Rejected Proposals）
參考文獻和腳注（References and Footnotes）

摘要（Abstract）

本 PEP 引入了一種語法，用於為 Python 函數添加元數據注解（metadata annotation）

原由（Rationale）

因為 Python 2.x 沒有為函數參數和返回值提供標准的注解方式，貌似出現了多種工具軟件和程序庫來填補這一空白。有些工具利用 PEP 318 中引入的裝飾器，而另一些則對函數的文檔字符串（docstring）進行解析，以期找到注解信息。

到目前為止已有機制和語法之間存在着巨大差異，本 PEP 旨在提供一種單一的、標准的注解定義方式，以期減少這些差異所引起的混亂。

函數注解的基礎（Fundamentals of Function Annotations）

在開始精確討論 Python 3.0 函數注釋的來龍去脈之前，先來大致討論一下什么是注解：

函數注解（包括參數和返回值）完全是可選內容的。
函數注解只是一種在編譯階段將 Python 表達式與函數的各個部分建立關聯的方式，僅此而已。

Python 本身不會為注解關聯任何特定的含義或意義。注解表達式是獨立存在的，Python 只是讓這些表達式可供使用，用法如下文“函數注解的讀取”所述。

僅當被第三方庫解釋時，注解才能發揮作用。使用者可以隨意使用函數的注解。比如某個程序庫可能會把字符串形式的注解用於提供更好的幫助消息，如下所示：

        def compile(source: "something compilable",
                    filename: "where the compilable thing comes from",
                    mode: "is this a single statement or a suite?"):
            ...

另一個程序庫或許會被用於對 Python 函數和方法提供類型檢查功能。它可以利用注解將函數應有的輸入和返回類型標識出來，格式可能如下：

        def haul(item: Haulable, *vargs: PackAnimal) -> Distance:
            ...

不過，不論是第一個示例中的字符串還是第二個示例中的類型信息，本身都沒有任何意義，一切含義都單獨來自第三方庫。

繼續第2點，即便是對內置類型，本 PEP 也不會引入任何標准語義。這項工作將留給第三方庫去完成。

語法（Syntax）

參數的注解（Parameters）

參數的注解采用可選表達式的格式，跟在參數名的后面：

def foo(a: expression, b: expression = 5):
    ...

若用偽語法（pseudo-grammar）表示，現在參數看起來類似 identifier [: expression] [= expression]。也就是說，注解始終位於參數默認值之前，注解和默認值都是可選的。就像用等號標出默認值一樣，這里用冒號把注解標出來。就像默認值一樣，在函數定義得以運行時將會對所有注解表達式進行求值。

*args 和 **kwargs 這種可變長參數（excess parameters）的注解方式也是類似的：

def foo(*args: expression, **kwargs: expression):
    ...

嵌套參數的注解總是跟在參數名的后面，而不是在右括號后面。嵌套參數中的參數不需要全要帶有注解：

def foo((x1, y1: expression),
        (x2: expression, y2: expression)=(None, None)):
    ...

返回值的注解（Return Values）

到目前為止，還沒有給出如何注解函數返回值的示例。以下便是：

    def sum() -> expression:
        ...

也就是說，現在參數列表后面可以跟一個 -> 和一個 Python 表達式。像參數的注解一樣，函數定義得以運行時將會對該表達式進行求值。

函數定義的語法【11】現在變成了：

decorator: '@' dotted_name [ '(' [arglist] ')' ] NEWLINE
decorators: decorator+
funcdef: [decorators] 'def' NAME parameters ['->' test] ':' suite
parameters: '(' [typedargslist] ')'
typedargslist: ((tfpdef ['=' test] ',')*
                ('*' [tname] (',' tname ['=' test])* [',' '**' tname]
                    | '**' tname)
                | tfpdef ['=' test] (',' tfpdef ['=' test])* [','])
tname: NAME [':' test]
tfpdef: tname | '(' tfplist ')'
tfplist: tfpdef (',' tfpdef)* [',']

Lambda 表達式

lambda 表達式的語法不支持注解。當然 lambda 表達式的語法可以改成支持注解的格式，這需要在參數列表兩側加上括號。但因為以下原因，還是決定不做改動了【12】：

該改動不具兼容性。
不管怎么說，lambda 已式微了。
lambda 表達式一定是能變換成函數的。

函數注解的讀取（Accessing Function Annotations）

只要一經編譯，函數注解就可以通過函數的 __annotations__ 屬性訪問到了。該屬性是一個可變（mutable）字典，將參數名稱映射為一個代表已求值注解表達式的對象。

在 __annotations__ 映射中有一個特殊鍵 "return"。僅當提供了函數返回值的注解時，它才會有效。

例如，以下注解：

def foo(a: 'x', b: 5 + 6, c: list) -> max(2, 9):
    ...

將會生成如下 __annotations__ 映射：

{'a': 'x',
'b': 11,
'c': list,
'return': 9}

選用 return 鍵是因為不能與參數名稱發生沖突，任何時候想把 return 用於參數名稱，都會引發 SyntaxError。

如果函數沒有帶注解或是由 lambda 表達式生成的，則 __annotations__ 將是一個空的可變字典。

應用案例（Use Cases）

在注解的討論過程中，已經給出了很多應用案例。下面給出其中一些案例，按其表達的信息做了分組。這里還包括了一些可能用到注解的現有產品和包示例。

為以下特性提供類型信息
- 類型檢查（【3】、【4】）
- 讓 IDE 能夠顯示函數應該的參數類型和返回類型（【17】）
- 函數重載 / 泛型函數（【22】）
- 與其他語言的橋梁（bridge）（【18】、【19】）
- 適配器（adaptation）模式（【21】、【20】）
- 謂詞邏輯（predicate logic）函數
- 數據庫查詢映射（map）
- RPC 參數封送（marshal）（23）
其他信息
- 參數和返回值的文檔說明（【24】）

標准庫（Standard Library）

pydoc 和 inspect

在顯示函數幫助信息時，pydoc 模塊應能顯示函數的注解。inspect 模塊應改為支持注解信息的獲取。

與其他 PEP 的關聯（Relation to Other PEPs）

函數簽名對象（Function Signature Objects）【13】

函數簽名對象應該公開函數的注解。Parameter 對象或其他地方可能需要做出改動。

實現（Implementation）

參考實現已作為修訂（revision） 53170 【10】簽入 py3k（以前名為“p3yk”）分支中。

未被接受的提案（Rejected Proposals）

BDFL 拒絕了一種特殊語法的想法，該語法要為生成器（generator）添加注解，因為它“太難看了”
【2】。
盡管之前（【5】、【6】）進行過討論，但為注解生成器函數和更高層函數（higher-order）在 stdlib 中納入特殊對象提案最終被拒，因其更適合用第三方庫去實現，將他們包含在標准庫中引發了太多棘手的問題。
雖然對標准類型參數化的語法進行過大量討論，但仍決定應將其留給第三方庫去實現。（【7】、【8】、【9】）
盡管尚有更多討論，但仍決定不對注解的互操作（interoperability）機制作標准化規定。目前對互操作性作標准化約定還為時過早。寧可讓這些約定根據實際使用情況和必要性野蠻生長（organically）一番，也不妄圖強行讓所有用戶都采用某些造作的方案。（【14】、【15】、【16】）