cpython/Doc/library/symtable.rst

189 lines
4.9 KiB
ReStructuredText
Raw Normal View History

:mod:`symtable` --- Access to the compiler's symbol tables
==========================================================
.. module:: symtable
:synopsis: Interface to the compiler's internal symbol tables.
.. moduleauthor:: Jeremy Hylton <jeremy@alum.mit.edu>
.. sectionauthor:: Benjamin Peterson <benjamin@python.org>
Symbol tables are generated by the compiler from AST just before bytecode is
generated. The symbol table is responsible for calculating the scope of every
identifier in the code. :mod:`symtable` provides an interface to examine these
tables.
Generating Symbol Tables
------------------------
.. function:: symtable(code, filename, compile_type)
Return the toplevel :class:`SymbolTable` for the Python source *code*.
*filename* is the name of the file containing the code. *compile_type* is
like the *mode* argument to :func:`compile`.
Examining Symbol Tables
-----------------------
.. class:: SymbolTable
A namespace table for a block. The constructor is not public.
.. method:: get_type()
Return the type of the symbol table. Possible values are ``'class'``,
``'module'``, and ``'function'``.
.. method:: get_id()
Return the table's identifier.
.. method:: get_name()
Return the table's name. This is the name of the class if the table is
for a class, the name of the function if the table is for a function, or
``'top'`` if the table is global (:meth:`get_type` returns ``'module'``).
.. method:: get_lineno()
Return the number of the first line in the block this table represents.
.. method:: is_optimized()
Return ``True`` if the locals in this table can be optimized.
.. method:: is_nested()
Return ``True`` if the block is a nested class or function.
.. method:: has_children()
Return ``True`` if the block has nested namespaces within it. These can
be obtained with :meth:`get_children`.
.. method:: has_exec()
Return ``True`` if the block uses ``exec``.
.. method:: has_import_star()
Return ``True`` if the block uses a starred from-import.
.. method:: get_identifiers()
Return a list of names of symbols in this table.
.. method:: lookup(name)
Lookup *name* in the table and return a :class:`Symbol` instance.
.. method:: get_symbols()
Return a list of :class:`Symbol` instances for names in the table.
.. method:: get_children()
Return a list of the nested symbol tables.
.. class:: Function
A namespace for a function or method. This class inherits
:class:`SymbolTable`.
.. method:: get_parameters()
2008-08-20 09:55:31 -03:00
Return a tuple containing names of parameters to this function.
.. method:: get_locals()
2008-08-20 09:55:31 -03:00
Return a tuple containing names of locals in this function.
.. method:: get_globals()
2008-08-20 09:55:31 -03:00
Return a tuple containing names of globals in this function.
.. method:: get_frees()
2008-08-20 09:55:31 -03:00
Return a tuple containing names of free variables in this function.
.. class:: Class
A namespace of a class. This class inherits :class:`SymbolTable`.
.. method:: get_methods()
2008-08-20 09:55:31 -03:00
Return a tuple containing the names of methods declared in the class.
.. class:: Symbol
An entry in a :class:`SymbolTable` corresponding to an identifier in the
source. The constructor is not public.
.. method:: get_name()
Return the symbol's name.
.. method:: is_referenced()
Return ``True`` if the symbol is used in its block.
.. method:: is_imported()
Return ``True`` if the symbol is created from an import statement.
.. method:: is_parameter()
Return ``True`` if the symbol is a parameter.
.. method:: is_global()
Return ``True`` if the symbol is global.
Merged revisions 73004,73439,73496,73509,73529,73564,73576-73577,73595-73596,73605 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r73004 | jeffrey.yasskin | 2009-05-28 22:44:31 -0500 (Thu, 28 May 2009) | 5 lines Fix nearly all compilation warnings under Apple gcc-4.0. Tested with OPT="-g -Wall -Wstrict-prototypes -Werror" in both --with-pydebug mode and --without. There's still a batch of non-prototype warnings in Xlib.h that I don't know how to fix. ........ r73439 | benjamin.peterson | 2009-06-15 19:29:31 -0500 (Mon, 15 Jun 2009) | 1 line don't mask encoding errors when decoding a string #6289 ........ r73496 | vinay.sajip | 2009-06-21 12:37:27 -0500 (Sun, 21 Jun 2009) | 1 line Issue #6314: logging.basicConfig() performs extra checks on the "level" argument. ........ r73509 | amaury.forgeotdarc | 2009-06-22 14:33:48 -0500 (Mon, 22 Jun 2009) | 2 lines #4490 Fix sample code run by "python -m xml.sax.xmlreader" ........ r73529 | r.david.murray | 2009-06-23 13:02:46 -0500 (Tue, 23 Jun 2009) | 4 lines Fix issue 5230 by having pydoc's safeimport check to see if the import error was thrown from itself in order to decide if the module can't be found. Thanks to Lucas Prado Melo for collaborating on the fix and tests. ........ r73564 | amaury.forgeotdarc | 2009-06-25 17:29:29 -0500 (Thu, 25 Jun 2009) | 6 lines #2016 Fix a crash in function call when the **kwargs dictionary is mutated during the function call setup. This even gives a slight speedup, probably because tuple allocation is faster than PyMem_NEW. ........ r73576 | benjamin.peterson | 2009-06-26 18:37:06 -0500 (Fri, 26 Jun 2009) | 1 line document is_declared_global() ........ r73577 | benjamin.peterson | 2009-06-27 09:16:23 -0500 (Sat, 27 Jun 2009) | 1 line link to extensive generator docs in the reference manual ........ r73595 | ezio.melotti | 2009-06-27 18:45:39 -0500 (Sat, 27 Jun 2009) | 1 line stmt and setup can contain multiple statements, see #5896 ........ r73596 | ezio.melotti | 2009-06-27 19:07:45 -0500 (Sat, 27 Jun 2009) | 1 line Fixed a wrong apostrophe ........ r73605 | georg.brandl | 2009-06-28 07:10:18 -0500 (Sun, 28 Jun 2009) | 1 line Remove stray pychecker directive. ........
2009-06-28 14:22:03 -03:00
.. method:: is_declared_global()
Return ``True`` if the symbol is declared global with a global statement.
.. method:: is_local()
Return ``True`` if the symbol is local to its block.
.. method:: is_free()
Return ``True`` if the symbol is referenced in its block, but not assigned
to.
.. method:: is_assigned()
Return ``True`` if the symbol is assigned to in its block.
.. method:: is_namespace()
Return ``True`` if name binding introduces new namespace.
If the name is used as the target of a function or class statement, this
will be true.
Merged revisions 69998-69999,70002,70022-70023,70025-70026,70061,70086,70145,70171,70183,70188,70235,70244,70275,70281 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r69998 | benjamin.peterson | 2009-02-26 13:04:40 -0600 (Thu, 26 Feb 2009) | 1 line the startship is rather outdated now ........ r69999 | benjamin.peterson | 2009-02-26 13:05:59 -0600 (Thu, 26 Feb 2009) | 1 line comma ........ r70002 | andrew.kuchling | 2009-02-26 16:34:30 -0600 (Thu, 26 Feb 2009) | 1 line The curses panel library is now supported ........ r70022 | georg.brandl | 2009-02-27 10:23:18 -0600 (Fri, 27 Feb 2009) | 1 line #5361: fix typo. ........ r70023 | georg.brandl | 2009-02-27 10:39:26 -0600 (Fri, 27 Feb 2009) | 1 line #5363: fix cmpfiles() docs. Another instance where a prose description is twice as long as the code. ........ r70025 | georg.brandl | 2009-02-27 10:52:55 -0600 (Fri, 27 Feb 2009) | 1 line #5344: fix punctuation. ........ r70026 | georg.brandl | 2009-02-27 10:59:03 -0600 (Fri, 27 Feb 2009) | 1 line #5365: add quick look conversion table for different time representations. ........ r70061 | hirokazu.yamamoto | 2009-02-28 09:24:00 -0600 (Sat, 28 Feb 2009) | 1 line Binary flag is needed on windows. ........ r70086 | benjamin.peterson | 2009-03-01 21:35:12 -0600 (Sun, 01 Mar 2009) | 1 line fix a silly problem of caching gone wrong #5401 ........ r70145 | benjamin.peterson | 2009-03-03 16:51:57 -0600 (Tue, 03 Mar 2009) | 1 line making the writing more formal ........ r70171 | facundo.batista | 2009-03-04 15:18:17 -0600 (Wed, 04 Mar 2009) | 3 lines Fixed a typo. ........ r70183 | benjamin.peterson | 2009-03-04 18:17:57 -0600 (Wed, 04 Mar 2009) | 1 line add example ........ r70188 | hirokazu.yamamoto | 2009-03-05 03:34:14 -0600 (Thu, 05 Mar 2009) | 1 line Fixed memory leak on failure. ........ r70235 | benjamin.peterson | 2009-03-07 18:21:17 -0600 (Sat, 07 Mar 2009) | 1 line fix funky indentation ........ r70244 | martin.v.loewis | 2009-03-08 09:06:19 -0500 (Sun, 08 Mar 2009) | 2 lines Add Chris Withers. ........ r70275 | georg.brandl | 2009-03-09 11:35:48 -0500 (Mon, 09 Mar 2009) | 2 lines Add missing space. ........ r70281 | benjamin.peterson | 2009-03-09 15:38:56 -0500 (Mon, 09 Mar 2009) | 1 line gzip and bz2 are context managers ........
2009-03-09 18:04:33 -03:00
For example::
>>> table = symtable.symtable("def some_func(): pass", "string", "exec")
>>> table.lookup("some_func").is_namespace()
True
Note that a single name can be bound to multiple objects. If the result
is ``True``, the name may also be bound to other objects, like an int or
list, that does not introduce a new namespace.
.. method:: get_namespaces()
Return a list of namespaces bound to this name.
.. method:: get_namespace()
Return the namespace bound to this name. If more than one namespace is
bound, a :exc:`ValueError` is raised.