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

     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.