Benjamin Peterson | 55e00f2 | 2008-08-17 18:02:44 +0000 | [diff] [blame] | 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> |
Benjamin Peterson | aa06900 | 2009-01-23 03:26:36 +0000 | [diff] [blame] | 8 | .. sectionauthor:: Benjamin Peterson <benjamin@python.org> |
Benjamin Peterson | 55e00f2 | 2008-08-17 18:02:44 +0000 | [diff] [blame] | 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 | |
Benjamin Peterson | b71caf1 | 2008-08-20 12:55:31 +0000 | [diff] [blame] | 98 | Return a tuple containing names of parameters to this function. |
Benjamin Peterson | 55e00f2 | 2008-08-17 18:02:44 +0000 | [diff] [blame] | 99 | |
| 100 | .. method:: get_locals() |
| 101 | |
Benjamin Peterson | b71caf1 | 2008-08-20 12:55:31 +0000 | [diff] [blame] | 102 | Return a tuple containing names of locals in this function. |
Benjamin Peterson | 55e00f2 | 2008-08-17 18:02:44 +0000 | [diff] [blame] | 103 | |
| 104 | .. method:: get_globals() |
| 105 | |
Benjamin Peterson | b71caf1 | 2008-08-20 12:55:31 +0000 | [diff] [blame] | 106 | Return a tuple containing names of globals in this function. |
Benjamin Peterson | 55e00f2 | 2008-08-17 18:02:44 +0000 | [diff] [blame] | 107 | |
| 108 | .. method:: get_frees() |
| 109 | |
Benjamin Peterson | b71caf1 | 2008-08-20 12:55:31 +0000 | [diff] [blame] | 110 | Return a tuple containing names of free variables in this function. |
Benjamin Peterson | 55e00f2 | 2008-08-17 18:02:44 +0000 | [diff] [blame] | 111 | |
| 112 | |
| 113 | .. class:: Class |
| 114 | |
| 115 | A namespace of a class. This class inherits :class:`SymbolTable`. |
| 116 | |
| 117 | .. method:: get_methods() |
| 118 | |
Benjamin Peterson | b71caf1 | 2008-08-20 12:55:31 +0000 | [diff] [blame] | 119 | Return a tuple containing the names of methods declared in the class. |
Benjamin Peterson | 55e00f2 | 2008-08-17 18:02:44 +0000 | [diff] [blame] | 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 | |
Benjamin Peterson | 55e00f2 | 2008-08-17 18:02:44 +0000 | [diff] [blame] | 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 | |
Benjamin Peterson | e0124bd | 2009-03-09 21:04:33 +0000 | [diff] [blame] | 167 | For example:: |
| 168 | |
| 169 | >>> table = symtable.symtable("def some_func(): pass", "string", "exec") |
| 170 | >>> table.lookup("some_func").is_namespace() |
| 171 | True |
| 172 | |
Benjamin Peterson | 55e00f2 | 2008-08-17 18:02:44 +0000 | [diff] [blame] | 173 | Note that a single name can be bound to multiple objects. If the result |
| 174 | is ``True``, the name may also be bound to other objects, like an int or |
| 175 | list, that does not introduce a new namespace. |
| 176 | |
| 177 | .. method:: get_namespaces() |
| 178 | |
| 179 | Return a list of namespaces bound to this name. |
| 180 | |
| 181 | .. method:: get_namespace() |
| 182 | |
| 183 | Return the namespace bound to this name. If more than one namespace is |
| 184 | bound, a :exc:`ValueError` is raised. |