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 <jeremy@alum.mit.edu> 12.. sectionauthor:: Benjamin Peterson <benjamin@python.org> 13 14 15Symbol tables are generated by the compiler from AST just before bytecode is 16generated. The symbol table is responsible for calculating the scope of every 17identifier in the code. :mod:`symtable` provides an interface to examine these 18tables. 19 20 21Generating 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 31Examining 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 299Command-Line Usage 300------------------ 301 302.. versionadded:: 3.13 303 304The :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 310Symbol tables are generated for the specified Python source files and 311dumped to stdout. 312If no input file is specified, the content is read from stdin. 313