← Back to branch summary

~ubuntu-branches/ubuntu/trusty/python3.4/trusty-proposed

« back to all changes in this revision

Viewing changes to Doc/library/symtable.rst

  • Committer: Package Import Robot
  • Author(s): Matthias Klose
  • Date: 2013-11-25 09:44:27 UTC
  • Revision ID: package-import@ubuntu.com-20131125094427-lzxj8ap5w01lmo7f
Tags: upstream-3.4~b1
Import upstream version 3.4~b1

Show diffs side-by-side

added added

removed removed

Lines of Context:
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.