"symtable" --- コンパイラーの記号表へのアクセス
***********************************************

**ソースコード:** Lib/symtable.py

======================================================================

記号表(symbol table)は、コンパイラが AST からバイトコードを生成する直
前に作られます。記号表はコード中の全ての識別子のスコープの算出に責任を
持ちます。 "symtable" はこうした記号表を調べるインターフェイスを提供し
ます。


記号表の生成
============

symtable.symtable(code, filename, compile_type)

   Python ソース *code* に対するトップレベルの "SymbolTable" を返しま
   す。 *filename* はコードを収めてあるファイルの名前です。
   *compile_type* は "compile()" の *mode* 引数のようなものです。


記号表の検査
============

class symtable.SymbolTableType

   An enumeration indicating the type of a "SymbolTable" object.

   MODULE = "module"

      Used for the symbol table of a module.

   FUNCTION = "function"

      Used for the symbol table of a function.

   CLASS = "class"

      Used for the symbol table of a class.

   The following members refer to different flavors of annotation
   scopes.

   ANNOTATION = "annotation"

      Used for annotations if "from __future__ import annotations" is
      active.

   TYPE_ALIAS = "type alias"

      Used for the symbol table of "type" constructions.

   TYPE_PARAMETERS = "type parameters"

      Used for the symbol table of generic functions or generic
      classes.

   TYPE_VARIABLE = "type variable"

      Used for the symbol table of the bound, the constraint tuple or
      the default value of a single type variable in the formal sense,
      i.e., a TypeVar, a TypeVarTuple or a ParamSpec object (the
      latter two do not support a bound or a constraint tuple).

   Added in version 3.13.

class symtable.SymbolTable

   ブロックに対する名前空間の記号表。コンストラクタはパブリックではあ
   りません。

   get_type()

      Return the type of the symbol table.  Possible values are
      members of the "SymbolTableType" enumeration.

      バージョン 3.12 で変更: Added "'annotation'",  "'TypeVar
      bound'", "'type alias'", and "'type parameter'" as possible
      return values.

      バージョン 3.13 で変更: Return values are members of the
      "SymbolTableType" enumeration.The exact values of the returned
      string may change in the future, and thus, it is recommended to
      use "SymbolTableType" members instead of hard-coded strings.

   get_id()

      記号表の識別子を返します。

   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 ("get_type()"
      returns "'module'"). For type parameter scopes (which are used
      for generic classes, functions, and type aliases), it is the
      name of the underlying class, function, or type alias. For type
      alias scopes, it is the name of the type alias. For "TypeVar"
      bound scopes, it is the name of the "TypeVar".

   get_lineno()

      この記号表に対応するブロックの一行目の行番号を返します。

   is_optimized()

      この記号表に含まれるローカル変数が最適化できるならば "True" を返
      します。

   is_nested()

      ブロックが入れ子のクラスまたは関数のとき "True" を返します。

   has_children()

      ブロックが入れ子の名前空間を含んでいるならば "True" を返します。
      入れ子の名前空間は "get_children()" で得られます。

   get_identifiers()

      Return a view object containing the names of symbols in the
      table. See the documentation of view objects.

   lookup(name)

      記号表から名前 *name* を見つけ出して "Symbol" インスタンスとして
      返します。

   get_symbols()

      記号表中の名前を表す "Symbol" インスタンスのリストを返します。

   get_children()

      入れ子になった記号表のリストを返します。

class symtable.Function

   A namespace for a function or method.  This class inherits from
   "SymbolTable".

   get_parameters()

      この関数の引数名からなるタプルを返します。

   get_locals()

      この関数のローカル変数の名前からなるタプルを返します。

   get_globals()

      この関数のグローバル変数の名前からなるタプルを返します。

   get_nonlocals()

      Return a tuple containing names of explicitly declared nonlocals
      in this function.

   get_frees()

      Return a tuple containing names of *free (closure) variables* in
      this function.

class symtable.Class

   A namespace of a class.  This class inherits from "SymbolTable".

   get_methods()

      Return a tuple containing the names of method-like functions
      declared in the class.

      Here, the term 'method' designates *any* function defined in the
      class body via "def" or "async def".

      Functions defined in a deeper scope (e.g., in an inner class)
      are not picked up by "get_methods()".

      例えば:

         >>> import symtable
         >>> st = symtable.symtable('''
         ... def outer(): pass
         ...
         ... class A:
         ...    def f():
         ...        def w(): pass
         ...
         ...    def g(self): pass
         ...
         ...    @classmethod
         ...    async def h(cls): pass
         ...
         ...    global outer
         ...    def outer(self): pass
         ... ''', 'test', 'exec')
         >>> class_A = st.get_children()[2]
         >>> class_A.get_methods()
         ('f', 'g', 'h')

      Although "A().f()" raises "TypeError" at runtime, "A.f" is still
      considered as a method-like function.

      Deprecated since version 3.14, will be removed in version 3.16.

class symtable.Symbol

   "SymbolTable" のエントリーでソースの識別子に対応するものです。コン
   ストラクタはパブリックではありません。

   get_name()

      記号の名前を返します。

   is_referenced()

      記号がそのブロックの中で使われていれば "True" を返します。

   is_imported()

      記号が import 文で作られたものならば "True" を返します。

   is_parameter()

      記号がパラメータならば "True" を返します。

   is_type_parameter()

      Return "True" if the symbol is a type parameter.

      Added in version 3.14.

   is_global()

      記号がグローバルならば "True" を返します。

   is_nonlocal()

      記号が非ローカルならば "True" を返します。

   is_declared_global()

      記号が global 文によってグローバルであると宣言されているなら
      "True" を返します。

   is_local()

      記号がそのブロックに対してローカルならば "True" を返します。

   is_annotated()

      記号が注釈付きならば "True" を返します。

      Added in version 3.6.

   is_free()

      記号がそのブロックの中で参照されていて、しかし代入は行われないな
      らば "True" を返します。

   is_free_class()

      Return *True* if a class-scoped symbol is free from the
      perspective of a method.

      次に示す例について考えてみてください。:

         def f():
             x = 1  # function-scoped
             class C:
                 x = 2  # class-scoped
                 def method(self):
                     return x

      In this example, the class-scoped symbol "x" is considered to be
      free from the perspective of "C.method", thereby allowing the
      latter to return *1* at runtime and not *2*.

      Added in version 3.14.

   is_assigned()

      記号がそのブロックの中で代入されているならば "True" を返します。

   is_comp_iter()

      Return "True" if the symbol is a comprehension iteration
      variable.

      Added in version 3.14.

   is_comp_cell()

      Return "True" if the symbol is a cell in an inlined
      comprehension.

      Added in version 3.14.

   is_namespace()

      名前の束縛が新たな名前空間を導入するならば "True" を返します。

      名前が関数または class 文のターゲットとして使われるならば、真で
      す。

      例えば:

         >>> table = symtable.symtable("def some_func(): pass", "string", "exec")
         >>> table.lookup("some_func").is_namespace()
         True

      一つの名前が複数のオブジェクトに束縛されうることに注意しましょう
      。結果が "True" であったとしても、その名前は他のオブジェクトにも
      束縛されるかもしれず、それがたとえば整数やリストであれば、そこで
      は新たな名前空間は導入されません。

   get_namespaces()

      この名前に束縛された名前空間のリストを返します。

   get_namespace()

      この名前に束縛された名前空間を返します。この名前に束縛された名前
      空間が複数あるか一つもないなら "ValueError" が送出されます。


コマンドラインからの使用
========================

Added in version 3.13.

The "symtable" module can be executed as a script from the command
line.

   python -m symtable [infile...]

Symbol tables are generated for the specified Python source files and
dumped to stdout. If no input file is specified, the content is read
from stdin.
