"types" --- Creación de tipos dinámicos y nombres para tipos integrados
***********************************************************************

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

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

Este módulo define funciones de utilidad para ayudar en la creación
dinámica de tipos nuevos.

Este también define nombres para algunos tipos de objetos que son
utilizados por el intérprete estándar de Python, pero no expuestos
como integrados como lo son "int" o "str".

Por último, este proporciona algunas clases de utilidad y funciones
adicionales relacionadas con tipos que no son lo suficientemente
fundamentales como para ser integradas.


Creación dinámica de tipos
==========================

types.new_class(name, bases=(), kwds=None, exec_body=None)

   Crea un objeto de clase dinámicamente utilizando la metaclase
   adecuada.

   Los tres primeros argumentos son los componentes que componen un
   encabezado de definición de clase: el nombre de la clase, las
   clases base (en orden), los argumentos por palabra clave (tal como
   "metaclass").

   The *exec_body* argument is a callback that is used to populate the
   freshly created class namespace. It should accept the class
   namespace as its sole argument and update the namespace directly
   with the class contents. If no callback is provided, it has the
   same effect as passing in "lambda ns: None".

   Nuevo en la versión 3.3.

types.prepare_class(name, bases=(), kwds=None)

   Calcula la metaclase adecuada y crea el espacio de nombre de clase.

   Los argumentos son los componentes que constituyen un encabezado de
   definición de clase: el nombre de la clase, las clases base (en
   orden) y los argumentos de palabra clave (como "metaclass").

   El valor retornado es una tupla de 3: "metaclass, namespace, kwds"

   *metaclass* es la metaclase adecuada, *namespace* es el espacio de
   nombre de clase preparado y *kwds* es una copia actualizada del
   pasado en el argumento *kwds* con cualquier entrada "'metaclass'"
   eliminada. Si no se pasa ningún argumento *kwds*, será un
   diccionario vacío.

   Nuevo en la versión 3.3.

   Distinto en la versión 3.6: El valor predeterminado para el
   elemento "namespace" de la tupla retornada ha cambiado.  Ahora una
   asignación de inserción-orden-conservación es utilizada cuando la
   metaclase no tiene un método "__prepare__".

Ver también:

  Metaclases
     Detalles completos del proceso de creación de clases soportado
     por estas funciones

  **PEP 3115** - Metaclases en Python 3000
     Se presenta el *hook* de espacio de nombres "__prepare__"

types.resolve_bases(bases)

   Resuelve las entradas MRO dinámicamente según lo especificado por
   **PEP 560**.

   Esta función busca elementos en *bases* que no son instancias de
   "type" y retorna una tupla donde cada uno de estos objetos que
   tiene un método "__mro_entries__" se reemplaza con un resultado
   desempaquetado de llamar a este método.  Si un elemento *bases* es
   una instancia de "type" o no tiene un método "__mro_entries__", se
   incluye en el retorno la tupla sin cambios.

   Nuevo en la versión 3.7.

Ver también:

  **PEP 560** - Soporte principal para módulos de tipo y tipos
  genéricos


Tipos de Intérpretes Estándar
=============================

Este módulo proporciona nombres para muchos de los tipos necesarios
para implementar un intérprete de Python. Esto evita deliberadamente
incluir algunos de los tipos que surgen sólo accidentalmente durante
el procesamiento, tal como el tipo "listiterator".

El uso típico de estos nombres es para verificar "isinstance()" o
"issubclass()".

Si se crea una instancia de cualquiera de estos tipos, tenga en cuenta
que las firmas pueden variar entre las versiones de Python.

Los nombres estándar son definidos para los siguientes tipos:

types.FunctionType
types.LambdaType

   El tipo de funciones definidas por el usuario y funciones creadas
   por expresiones  "lambda".

   Lanza un auditing event "function.__new__" con el argumento "code".

   El evento auditor solo ocurre para la instanciación directa de
   objetos de código y no se genera para la compilación normal.

types.GeneratorType

   El tipo de iterador *generator* de objetos, creados por funciones
   generadoras.

types.CoroutineType

   El tipo de objetos *coroutine*, creados por funciones "async def".

   Nuevo en la versión 3.5.

types.AsyncGeneratorType

   El tipo de iterador *asynchronous generator* de objetos, creados
   por funciones generadoras asíncronas.

   Nuevo en la versión 3.6.

class types.CodeType(**kwargs)

   El tipo de objetos de código cómo los retornados por "compile()".

   Lanza un evento auditor "code.__new__" con los argumentos "code",
   "filename", "name", "argcount", "posonlyargcount",
   "kwonlyargcount", "nlocals", "stacksize", "flags".

   Tenga en cuenta que los argumentos auditados pueden no coincidir
   con los nombres o posiciones requeridos por el inicializador. El
   evento auditor solo ocurre para la instanciación directa de objetos
   de código y no se genera para la compilación normal.

   replace(**kwargs)

      Retorna una copia del objeto de código con nuevos valores para
      los campos especificados.

      Nuevo en la versión 3.8.

types.CellType

   El tipo de objetos de celda: estos objetos se utilizan como
   contenedores para las variables libres de una función.

   Nuevo en la versión 3.8.

types.MethodType

   El tipo de métodos de instancias de clase definidas por el usuario.

types.BuiltinFunctionType
types.BuiltinMethodType

   El tipo de funciones integradas como "len()" o "sys.exit()" y
   métodos de clases integradas.  (Aquí, el término "incorporado"
   significa "escrito en C".)

types.WrapperDescriptorType

   El tipo de métodos de algunos tipos de datos integrados y clases
   base como "object.__init__()" o "object.__lt__()".

   Nuevo en la versión 3.7.

types.MethodWrapperType

   El tipo de métodos *bound* de algunos tipos de datos integrados y
   clases base. Por ejemplo, es el tipo de "object().__str__".

   Nuevo en la versión 3.7.

types.MethodDescriptorType

   El tipo de métodos de algunos tipos de datos integrados como
   "str.join()".

   Nuevo en la versión 3.7.

types.ClassMethodDescriptorType

   El tipo de métodos de clase *unbound* de algunos tipos de datos
   integrados como "dict.__dict__['fromkeys']".

   Nuevo en la versión 3.7.

class types.ModuleType(name, doc=None)

   The type of *modules*. The constructor takes the name of the module
   to be created and optionally its *docstring*.

   Nota:

     Utilice "importlib.util.module_from_spec()" para crear un nuevo
     módulo si desea establecer los diversos atributos controlados por
     importación.

   __doc__

      El *docstring* del módulo. El valor predeterminado es "None".

   __loader__

      El *loader* que cargó el módulo. El valor predeterminado es
      "None".

      This attribute is to match
      "importlib.machinery.ModuleSpec.loader" as stored in the
      attr:*__spec__* object.

      Nota:

        A future version of Python may stop setting this attribute by
        default. To guard against this potential change, preferably
        read from the "__spec__" attribute instead or use
        "getattr(module, "__loader__", None)" if you explicitly need
        to use this attribute.

      Distinto en la versión 3.4: El valor predeterminado es "None".
      Anteriormente el atributo era opcional.

   __name__

      The name of the module. Expected to match
      "importlib.machinery.ModuleSpec.name".

   __package__

      A cuál *package* pertenece un módulo. Si el módulo es de nivel
      superior (es decir, no una parte de algún paquete específico),
      el atributo debe establecerse en "''", de lo contrario debe
      establecerse en el nombre del paquete (el cual puede ser
      "__name__" si el módulo es un paquete). El valor predeterminado
      es "None".

      This attribute is to match
      "importlib.machinery.ModuleSpec.parent" as stored in the
      attr:*__spec__* object.

      Nota:

        A future version of Python may stop setting this attribute by
        default. To guard against this potential change, preferably
        read from the "__spec__" attribute instead or use
        "getattr(module, "__package__", None)" if you explicitly need
        to use this attribute.

      Distinto en la versión 3.4: El valor predeterminado es "None".
      Anteriormente el atributo era opcional.

   __spec__

      A record of the module's import-system-related state. Expected
      to be an instance of "importlib.machinery.ModuleSpec".

      Nuevo en la versión 3.4.

class types.GenericAlias(t_origin, t_args)

   El tipo de parameterized generics como "list[int]".

   "t_origin" debería ser una clase genérica no parametrizada, como
   "list", "tuple" o "dict". "t_args" debe ser una "tuple"
   (posiblemente de longitud 1) de tipos que parametriza "t_origin":

      >>> from types import GenericAlias

      >>> list[int] == GenericAlias(list, (int,))
      True
      >>> dict[str, int] == GenericAlias(dict, (str, int))
      True

   Nuevo en la versión 3.9.

   Distinto en la versión 3.9.2: Este tipo ahora puede tener subclases

class types.TracebackType(tb_next, tb_frame, tb_lasti, tb_lineno)

   El tipo de objetos *traceback* tal como los encontrados en
   "sys.exc_info()[2]".

   Consulte la referencia de lenguaje para obtener detalles de los
   atributos y operaciones disponibles, y orientación sobre cómo crear
   *tracebacks* dinámicamente.

types.FrameType

   El tipo de objetos de marco como se encuentra en "tb.tb_frame" si
   "tb" es un objeto *traceback*.

   Consulte la referencia de lenguaje para obtener más información
   sobre los atributos y operaciones disponibles.

types.GetSetDescriptorType

   El tipo de objetos definidos en módulos de extensión con
   "PyGetSetDef", como "FrameType.f_locals" o "array.array.typecode".
   Este tipo se utiliza como descriptor para los atributos de objeto;
   tiene el mismo propósito que el tipo "property", pero para las
   clases definidas en los módulos de extensión.

types.MemberDescriptorType

   El tipo de objetos definidos en módulos de extensión con
   "PyMemberDef", como "datetime.timedelta.days".  Este tipo se
   utiliza como descriptor para miembros de datos C simples que
   utilizan funciones de conversión estándar; tiene el mismo propósito
   que el tipo "property", pero para las clases definidas en los
   módulos de extensión.

   **CPython implementation detail:** En otras implementaciones de
   Python, este tipo puede ser idéntico a "GetSetDescriptorType".

class types.MappingProxyType(mapping)

   Proxy de solo lectura de un mapeo. Proporciona una vista dinámica
   en las entradas de la asignación, lo que significa que cuando
   cambia la asignación, la vista refleja estos cambios.

   Nuevo en la versión 3.3.

   Distinto en la versión 3.9: Actualizado para soportar el nuevo
   operador de unión ("|") de **PEP 584**, que simplemente delega al
   mapeo subyacente.

   key in proxy

      Retorna "True" si la asignación subyacente tiene una clave
      *key*, de lo contrario "False".

   proxy[key]

      Retorna el elemento de la asignación subyacente con la clave
      *key*.  Lanza un "KeyError" si *key* no está en la asignación
      subyacente.

   iter(proxy)

      Retorna un iterador sobre las claves de la asignación
      subyacente.  Este es un método abreviado para
      "iter(proxy.keys())".

   len(proxy)

      Retorna el número de elementos de la asignación subyacente.

   copy()

      Retorna una copia superficial de la asignación subyacente.

   get(key[, default])

      Retorna el valor de *key* si *key* está en la asignación
      subyacente, de lo contrario *default*.  Si no se proporciona
      *default*, el valor predeterminado es "None", por lo que este
      método nunca lanza un "KeyError".

   items()

      Retorna una nueva vista de los elementos de la asignación
      subyacente (en pares "(key, value)").

   keys()

      Retorna una nueva vista de las claves de la asignación
      subyacente.

   values()

      Retorna una nueva vista de los valores de la asignación
      subyacente.

   reversed(proxy)

      Retorna un iterador inverso sobre las claves de la asignación
      subyacente.

      Nuevo en la versión 3.9.


Clases y funciones de utilidad adicionales
==========================================

class types.SimpleNamespace

   Una subclase simple "object" que proporciona acceso de atributo a
   su espacio de nombre, así como una representación significativa.

   A diferencia de "object", con "SimpleNamespace" puede agregar y
   eliminar atributos.  Si un objeto "SimpleNamespace" se inicializa
   con argumentos de palabra clave, estos se agregan directamente al
   espacio de nombres subyacente.

   El tipo es aproximadamente equivalente al código siguiente:

      class SimpleNamespace:
          def __init__(self, /, **kwargs):
              self.__dict__.update(kwargs)

          def __repr__(self):
              items = (f"{k}={v!r}" for k, v in self.__dict__.items())
              return "{}({})".format(type(self).__name__, ", ".join(items))

          def __eq__(self, other):
              if isinstance(self, SimpleNamespace) and isinstance(other, SimpleNamespace):
                 return self.__dict__ == other.__dict__
              return NotImplemented

   "SimpleNamespace" puede ser útil como reemplazo para "class NS:
   pass". Sin embargo, para un tipo de registro estructurado, utilice
   "namedtuple()" en su lugar.

   Nuevo en la versión 3.3.

   Distinto en la versión 3.9: El orden de los atributos en el *repr*
   cambió de alfabético a orden de inserción (como "dict").

types.DynamicClassAttribute(fget=None, fset=None, fdel=None, doc=None)

   Acceso de atributo de ruta en una clase para __getattr__.

   Se trata de un descriptor, que se utiliza para definir atributos
   que actúan de forma diferente cuando se accede a través de una
   instancia y a través de una clase.  El acceso a la instancia sigue
   siendo normal, pero el acceso a un atributo a través de una clase
   se enrutará al método __getattr__ de la clase; esto se hace
   lanzando AttributeError.

   Esto permite tener propiedades activas en una instancia y tener
   atributos virtuales en la clase con el mismo nombre (véase
   "enum.Enum" para obtener un ejemplo).

   Nuevo en la versión 3.4.


Funciones de utilidad de corutina
=================================

types.coroutine(gen_func)

   Esta función transforma una función *generador* en una función
   *coroutine* que retorna una corrutina basada en un generador. La
   corrutina basada en un generador sigue siendo un *generator
   iterator*, pero también se considera un objeto *coroutine* y es
   *awaitable*.  Sin embargo, no puede necesariamente implementar el
   método "__await__()".

   Si *gen_func* es una función generadora, se modificará en el lugar.

   Si *gen_func* no es una función generadora, se envolverá. Si
   retorna una instancia de "collections.abc.Generator", la instancia
   se ajustará en un objeto proxy *awaitable*.  Todos los demás tipos
   de objetos se retornarán tal cual.

   Nuevo en la versión 3.5.
