Python 官方文檔 PEP3107（函數註解）的譯文，本人原創。 ...

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 [email protected], Tony Lownds [email protected]
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】）