Doc/library/symtable.rst

   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 .. moduleauthor:: Jeremy Hylton <jeremy@alum.mit.edu>
   8 .. sectionauthor:: Benjamin Peterson <benjamin@python.org>
   9
  10
  11 Symbol tables are generated by the compiler from AST just before bytecode is
  12 generated.  The symbol table is responsible for calculating the scope of every
  13 identifier in the code.  :mod:`symtable` provides an interface to examine these
  14 tables.
  15
  16
  17 Generating Symbol Tables
  18 ------------------------
  19
  20 .. function:: symtable(code, filename, compile_type)
  21
  22    Return the toplevel :class:`SymbolTable` for the Python source *code*.
  23    *filename* is the name of the file containing the code.  *compile_type* is
  24    like the *mode* argument to :func:`compile`.
  25
  26
  27 Examining Symbol Tables
  28 -----------------------
  29
  30 .. class:: SymbolTable
  31
  32    A namespace table for a block.  The constructor is not public.
  33
  34    .. method:: get_type()
  35
  36       Return the type of the symbol table.  Possible values are ``'class'``,
  37       ``'module'``, and ``'function'``.
  38
  39    .. method:: get_id()
  40
  41       Return the table's identifier.
  42
  43    .. method:: get_name()
  44
  45       Return the table's name.  This is the name of the class if the table is
  46       for a class, the name of the function if the table is for a function, or
  47       ``'top'`` if the table is global (:meth:`get_type` returns ``'module'``).
  48
  49    .. method:: get_lineno()
  50
  51       Return the number of the first line in the block this table represents.
  52
  53    .. method:: is_optimized()
  54
  55       Return ``True`` if the locals in this table can be optimized.
  56
  57    .. method:: is_nested()
  58
  59       Return ``True`` if the block is a nested class or function.
  60
  61    .. method:: has_children()
  62
  63       Return ``True`` if the block has nested namespaces within it.  These can
  64       be obtained with :meth:`get_children`.
  65
  66    .. method:: has_exec()
  67
  68       Return ``True`` if the block uses ``exec``.
  69
  70    .. method:: has_import_star()
  71
  72       Return ``True`` if the block uses a starred from-import.
  73
  74    .. method:: get_identifiers()
  75
  76       Return a list of names of symbols in this table.
  77
  78    .. method:: lookup(name)
  79
  80       Lookup *name* in the table and return a :class:`Symbol` instance.
  81
  82    .. method:: get_symbols()
  83
  84       Return a list of :class:`Symbol` instances for names in the table.
  85
  86    .. method:: get_children()
  87
  88       Return a list of the nested symbol tables.
  89
  90
  91 .. class:: Function
  92
  93    A namespace for a function or method.  This class inherits
  94    :class:`SymbolTable`.
  95
  96    .. method:: get_parameters()
  97
  98       Return a tuple containing names of parameters to this function.
  99
 100    .. method:: get_locals()
 101
 102       Return a tuple containing names of locals in this function.
 103
 104    .. method:: get_globals()
 105
 106       Return a tuple containing names of globals in this function.
 107
 108    .. method:: get_frees()
 109
 110       Return a tuple containing names of free variables in this function.
 111
 112
 113 .. class:: Class
 114
 115    A namespace of a class.  This class inherits :class:`SymbolTable`.
 116
 117    .. method:: get_methods()
 118
 119       Return a tuple containing the names of methods declared in the class.
 120
 121
 122 .. class:: Symbol
 123
 124    An entry in a :class:`SymbolTable` corresponding to an identifier in the
 125    source.  The constructor is not public.
 126
 127    .. method:: get_name()
 128
 129       Return the symbol's name.
 130
 131    .. method:: is_referenced()
 132
 133       Return ``True`` if the symbol is used in its block.
 134
 135    .. method:: is_imported()
 136
 137       Return ``True`` if the symbol is created from an import statement.
 138
 139    .. method:: is_parameter()
 140
 141       Return ``True`` if the symbol is a parameter.
 142
 143    .. method:: is_global()
 144
 145       Return ``True`` if the symbol is global.
 146
 147    .. method:: is_declared_global()
 148
 149       Return ``True`` if the symbol is declared global with a global statement.
 150
 151    .. method:: is_local()
 152
 153       Return ``True`` if the symbol is local to its block.
 154
 155    .. method:: is_free()
 156
 157       Return ``True`` if the symbol is referenced in its block, but not assigned
 158       to.
 159
 160    .. method:: is_assigned()
 161
 162       Return ``True`` if the symbol is assigned to in its block.
 163
 164    .. method:: is_namespace()
 165
 166       Return ``True`` if name binding introduces new namespace.
 167
 168       If the name is used as the target of a function or class statement, this
 169       will be true.
 170
 171       For example::
 172
 173          >>> table = symtable.symtable("def some_func(): pass", "string", "exec")
 174          >>> table.lookup("some_func").is_namespace()
 175          True
 176
 177       Note that a single name can be bound to multiple objects.  If the result
 178       is ``True``, the name may also be bound to other objects, like an int or
 179       list, that does not introduce a new namespace.
 180
 181    .. method:: get_namespaces()
 182
 183       Return a list of namespaces bound to this name.
 184
 185    .. method:: get_namespace()
 186
 187       Return the namespace bound to this name.  If more than one namespace is
 188       bound, a :exc:`ValueError` is raised.