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

原始碼： Lib/symtable.py

符號表 (symbol table) 是在生成位元組碼 (bytecode) 之前由編譯器從 AST 生成的。符號表負責計算程式碼中每個識別器 (identifier) 的範圍。`symtable` 提供了一個介面來檢查這些表。

## 產生符號表

symtable.symtable(code, filename, compile_type)

  回傳 Python 原始 code 的頂層 `SymbolTable`。filename 是包含程式碼之檔案之名稱。compile_type 類似於 `compile()` 的 mode 引數。

## 檢查符號表

class symtable.SymbolTableType

  An enumeration indicating the type of a `SymbolTable` object.

  MODULE = "module"

    Used for the symbol table of a module.

  FUNCTION = "function"

    Used for the symbol table of a function.

  CLASS = "class"

    Used for the symbol table of a class.

  The following members refer to different flavors of annotation scopes.

  ANNOTATION = "annotation"

    Used for annotations if `from __future__ import annotations` is active.

  TYPE_ALIAS = "type alias"

    Used for the symbol table of `type` constructions.

  TYPE_PARAMETERS = "type parameters"

    Used for the symbol table of generic functions or generic classes.

  TYPE_VARIABLE = "type variable"

    Used for the symbol table of the bound, the constraint tuple or the default value of a single type variable in the formal sense, i.e., a TypeVar, a TypeVarTuple or a ParamSpec object (the latter two do not support a bound or a constraint tuple).

  在 3.13 版被加入.

class symtable.SymbolTable

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

  get_type()

    Return the type of the symbol table. Possible values are members of the `SymbolTableType` enumeration.

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

    在 3.13 版的變更: Return values are members of the `SymbolTableType` enumeration.

    The exact values of the returned string may change in the future, and thus, it is recommended to use `SymbolTableType` members instead of hard-coded strings.

  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 variables) 名稱的元組。

class symtable.Class

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

  get_methods()

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

    Here, the term 'method' designates any function defined in the class body via `def` or `async def`.

    Functions defined in a deeper scope (e.g., in an inner class) are not picked up by `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()[1]
        >>> class_A.get_methods()
        ('f', 'g', 'h')

    Although `A().f()` raises `TypeError` at runtime, `A.f` is still considered as a method-like function.

class symtable.Symbol

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

  get_name()

    回傳符號的名稱。

  is_referenced()

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

  is_imported()

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

  is_parameter()

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

  is_global()

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

  is_nonlocal()

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

  is_declared_global()

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

  is_local()

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

  is_annotated()

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

    在 3.6 版被加入.

  is_free()

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

  is_assigned()

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

  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`。

## Command-Line Usage

在 3.13 版被加入.

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

    python -m symtable [infile...]

Symbol tables are generated for the specified Python source files and dumped to stdout. If no input file is specified, the content is read from stdin.