"symtable" --- Access to the compiler's symbol tables
*****************************************************

**Código fuente:** Lib/symtable.py

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

Las tablas de símbolos son generadas por el compilador a partir del
AST justo antes de que el bytecode sea generado. La tabla de símbolos
es responsable de calcular el ámbito de cada identificador en el
código.  "symtable" provee una interfaz para examinar esas tablas.


Generando tablas de símbolos
============================

symtable.symtable(code, filename, compile_type)

   Retorna la "SymbolTable" del nivel más alto para el código Python
   *code*. *filename* es el nombre del archivo conteniendo el código.
   *compile_type* es como el argumento *mode* de la función
   "compile()".


Examinando la tabla de símbolos
===============================

class symtable.SymbolTable

   Un espacio de nombres para el bloque. El constructor no es público.

   get_type()

      Retorna el tipo de la tabla de símbolos.  Los valores posibles
      son "'class'", "'module'", "'function'", "'annotation'",
      "'TypeVar bound'", "'type alias'" y "'type parameter'". Los
      cuatro últimos se refieren a diferentes tipos de Ámbitos de
      anotación.

      Distinto en la versión 3.12: Se agregaron "'annotation'",
      "'TypeVar bound'", "'type alias'" y "'type parameter'" como
      posibles valores de retorno.

   get_id()

      Retorna el identificador de la tabla.

   get_name()

      Retorna el nombre de la tabla. Es el nombre de la clase si la
      tabla es para una clase, el nombre de la función si la tabla es
      para una función o "'top" si la tabla es global ("get_type()"
      retorna "'module"). Para ámbitos de parámetros de tipo (que se
      utilizan para clases genéricas, funciones y alias de tipo), es
      el nombre de la clase, función o alias de tipo subyacente. Para
      ámbitos de alias de tipo, es el nombre del alias de tipo. Para
      ámbitos enlazados "TypeVar", es el nombre del "TypeVar".

   get_lineno()

      Retorna el número de la primera línea en el bloque que esta
      tabla representa.

   is_optimized()

      Retorna "True" si los locales en esta tabla pueden ser
      optimizados.

   is_nested()

      Retorna "True" si el bloque es una clase o función anidadas.

   has_children()

      Retorna "True" si el bloque contiene espacios de nombres
      anidados en él. Estos pueden ser obtenidos con "get_children()".

   get_identifiers()

      Retorna una vista de objeto que contiene los nombres de los
      símbolos en la tabla. Lee la documentación de vistas de objetos.

   lookup(name)

      Busca *name* en la tabla y retorna una instancia de "Symbol".

   get_symbols()

      Retorna una lista de instancias de "Symbol" de los nombres en la
      tabla.

   get_children()

      Retorna una lista de las tablas de símbolos anidadas.

class symtable.Function

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

   get_parameters()

      Retorna una tupla conteniendo los nombres de los parámetros de
      esta función.

   get_locals()

      Retorna una tupla conteniendo los nombres de los locales en esta
      función.

   get_globals()

      Retorna una tupla conteniendo los nombres de los globales en
      esta función.

   get_nonlocals()

      Retorna una tupla conteniendo los nombres de los no locales en
      esta función.

   get_frees()

      Retorna una tupla conteniendo los nombres de las variables
      libres en esta función.

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()".

      For example:

      >>> 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()[1]
      >>> class_A.get_methods()
      ('f', 'g', 'h')

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

class symtable.Symbol

   Una entrada en una "SymbolTable" correspondiente a un identificador
   en el código. El constructor no es público.

   get_name()

      Retorna el nombre del símbolo.

   is_referenced()

      Retorna "True" si el símbolo es usado en su bloque.

   is_imported()

      Retorna "True" si el símbolo es creado desde una instrucción
      *import*.

   is_parameter()

      Retorna "True" si el símbolo es un parámetro.

   is_global()

      Retorna "True" si el símbolo es global.

   is_nonlocal()

      Retorna "True" si el símbolo es no local.

   is_declared_global()

      Retorna "True" si el símbolo es declarado global con una
      instrucción *global*.

   is_local()

      Retorna "True" si el símbolo es local a su bloque.

   is_annotated()

      Retorna "True" si el símbolo está anotado.

      Added in version 3.6.

   is_free()

      Retorna "True" si el símbolo es referenciado en su bloque pero
      no asignado.

   is_assigned()

      Retorna "True" si el símbolo es asignado en su bloque.

   is_namespace()

      Retorna "True" si la vinculación de nombres introduce un nuevo
      espacio de nombres.

      Si el nombre es usado como objetivo de una instrucción
      *function* o *class* retornará verdadero.

      Por ejemplo:

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

      Note que un solo nombre puede estar vinculado a varios objetos.
      Si el resultado es "True", el nombre puede estar vinculado
      también a otros objetos, como un entero o una lista, esto no
      introduce un nuevo espacio de nombres.

   get_namespaces()

      Retorna una lista de espacios de nombres vinculados a este
      nombre.

   get_namespace()

      Retorna el espacio de nombre vinculado a este nombre. Si hay más
      de un espacio de nombre vinculado o ninguno a ese nombre se
      levanta un "ValueError".
