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_start()
  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_local()
 148
 149       Return ``True`` if the symbol is local to its block.
 150
 151    .. method:: is_free()
 152
 153       Return ``True`` if the symbol is referenced in its block, but not assigned
 154       to.
 155
 156    .. method:: is_assigned()
 157
 158       Return ``True`` if the symbol is assigned to in its block.
 159
 160    .. method:: is_namespace()
 161
 162       Return ``True`` if name binding introduces new namespace.
 163
 164       If the name is used as the target of a function or class statement, this
 165       will be true.
 166
 167       Note that a single name can be bound to multiple objects.  If the result
 168       is ``True``, the name may also be bound to other objects, like an int or
 169       list, that does not introduce a new namespace.
 170
 171    .. method:: get_namespaces()
 172
 173       Return a list of namespaces bound to this name.
 174
 175    .. method:: get_namespace()
 176
 177       Return the namespace bound to this name.  If more than one namespace is
 178       bound, a :exc:`ValueError` is raised.