# `symtable` --- 存取編譯器的符號表

原始碼：Lib/symtable.py

Symbol tables are generated by the compiler from AST just before bytecode is generated. The symbol table is responsible for calculating the scope of every identifier in the code. `symtable` provides an interface to examine these tables.

## 產生符號表

symtable.symtable(code, filename, compile_type, *, module=None)

  Return the toplevel `SymbolTable` for the Python source code. filename is the name of the file containing the code. compile_type is like the mode argument to `compile()`. The optional argument module specifies the module name. It is needed to unambiguous filter syntax warnings by module name.

  在 3.15 版被加入: Added the module parameter.

## 檢查符號表

class symtable.SymbolTableType

  表明 `SymbolTable` 物件型別的列舉。

  MODULE = "module"

    用於模組的符號表。

  FUNCTION = "function"

    用於函式的符號表。

  CLASS = "class"

    用於類別的符號表。

  以下成員代表不同風格的註釋作用域。

  ANNOTATION = "annotation"

    如果 `from __future__ import annotations` 處於活動狀態，則用於註解。

  TYPE_ALIAS = "type alias"

    用於 `type` 結構的符號表。

  TYPE_PARAMETERS = "type parameters"

    用於泛型函式 (generic functions)或泛型類別 (generic classes)的符號表。

  TYPE_VARIABLE = "type variable"

    用於形式意義上 (formal sense) 的繫結、約束元組 (constraint tuple) 或單一型別變數的預設值的符號表，即 TypeVar、TypeVarTuple 或 ParamSpec 物件（後兩者不支援繫結或約束元組）。

  在 3.13 版被加入.

class symtable.SymbolTable

  一個區塊 (block) 的命名空間表 (namespace table) 。建構函式 (constructor) 並不公開。

  get_type()

    回傳符號表的類型。可能的值為 `SymbolTableType` 列舉的成員。

    在 3.12 版的變更: 新增了 `'annotation'`、`'TypeVar bound'`、`'type alias'` 和 `'type parameter'` 作為可能的回傳值。

    在 3.13 版的變更: 回傳值是 `SymbolTableType` 列舉的成員。

    回傳字串的確切值在未來可能會發生變化，因此建議使用 `SymbolTableType` 成員而不是寫死 (hard-coded) 字串。

  get_id()

    回傳表的識別器。

  get_name()

    回傳表的名稱。如果表用於類別，則這是類別的名稱；如果表用於函式，則這是函式的名稱；如果表是全域的，則為 `'top'` （`get_type()` 會回傳 `'module'`）。對於型別參數作用域（用於泛型類別、函式和型別別名），它是底層類別、函式或型別別名的名稱。對於型別別名作用域，它是型別別名的名稱。對於 `TypeVar` 綁定作用域，它會是 `TypeVar` 的名稱。

  get_lineno()

    回傳此表所代表的區塊中第一行的編號。

  is_optimized()

    如果可以最佳化該表中的區域變數，則回傳 `True`。

  is_nested()

    如果區塊是巢狀類別或函式，則回傳 `True`。

  has_children()

    如果區塊內有巢狀命名空間，則回傳 `True`。這些可以透過 `get_children()` 獲得。

  get_identifiers()

    回傳包含表中符號之名稱的視圖物件 (view object)。請參閱視圖物件的文件。

  lookup(name)

    在表中查找 name 並回傳一個 `Symbol` 實例。

  get_symbols()

    回傳表中名稱的 `Symbol` 實例串列。

  get_children()

    回傳巢狀符號表的串列。

class symtable.Function

  一個函式或方法的命名空間。該類別繼承自 `SymbolTable`。

  get_parameters()

    回傳一個包含此函式參數名稱的元組 (tuple)。

  get_locals()

    回傳一個包含此函式中區域變數 (locals) 名稱的元組。

  get_globals()

    回傳一個包含此函式中全域變數 (globals) 名稱的元組。

  get_nonlocals()

    回傳一個包含此函式中明確宣告的非區域變數 (nonlocals) 名稱的元組。

  get_frees()

    回傳一個包含此函式中的自由（閉包）變數 (free (closure) variables) 名稱的元組。

  get_cells()

    Return a tuple containing names of cell variables in this table.

    在 3.15.0a5 (unreleased) 版被加入.

class symtable.Class

  一個類別的命名空間。該類別繼承自 `SymbolTable`。

  get_methods()

    回傳一個包含類別中聲明的類似方法之函式名稱的元組。

    在這裡，術語「方法 (method)」表示透過 `def` 或 `async def` 在類別主體中定義的任何函式。

    `get_methods()` 不會取得更深作用域內定義的函式（例如在內部類別中）。

    舉例來說：

        >>> import symtable
        >>> st = symtable.symtable('''
        ... def outer(): pass
        ...
        ... class A:
        ...    def f():
        ...        def w(): pass
        ...
        ...    def g(self): pass
        ...
        ...    @classmethod
        ...    async def h(cls): pass
        ...
        ...    global outer
        ...    def outer(self): pass
        ... ''', 'test', 'exec')
        >>> class_A = st.get_children()[2]
        >>> class_A.get_methods()
        ('f', 'g', 'h')

    儘管 `A().f()` 會在 runtime 引發 `TypeError`，但 `A.f` 仍然被視為類似方法的函式。

    自從版本 3.14 後不推薦使用，將會自版本 3.16 中移除。.

class symtable.Symbol

  `SymbolTable` 中的條目對應於來源中的識別器。建構函式不是公開的。

  get_name()

    回傳符號的名稱。

  is_referenced()

    如果該符號在其區塊中使用，則回傳 `True`。

  is_imported()

    如果符號是從 import 陳述式建立的，則回傳 `True`。

  is_parameter()

    如果符號是一個參數，則回傳 `True`。

  is_type_parameter()

    如果符號是一個型別參數，則回傳 `True`。

    在 3.14 版被加入.

  is_global()

    如果符號是全域的，則回傳 `True`。

  is_nonlocal()

    如果符號是非區域的，則回傳 `True`。

  is_declared_global()

    如果使用全域陳述式將符號聲明為全域的，則回傳 `True`。

  is_local()

    如果符號是其區塊的區域符號，則回傳 `True`。

  is_annotated()

    如果符號有被註釋，則回傳 `True`。

    在 3.6 版被加入.

  is_free()

    如果該符號在其區塊中被參照 (referenced) 但未被賦值 (assigned)，則回傳 `True`。

  is_cell()

    Return `True` if the symbol is referenced but not assigned in a nested block.

    在 3.15.0a5 (unreleased) 版被加入.

  is_free_class()

    Return True if a class-scoped symbol is free from the perspective of a method.

    參考以下範例：

        def f():
            x = 1  # 函式範圍
            class C:
                x = 2  # 類別範圍
                def method(self):
                    return x

    In this example, the class-scoped symbol `x` is considered to be free from the perspective of `C.method`, thereby allowing the latter to return 1 at runtime and not 2.

    在 3.14 版被加入.

  is_assigned()

    如果該符號被賦值到其區塊中，則回傳 `True`。

  is_comp_iter()

    Return `True` if the symbol is a comprehension iteration variable.

    在 3.14 版被加入.

  is_comp_cell()

    Return `True` if the symbol is a cell in an inlined comprehension.

    在 3.14 版被加入.

  is_namespace()

    如果名稱綁定引入 (introduce) 新的命名空間，則回傳 `True`。

    如果名稱用作函式或類別陳述式的目標，則這將會是 true。

    舉例來說：

        >>> table = symtable.symtable("def some_func(): pass", "string", "exec")
        >>> table.lookup("some_func").is_namespace()
        True

    請注意，單個名稱可以綁定到多個物件。如果結果為 `True`，則該名稱也可能被綁定到其他物件，例如 int 或 list，而不會引入新的命名空間。

  get_namespaces()

    回傳綁定到該名稱的命名空間的串列。

  get_namespace()

    回傳綁定到該名稱的命名空間。如果該名稱綁定了多個命名空間或沒有命名空間，則會引發 `ValueError`。

## 命令列用法

在 3.13 版被加入.

The `symtable` module can be executed as a script from the command line.

    python -m symtable [infile...]

為指定的 Python 原始檔產生符號表並轉儲 (dump) 到 stdout。如果未指定輸入檔案，則從 stdin 讀取內容。