Importando Módulos
******************

PyObject* PyImport_ImportModule(const char *name)
    *Return value: New reference.*

   Esta es una interfaz simplificada para "PyImport_ImportModuleEx()"
   a continuación, dejando los argumentos *globals* y *locals*
   establecidos en "NULL" y *level* establecidos en 0. Cuando el
   argumento *name* contiene un punto (cuando especifica un submódulo
   de un paquete), el argumento *fromlist* se establece en la lista
   "['*']" para que el valor de retorno sea el módulo con nombre en
   lugar del paquete de nivel superior que lo contiene como lo haría
   de lo contrario sea el caso. (Desafortunadamente, esto tiene un
   efecto secundario adicional cuando *name* de hecho especifica un
   subpaquete en lugar de un submódulo: los submódulos especificados
   en la variable "__all__" del paquete están cargados). Retorna una
   nueva referencia al módulo importado, o "NULL" con una excepción
   establecida en caso de error. Una importación fallida de un módulo
   no deja el módulo en "sys.modules".

   Esta función siempre usa importaciones absolutas.

PyObject* PyImport_ImportModuleNoBlock(const char *name)
    *Return value: New reference.*

   Esta función es un alias obsoleto de "PyImport_ImportModule()".

   Distinto en la versión 3.3: Esta función solía fallar
   inmediatamente cuando el bloqueo de importación era retenido por
   otro hilo. Sin embargo, en Python 3.3, el esquema de bloqueo cambió
   a bloqueos por módulo para la mayoría de los propósitos, por lo que
   el comportamiento especial de esta función ya no es necesario.

PyObject* PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
    *Return value: New reference.*

   Importa un módulo. Esto se describe mejor haciendo referencia a la
   función Python incorporada "__import__()".

   El valor de retorno es una nueva referencia al módulo importado o
   paquete de nivel superior, o "NULL" con una excepción establecida
   en caso de error. Al igual que para "__import__()", el valor de
   retorno cuando se solicitó un submódulo de un paquete normalmente
   es el paquete de nivel superior, a menos que se proporcione un
   *fromlist* no vacío.

   Las importaciones que fallan eliminan objetos de módulo
   incompletos, como con "PyImport_ImportModule()".

PyObject* PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
    *Return value: New reference.*

   Importa un módulo. Esto se describe mejor haciendo referencia a la
   función Python incorporada "__import__()", ya que la función
   estándar "__import__()" llama a esta función directamente.

   El valor de retorno es una nueva referencia al módulo importado o
   paquete de nivel superior, o "NULL" con una excepción establecida
   en caso de error. Al igual que para "__import__()", el valor de
   retorno cuando se solicitó un submódulo de un paquete normalmente
   es el paquete de nivel superior, a menos que se proporcione un
   *fromlist* no vacío.

   Nuevo en la versión 3.3.

PyObject* PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
    *Return value: New reference.*

   Similar a "PyImport_ImportModuleLevelObject()", pero el nombre es
   una cadena de caracteres codificada UTF-8 en lugar de un objeto
   Unicode.

   Distinto en la versión 3.3: Los valores negativos para *level* ya
   no se aceptan.

PyObject* PyImport_Import(PyObject *name)
    *Return value: New reference.*

   Esta es una interfaz de nivel superior que llama a la "función de
   enlace de importación" actual (con un nivel explícito de 0, que
   significa importación absoluta). Invoca la función "__import__()"
   de las "__builtins__" de los globales (*globals*) actuales. Esto
   significa que la importación se realiza utilizando los ganchos de
   importación instalados en el entorno actual.

   Esta función siempre usa importaciones absolutas.

PyObject* PyImport_ReloadModule(PyObject *m)
    *Return value: New reference.*

   Recarga un módulo. Retorna una nueva referencia al módulo
   recargado, o "NULL" con una excepción establecida en caso de error
   (el módulo todavía existe en este caso).

PyObject* PyImport_AddModuleObject(PyObject *name)
    *Return value: Borrowed reference.*

   Retorna el objeto módulo correspondiente a un nombre de módulo. El
   argumento *name* puede tener la forma "package.module". Primero
   revise el diccionario de módulos si hay uno allí, y si no, crea uno
   nuevo y lo agrega al diccionario de módulos. Retorna "NULL" con una
   excepción establecida en caso de error.

   Nota:

     Esta función no carga ni importa el módulo; si el módulo no
     estaba cargado, obtendrá un objeto de módulo vacío. Utilice
     "PyImport_ImportModule()" o una de sus variantes para importar un
     módulo. Las estructuras de paquete implicadas por un nombre
     punteado para *name* no se crean si aún no están presentes.

   Nuevo en la versión 3.3.

PyObject* PyImport_AddModule(const char *name)
    *Return value: Borrowed reference.*

   Similar a "PyImport_AddModuleObject()", pero el nombre es una
   cadena de caracteres codificada UTF-8 en lugar de un objeto
   Unicode.

PyObject* PyImport_ExecCodeModule(const char *name, PyObject *co)
    *Return value: New reference.*

   Dado un nombre de módulo (posiblemente de la forma
   "package.module") y un objeto código leído desde un archivo de
   *bytecode* de Python u obtenido de la función incorporada
   "compile()", carga el módulo. Retorna una nueva referencia al
   objeto módulo, o "NULL" con una excepción establecida si se produjo
   un error. *name* se elimina de "sys.modules" en casos de error,
   incluso si *name* ya estaba en "sys.modules" en la entrada a
   "PyImport_ExecCodeModule()". Dejar módulos inicializados de forma
   incompleta en "sys.modules" es peligroso, ya que las importaciones
   de dichos módulos no tienen forma de saber que el objeto del módulo
   es un estado desconocido (y probablemente dañado con respecto a las
   intenciones del autor del módulo).

   Los módulos "__spec__" y "__loader__" se establecerán, si no se han
   configurado ya, con los valores apropiados. El cargador de la
   especificación se establecerá en el módulo "__loader__" (si está
   configurado) y en una instancia de "SourceFileLoader" de lo
   contrario.

   El atributo del módulo "__file__" se establecerá en el objeto
   código "co_filename". Si corresponde, también se establecerá
   "__cached__".

   Esta función volverá a cargar el módulo si ya se importó. Consulte
   "PyImport_ReloadModule()" para conocer la forma prevista de volver
   a cargar un módulo.

   Si *name* apunta a un nombre punteado de la forma "package.module",
   cualquier estructura de paquete que no se haya creado aún no se
   creará.

   Ver también "PyImport_ExecCodeModuleEx()" y
   "PyImport_ExecCodeModuleWithPathnames()".

PyObject* PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)
    *Return value: New reference.*

   Como "PyImport_ExecCodeModule()", pero el atributo "__file__" del
   objeto del módulo se establece en *pathname* si no es "NULL".

   Ver también "PyImport_ExecCodeModuleWithPathnames()".

PyObject* PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)
    *Return value: New reference.*

   Como "PyImport_ExecCodeModuleEx()", pero el atributo "__cached__"
   del objeto módulo se establece en *cpathname* si no es "NULL". De
   las tres funciones, esta es la recomendada para usar.

   Nuevo en la versión 3.3.

PyObject* PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)
    *Return value: New reference.*

   Como "PyImport_ExecCodeModuleObject()", pero *name*, *pathname* y
   *cpathname* son cadenas de caracteres codificadas UTF-8. También se
   intenta averiguar cuál debe ser el valor de *pathname* de
   *cpathname* si el primero se establece en "NULL".

   Nuevo en la versión 3.2.

   Distinto en la versión 3.3: Utiliza "imp.source_from_cache()" para
   calcular la ruta de origen si solo se proporciona la ruta del
   *bytecode*.

long PyImport_GetMagicNumber()

   Retorna el número mágico para los archivos de *bytecode* de Python
   (también conocido como archivos ".pyc"). El número mágico debe
   estar presente en los primeros cuatro bytes del archivo de código
   de bytes, en orden de bytes *little-endian*. Retorna "-1" en caso
   de error.

   Distinto en la versión 3.3: Retorna un valor de "-1" en caso de
   error.

const char * PyImport_GetMagicTag()

   Retorna la cadena de caracteres de etiqueta mágica para nombres de
   archivo de código de bytes Python en formato **PEP 3147**. Tenga en
   cuenta que el valor en "sys.implementation.cache_tag" es
   autoritario y debe usarse en lugar de esta función.

   Nuevo en la versión 3.2.

PyObject* PyImport_GetModuleDict()
    *Return value: Borrowed reference.*

   Retorna el diccionario utilizado para la administración del módulo
   (también conocido como "sys.modules"). Tenga en cuenta que esta es
   una variable por intérprete.

PyObject* PyImport_GetModule(PyObject *name)
    *Return value: New reference.*

   Retorna el módulo ya importado con el nombre dado. Si el módulo aún
   no se ha importado, retorna "NULL" pero no establece un error.
   Retorna "NULL" y establece un error si falla la búsqueda.

   Nuevo en la versión 3.7.

PyObject* PyImport_GetImporter(PyObject *path)
    *Return value: New reference.*

   Retorna un objeto buscador para un elemento *path*
   "sys.path"/"pkg.__path__", posiblemente obteniéndolo del
   diccionario "sys.path_importer_cache". Si aún no estaba en caché,
   atraviesa "sys.path_hooks" hasta que se encuentre un gancho
   (*hook*) que pueda manejar el elemento de ruta. Retorna "None" si
   ningún gancho podría; esto le dice a la persona que llama que *path
   based finder* no pudo encontrar un buscador para este elemento de
   ruta. Guarda en el resultado (caché) en "sys.path_importer_cache".
   Retorna una nueva referencia al objeto del buscador.

void _PyImport_Init()

   Inicializa el mecanismo de importación. Sólo para uso interno.

void PyImport_Cleanup()

   Vacía la tabla del módulo (*module table*). Sólo para uso interno.

void _PyImport_Fini()

   Finaliza el mecanismo de importación. Sólo para uso interno.

int PyImport_ImportFrozenModuleObject(PyObject *name)
    *Return value: New reference.*

   Carga un módulo congelado llamado *name*. Retorna "1" para el
   éxito, "0" si no se encuentra el módulo y "-1" con una excepción
   establecida si falla la inicialización. Para acceder al módulo
   importado con una carga exitosa, use "PyImport_ImportModule()".
   (Tenga en cuenta el nombre inapropiado --- esta función volvería a
   cargar el módulo si ya se importó).

   Nuevo en la versión 3.3.

   Distinto en la versión 3.4: El atributo "__file__" ya no está
   establecido en el módulo.

int PyImport_ImportFrozenModule(const char *name)

   Similar a "PyImport_ImportFrozenModuleObject()", pero el nombre es
   una cadena de caracteres codificada UTF-8 en lugar de un objeto
   Unicode.

struct _frozen

   Esta es la definición del tipo de estructura para los descriptores
   de módulos congelados, según lo generado con la herramienta
   **freeze** (ver "Tools/freeze" en la distribución de código fuente
   de Python). Su definición, que se encuentra en "Include/import.h",
   es:

      struct _frozen {
          const char *name;
          const unsigned char *code;
          int size;
      };

const struct _frozen* PyImport_FrozenModules

   Este puntero se inicializa para apuntar a un arreglo de registros
   "struct _frozen", terminado por uno cuyos miembros son todos "NULL"
   o cero. Cuando se importa un módulo congelado, se busca en esta
   tabla. El código de terceros podría jugar trucos con esto para
   proporcionar una colección de módulos congelados creada
   dinámicamente.

int PyImport_AppendInittab(const char *name, PyObject* (*initfunc)(void))

   Agrega un solo módulo a la tabla existente de módulos incorporados.
   Este es un contenedor conveniente "PyImport_ExtendInittab()", que
   retorna "-1" si la tabla no se puede extender. El nuevo módulo se
   puede importar con el nombre *name*, y utiliza la función
   *initfunc* como la función de inicialización llamada en el primer
   intento de importación. Esto debería llamarse antes de
   "Py_Initialize()".

struct _inittab

   Estructura que describe una sola entrada en la lista de módulos
   incorporados. Cada una de estas estructuras proporciona el nombre y
   la función de inicialización de un módulo incorporado en el
   intérprete. El nombre es una cadena de caracteres codificada ASCII.
   Los programas que incorporan Python pueden usar una matriz de estas
   estructuras junto con "PyImport_ExtendInittab()" para proporcionar
   módulos integrados adicionales. La estructura se define en
   "Include/import.h" como:

      struct _inittab {
          const char *name;           /* ASCII encoded string */
          PyObject* (*initfunc)(void);
      };

int PyImport_ExtendInittab(struct _inittab *newtab)

   Agrega una colección de módulos a la tabla de módulos integrados.
   El arreglo *newtab* debe terminar con una entrada centinela que
   contiene "NULL" para el campo "name"; Si no se proporciona el valor
   centinela, se puede producir un error de memoria. Retorna "0" en
   caso de éxito o "-1" si se puede asignar memoria insuficiente para
   ampliar la tabla interna. En caso de error, no se agregan módulos a
   la tabla interna. Esto debería llamarse antes de "Py_Initialize()".
