symtable --- 访问编译器的符号表

Source code： 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.

Added in version 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"

用于 泛型函数 或 泛型类 的符号表。

TYPE_VARIABLE = "type variable"

用于正式意义下的绑定、约束元组或单个类型变量的默认值的符号变量的符号表，即 TypeVar, TypeVarTuple 或 ParamSpec 对象（后两者不支持绑定或约束元组）。

Added in version 3.13.

class symtable.SymbolTable

某个代码块的命名空间表。构造函数不公开。

get_type()

返回符号表的类型。 可能的值为 SymbolTableType 枚举的成员。

在 3.12 版本发生变更: 增加 'annotation', 'TypeVar bound', 'type alias' 和 'type parameter' 作为可能的返回值。

在 3.13 版本发生变更: 返回值为 SymbolTableType 枚举的成员。

返回字符串的实际值可能在未来发生变化，因此，建议使用 SymbolTableType 成员而不是硬编码的字符串。

get_id()

返回符号表的标识符

get_name()

返回表名称。 如果表是针对类的则为类名；如果是针对函数的则为函数名；或者如果表是全局的 (get_type() 返回 'module') 则为 'top'。 对于类型形参作用域 (用于泛型类、函数和类型别名)，它将为底层类、函数或类型别名的名称。 对于类型别名作用域，它将为类型别名的名称。 对于 TypeVar 绑定作用域，它将为 TypeVar 的名称。

get_lineno()

返回符号表所代表代码块的第一行编号。

is_optimized()

如果符号表中的局部变量可能被优化过，则返回 True。

is_nested()

如果代码块是嵌套类或函数，则返回 True。

has_children()

如果代码块中有嵌套的命名空间，则返回 True。可通过 get_children() 读取。

get_identifiers()

返回一个包含表中符号名称的视图对象。 参见 视图对象文档。

lookup(name)

在符号表中查找 name 并返回一个 Symbol 实例。

get_symbols()

返回符号表中所有符号的 Symbol 实例的列表。

get_children()

返回嵌套符号表的列表。

class symtable.Function

函数或方法的命名空间。 该类继承自 SymbolTable。

get_parameters()

返回由函数的参数名组成的元组。

get_locals()

返回函数中局部变量名组成的元组。

get_globals()

返回函数中全局变量名组成的元组。

get_nonlocals()

返回一个包含在此函数中显式声明的非局部变量名称的元组。

get_frees()

返回一个包含在此函数中的 自由（闭包）变量 名称的元组。

get_cells()

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

Added in version 3.15.0a5 (unreleased).

class symtable.Class

类的命名空间。 该类继承自 SymbolTable。

get_methods()

返回一个包含类中声明的方法型函数的名称的元组。

在这里，术语 '方法' 是指 任何 在 class 语句体中通过 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() 在运行时会引发 TypeError，但 A.f 仍然被视为是方法型函数。

从 3.14 版起已弃用，将在 3.16 版中移除.

class symtable.Symbol

SymbolTable 中的数据项，对应于源码中的某个标识符。构造函数不公开。

get_name()

返回符号名

is_referenced()

如果符号在代码块中被引用了，则返回 True。

is_imported()

如果符号是由导入语句创建的，则返回 True。

is_parameter()

如果符号是参数，返回 True。

is_type_parameter()

如果符号是一个类型形参则返回 True。

Added in version 3.14.

is_global()

如果符号是全局变量，则返回 True。

is_nonlocal()

如果符号为非局部变量，则返回 True。

is_declared_global()

如果符号用 global 声明为全局变量，则返回 True。

is_local()

如果符号是代码块内的局部变量，则返回 True。

is_annotated()

如果符号带有注解，则返回 True。

Added in version 3.6.

is_free()

如果符号在代码块中被引用，但未赋值，则返回 True。

is_cell()

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

Added in version 3.15.0a5 (unreleased).

is_free_class()

如果类级作用域的符号对于一个方法来说是自由的则返回 True。

比如下面的例子:

def f():
    x = 1  # 函数级作用域
    class C:
        x = 2  # 类级作用域
        def method(self):
            return x

在这个示例中，类级作用域的符号 x 从is considered to be free from the perspective of C.method 的视角来说是自由的，因此允许后者在运行时返回 1 而不是 2。

Added in version 3.14.

is_assigned()

如果符号在代码块中赋值，则返回 True。

is_comp_iter()

如果符号是一个推导式的迭代变量则返回 True。

Added in version 3.14.

is_comp_cell()

如果符号是一个内联推导式中的单元则返回 True。

Added in version 3.14.

is_namespace()

如果符号名绑定引入了新的命名空间，则返回 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。

命令行用法

Added in version 3.13.

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

python -m symtable [infile...]

符号表将针对指定的 Python 文件生成并转储至 stdout。 如果未指定输入文件，将从 stdin 读取内容。