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 .. testsetup:: symtable.Class.get_methods
196
197 import warnings
198 context = warnings.catch_warnings()
199 context.__enter__()
200 warnings.simplefilter("ignore", category=DeprecationWarning)
201
202 .. testcleanup:: symtable.Class.get_methods
203
204 context.__exit__()
205
206 .. doctest:: symtable.Class.get_methods
207
208 >>> import symtable
209 >>> st = symtable.symtable('''
210 ... def outer(): pass
211 ...
212 ... class A:
213 ... def f():
214 ... def w(): pass
215 ...
216 ... def g(self): pass
217 ...
218 ... @classmethod
219 ... async def h(cls): pass
220 ...
221 ... global outer
222 ... def outer(self): pass
223 ... ''', 'test', 'exec')
224 >>> class_A = st.get_children()[2]
225 >>> class_A.get_methods()
226 ('f', 'g', 'h')
227
228 Although ``A().f()`` raises :exc:`TypeError` at runtime, ``A.f`` is still
229 considered as a method-like function.
230
231 .. deprecated-removed:: 3.14 3.16
232
233
234 .. class:: Symbol
235
236 An entry in a :class:`SymbolTable` corresponding to an identifier in the
237 source. The constructor is not public.
238
239 .. method:: get_name()
240
241 Return the symbol's name.
242
243 .. method:: is_referenced()
244
245 Return ``True`` if the symbol is used in its block.
246
247 .. method:: is_imported()
248
249 Return ``True`` if the symbol is created from an import statement.
250
251 .. method:: is_parameter()
252
253 Return ``True`` if the symbol is a parameter.
254
255 .. method:: is_type_parameter()
256
257 Return ``True`` if the symbol is a type parameter.
258
259 .. versionadded:: 3.14
260
261 .. method:: is_global()
262
263 Return ``True`` if the symbol is global.
264
265 .. method:: is_nonlocal()
266
267 Return ``True`` if the symbol is nonlocal.
268
269 .. method:: is_declared_global()
270
271 Return ``True`` if the symbol is declared global with a global statement.
272
273 .. method:: is_local()
274
275 Return ``True`` if the symbol is local to its block.
276
277 .. method:: is_annotated()
278
279 Return ``True`` if the symbol is annotated.
280
281 .. versionadded:: 3.6
282
283 .. method:: is_free()
284
285 Return ``True`` if the symbol is referenced in its block, but not assigned
286 to.
287
288 .. method:: is_free_class()
289
290 Return *True* if a class-scoped symbol is free from
291 the perspective of a method.
292
293 Consider the following example::
294
295 def f():
296 x = 1 # function-scoped
297 class C:
298 x = 2 # class-scoped
299 def method(self):
300 return x
301
302 In this example, the class-scoped symbol ``x`` is considered to
303 be free from the perspective of ``C.method``, thereby allowing
304 the latter to return *1* at runtime and not *2*.
305
306 .. versionadded:: 3.14
307
308 .. method:: is_assigned()
309
310 Return ``True`` if the symbol is assigned to in its block.
311
312 .. method:: is_comp_iter()
313
314 Return ``True`` if the symbol is a comprehension iteration variable.
315
316 .. versionadded:: 3.14
317
318 .. method:: is_comp_cell()
319
320 Return ``True`` if the symbol is a cell in an inlined comprehension.
321
322 .. versionadded:: 3.14
323
324 .. method:: is_namespace()
325
326 Return ``True`` if name binding introduces new namespace.
327
328 If the name is used as the target of a function or class statement, this
329 will be true.
330
331 For example::
332
333 >>> table = symtable.symtable("def some_func(): pass", "string", "exec")
334 >>> table.lookup("some_func").is_namespace()
335 True
336
337 Note that a single name can be bound to multiple objects. If the result
338 is ``True``, the name may also be bound to other objects, like an int or
339 list, that does not introduce a new namespace.
340
341 .. method:: get_namespaces()
342
343 Return a list of namespaces bound to this name.
344
345 .. method:: get_namespace()
346
347 Return the namespace bound to this name. If more than one or no namespace
348 is bound to this name, a :exc:`ValueError` is raised.
349
350
351 .. _symtable-cli:
352
353 Command-Line Usage
354 ------------------
355
356 .. versionadded:: 3.13
357
358 The :mod:`!symtable` module can be executed as a script from the command line.
359
360 .. code-block:: sh
361
362 python -m symtable [infile...]
363
364 Symbol tables are generated for the specified Python source files and
365 dumped to stdout.
366 If no input file is specified, the content is read from stdin.