# 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.

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)

  Add a collection of modules to the table of built-in modules. The newtab array must end with a sentinel entry which contains `NULL` for the `name` field; failure to provide the sentinel value can result in a memory fault. Returns `0` on success or `-1` if insufficient memory could be allocated to extend the internal table. In the event of failure, no modules are added to the internal table. This must be called before `Py_Initialize()`.

  If Python is initialized multiple times, `PyImport_AppendInittab()` or `PyImport_ExtendInittab()` must be called before each Python initialization.