/Doc/library/symtable.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 178 lines · 97 code · 81 blank · 0 comment · 0 complexity · cbce4011bfaf1277856b0df1a382debb MD5 · raw file

  1. :mod:`symtable` --- Access to the compiler's symbol tables
  2. ==========================================================
  3. .. module:: symtable
  4. :synopsis: Interface to the compiler's internal symbol tables.
  5. .. moduleauthor:: Jeremy Hylton <jeremy@alum.mit.edu>
  6. .. sectionauthor:: Benjamin Peterson
  7. Symbol tables are generated by the compiler from AST just before bytecode is
  8. generated. The symbol table is responsible for calculating the scope of every
  9. identifier in the code. :mod:`symtable` provides an interface to examine these
  10. tables.
  11. Generating Symbol Tables
  12. ------------------------
  13. .. function:: symtable(code, filename, compile_type)
  14. Return the toplevel :class:`SymbolTable` for the Python source *code*.
  15. *filename* is the name of the file containing the code. *compile_type* is
  16. like the *mode* argument to :func:`compile`.
  17. Examining Symbol Tables
  18. -----------------------
  19. .. class:: SymbolTable
  20. A namespace table for a block. The constructor is not public.
  21. .. method:: get_type()
  22. Return the type of the symbol table. Possible values are ``'class'``,
  23. ``'module'``, and ``'function'``.
  24. .. method:: get_id()
  25. Return the table's identifier.
  26. .. method:: get_name()
  27. Return the table's name. This is the name of the class if the table is
  28. for a class, the name of the function if the table is for a function, or
  29. ``'top'`` if the table is global (:meth:`get_type` returns ``'module'``).
  30. .. method:: get_lineno()
  31. Return the number of the first line in the block this table represents.
  32. .. method:: is_optimized()
  33. Return ``True`` if the locals in this table can be optimized.
  34. .. method:: is_nested()
  35. Return ``True`` if the block is a nested class or function.
  36. .. method:: has_children()
  37. Return ``True`` if the block has nested namespaces within it. These can
  38. be obtained with :meth:`get_children`.
  39. .. method:: has_exec()
  40. Return ``True`` if the block uses ``exec``.
  41. .. method:: has_import_start()
  42. Return ``True`` if the block uses a starred from-import.
  43. .. method:: get_identifiers()
  44. Return a list of names of symbols in this table.
  45. .. method:: lookup(name)
  46. Lookup *name* in the table and return a :class:`Symbol` instance.
  47. .. method:: get_symbols()
  48. Return a list of :class:`Symbol` instances for names in the table.
  49. .. method:: get_children()
  50. Return a list of the nested symbol tables.
  51. .. class:: Function
  52. A namespace for a function or method. This class inherits
  53. :class:`SymbolTable`.
  54. .. method:: get_parameters()
  55. Return a tuple containing names of parameters to this function.
  56. .. method:: get_locals()
  57. Return a tuple containing names of locals in this function.
  58. .. method:: get_globals()
  59. Return a tuple containing names of globals in this function.
  60. .. method:: get_frees()
  61. Return a tuple containing names of free variables in this function.
  62. .. class:: Class
  63. A namespace of a class. This class inherits :class:`SymbolTable`.
  64. .. method:: get_methods()
  65. Return a tuple containing the names of methods declared in the class.
  66. .. class:: Symbol
  67. An entry in a :class:`SymbolTable` corresponding to an identifier in the
  68. source. The constructor is not public.
  69. .. method:: get_name()
  70. Return the symbol's name.
  71. .. method:: is_referenced()
  72. Return ``True`` if the symbol is used in its block.
  73. .. method:: is_imported()
  74. Return ``True`` if the symbol is created from an import statement.
  75. .. method:: is_parameter()
  76. Return ``True`` if the symbol is a parameter.
  77. .. method:: is_global()
  78. Return ``True`` if the symbol is global.
  79. .. method:: is_local()
  80. Return ``True`` if the symbol is local to its block.
  81. .. method:: is_free()
  82. Return ``True`` if the symbol is referenced in its block, but not assigned
  83. to.
  84. .. method:: is_assigned()
  85. Return ``True`` if the symbol is assigned to in its block.
  86. .. method:: is_namespace()
  87. Return ``True`` if name binding introduces new namespace.
  88. If the name is used as the target of a function or class statement, this
  89. will be true.
  90. Note that a single name can be bound to multiple objects. If the result
  91. is ``True``, the name may also be bound to other objects, like an int or
  92. list, that does not introduce a new namespace.
  93. .. method:: get_namespaces()
  94. Return a list of namespaces bound to this name.
  95. .. method:: get_namespace()
  96. Return the namespace bound to this name. If more than one namespace is
  97. bound, a :exc:`ValueError` is raised.