Debian Codegraph @

Doc/library/symtable.rst

raw
1 :mod:`!symtable` --- Access to the compiler's symbol tables
2 ===========================================================
3
4 .. module:: symtable
5 :synopsis: Interface to the compiler's internal symbol tables.
6
7 **Source code:** :source:`Lib/symtable.py`
8
9 --------------
10
11 .. moduleauthor:: Jeremy Hylton <[email protected]>
12 .. sectionauthor:: Benjamin Peterson <[email protected]>
13
14
15 Symbol tables are generated by the compiler from AST just before bytecode is
16 generated. The symbol table is responsible for calculating the scope of every
17 identifier in the code. :mod:`symtable` provides an interface to examine these
18 tables.
19
20
21 Generating Symbol Tables
22 ------------------------
23
24 .. function:: symtable(code, filename, compile_type)
25
26 Return the toplevel :class:`SymbolTable` for the Python source *code*.
27 *filename* is the name of the file containing the code. *compile_type* is
28 like the *mode* argument to :func:`compile`.
29
30
31 Examining Symbol Tables
32 -----------------------
33
34 .. class:: SymbolTableType
35
36 An enumeration indicating the type of a :class:`SymbolTable` object.
37
38 .. attribute:: MODULE
39 :value: "module"
40
41 Used for the symbol table of a module.
42
43 .. attribute:: FUNCTION
44 :value: "function"
45
46 Used for the symbol table of a function.
47
48 .. attribute:: CLASS
49 :value: "class"
50
51 Used for the symbol table of a class.
52
53 The following members refer to different flavors of
54 :ref:`annotation scopes <annotation-scopes>`.
55
56 .. attribute:: ANNOTATION
57 :value: "annotation"
58
59 Used for annotations if ``from __future__ import annotations`` is active.
60
61 .. attribute:: TYPE_ALIAS
62 :value: "type alias"
63
64 Used for the symbol table of :keyword:`type` constructions.
65
66 .. attribute:: TYPE_PARAMETERS
67 :value: "type parameters"
68
69 Used for the symbol table of :ref:`generic functions <generic-functions>`
70 or :ref:`generic classes <generic-classes>`.
71
72 .. attribute:: TYPE_VARIABLE
73 :value: "type variable"
74
75 Used for the symbol table of the bound, the constraint tuple or the
76 default value of a single type variable in the formal sense, i.e.,
77 a TypeVar, a TypeVarTuple or a ParamSpec object (the latter two do
78 not support a bound or a constraint tuple).
79
80 .. versionadded:: 3.13
81
82 .. class:: SymbolTable
83
84 A namespace table for a block. The constructor is not public.
85
86 .. method:: get_type()
87
88 Return the type of the symbol table. Possible values are members
89 of the :class:`SymbolTableType` enumeration.
90
91 .. versionchanged:: 3.12
92 Added ``'annotation'``, ``'TypeVar bound'``, ``'type alias'``,
93 and ``'type parameter'`` as possible return values.
94
95 .. versionchanged:: 3.13
96 Return values are members of the :class:`SymbolTableType` enumeration.
97
98 The exact values of the returned string may change in the future,
99 and thus, it is recommended to use :class:`SymbolTableType` members
100 instead of hard-coded strings.
101
102 .. method:: get_id()
103
104 Return the table's identifier.
105
106 .. method:: get_name()
107
108 Return the table's name. This is the name of the class if the table is
109 for a class, the name of the function if the table is for a function, or
110 ``'top'`` if the table is global (:meth:`get_type` returns ``'module'``).
111 For type parameter scopes (which are used for generic classes, functions,
112 and type aliases), it is the name of the underlying class, function, or
113 type alias. For type alias scopes, it is the name of the type alias.
114 For :class:`~typing.TypeVar` bound scopes, it is the name of the ``TypeVar``.
115
116 .. method:: get_lineno()
117
118 Return the number of the first line in the block this table represents.
119
120 .. method:: is_optimized()
121
122 Return ``True`` if the locals in this table can be optimized.
123
124 .. method:: is_nested()
125
126 Return ``True`` if the block is a nested class or function.
127
128 .. method:: has_children()
129
130 Return ``True`` if the block has nested namespaces within it. These can
131 be obtained with :meth:`get_children`.
132
133 .. method:: get_identifiers()
134
135 Return a view object containing the names of symbols in the table.
136 See the :ref:`documentation of view objects <dict-views>`.
137
138 .. method:: lookup(name)
139
140 Lookup *name* in the table and return a :class:`Symbol` instance.
141
142 .. method:: get_symbols()
143
144 Return a list of :class:`Symbol` instances for names in the table.
145
146 .. method:: get_children()
147
148 Return a list of the nested symbol tables.
149
150
151 .. class:: Function
152
153 A namespace for a function or method. This class inherits from
154 :class:`SymbolTable`.
155
156 .. method:: get_parameters()
157
158 Return a tuple containing names of parameters to this function.
159
160 .. method:: get_locals()
161
162 Return a tuple containing names of locals in this function.
163
164 .. method:: get_globals()
165
166 Return a tuple containing names of globals in this function.
167
168 .. method:: get_nonlocals()
169
170 Return a tuple containing names of explicitly declared nonlocals in this function.
171
172 .. method:: get_frees()
173
174 Return a tuple containing names of :term:`free (closure) variables <closure variable>`
175 in this function.
176
177
178 .. class:: Class
179
180 A namespace of a class. This class inherits from :class:`SymbolTable`.
181
182 .. method:: get_methods()
183
184 Return a tuple containing the names of method-like functions declared
185 in the class.
186
187 Here, the term 'method' designates *any* function defined in the class
188 body via :keyword:`def` or :keyword:`async def`.
189
190 Functions defined in a deeper scope (e.g., in an inner class) are not
191 picked up by :meth:`get_methods`.
192
193 For example:
194
195 >>> import symtable
196 >>> st = symtable.symtable('''
197 ... def outer(): pass
198 ...
199 ... class A:
200 ... def f():
201 ... def w(): pass
202 ...
203 ... def g(self): pass
204 ...
205 ... @classmethod
206 ... async def h(cls): pass
207 ...
208 ... global outer
209 ... def outer(self): pass
210 ... ''', 'test', 'exec')
211 >>> class_A = st.get_children()[1]
212 >>> class_A.get_methods()
213 ('f', 'g', 'h')
214
215 Although ``A().f()`` raises :exc:`TypeError` at runtime, ``A.f`` is still
216 considered as a method-like function.
217
218 .. class:: Symbol
219
220 An entry in a :class:`SymbolTable` corresponding to an identifier in the
221 source. The constructor is not public.
222
223 .. method:: get_name()
224
225 Return the symbol's name.
226
227 .. method:: is_referenced()
228
229 Return ``True`` if the symbol is used in its block.
230
231 .. method:: is_imported()
232
233 Return ``True`` if the symbol is created from an import statement.
234
235 .. method:: is_parameter()
236
237 Return ``True`` if the symbol is a parameter.
238
239 .. method:: is_global()
240
241 Return ``True`` if the symbol is global.
242
243 .. method:: is_nonlocal()
244
245 Return ``True`` if the symbol is nonlocal.
246
247 .. method:: is_declared_global()
248
249 Return ``True`` if the symbol is declared global with a global statement.
250
251 .. method:: is_local()
252
253 Return ``True`` if the symbol is local to its block.
254
255 .. method:: is_annotated()
256
257 Return ``True`` if the symbol is annotated.
258
259 .. versionadded:: 3.6
260
261 .. method:: is_free()
262
263 Return ``True`` if the symbol is referenced in its block, but not assigned
264 to.
265
266 .. method:: is_assigned()
267
268 Return ``True`` if the symbol is assigned to in its block.
269
270 .. method:: is_namespace()
271
272 Return ``True`` if name binding introduces new namespace.
273
274 If the name is used as the target of a function or class statement, this
275 will be true.
276
277 For example::
278
279 >>> table = symtable.symtable("def some_func(): pass", "string", "exec")
280 >>> table.lookup("some_func").is_namespace()
281 True
282
283 Note that a single name can be bound to multiple objects. If the result
284 is ``True``, the name may also be bound to other objects, like an int or
285 list, that does not introduce a new namespace.
286
287 .. method:: get_namespaces()
288
289 Return a list of namespaces bound to this name.
290
291 .. method:: get_namespace()
292
293 Return the namespace bound to this name. If more than one or no namespace
294 is bound to this name, a :exc:`ValueError` is raised.
295
296
297 .. _symtable-cli:
298
299 Command-Line Usage
300 ------------------
301
302 .. versionadded:: 3.13
303
304 The :mod:`symtable` module can be executed as a script from the command line.
305
306 .. code-block:: sh
307
308 python -m symtable [infile...]
309
310 Symbol tables are generated for the specified Python source files and
311 dumped to stdout.
312 If no input file is specified, the content is read from stdin.