zipapp — Gestiona archivadores zip ejecutables de Python

Nuevo en la versión 3.5.

Código fuente: Lib/zipapp.py

Este módulo provee herramientas para administrar la creación de archivos zip que contengan código Python, los que pueden ser ejecutados directamente por el intérprete de Python. El módulo provee tanto una Interfaz de línea de comando y una API de Python.

Ejemplo básico

El siguiente ejemplo muestra cómo la Interfaz de línea de comando puede utilizarse para crear un archivador ejecutable de un directorio que contenga código en Python. Al ponerse en funcionamiento, el archivador ejecutará la función main del módulo myapp en el archivador.

$ python -m zipapp myapp -m "myapp:main"
$ python myapp.pyz
<output from myapp>

Interfaz de línea de comando

En la ejecución como programa desde la línea de comandos, se utiliza el siguiente formato:

$ python -m zipapp source [options]

Si source es un directorio, se creará un archivador zip para los contenidos de source. Si source es un archivo, debería ser un archivador, y se copiará al archivador de destino (o los contenidos de su línea shebang se mostrarán si se especifica la opción –info).

Se aceptan las siguientes opciones:

-o <output>, --output=<output>

Escribe la salida a un archivo llamado output. Si esta opción no está especificada, el nombre del archivo de salida será el mismo que la entrada source, con la extensión .pyz agregada. Si se provee de un nombre de archivo explícito, se usa tal como está (por lo que una extensión .pyz debería incluirse si esto se requiere).

Un nombre de archivo de salida debe especificarse si source es un archivador (y en ese caso, output no debería ser igual que source).

-p <interpreter>, --python=<interpreter>

Agrega una línea #! al archivador especificando interpreter como comando a ejecutar. También en POSIX, convierte al archivador en ejecutable. La opción por defecto es no escribir una línea #!, y no hacer que el archivo sea ejecutable.

-m <mainfn>, --main=<mainfn>

Escribe un archivo __main__.py en el archivador que ejecuta mainfn. El argumento mainfn debería tener la forma «pkg.mod:fn», donde «pkg.mod» is un paquete/módulo en el archivador, y «fn» es un invocable (callable) en ese módulo. El archivo __main__.py ejecutará ese invocable.

--main no puede especificarse al copiar un archivador.

-c, --compress

Comprime los archivos con el método deflate, lo que reduce el tamaño del archivo de salida. Por defecto, los archivos se guardan sin comprimir en el archivador.

--compress no surte efecto al copiar un archivador.

Nuevo en la versión 3.7.

--info

Muestra el intérprete incrustado en el archivador, para diagnósticos. En este caso cualquier otra opción se ignora, y SOURCE debe ser un archivador, no un directorio.

-h, --help

Muestra un breve mensaje sobre el modo de uso, y sale.

API de Python

El módulo define dos funciones convenientes:

zipapp.create_archive(source, target=None, interpreter=None, main=None, filter=None, compressed=False)

Crea un archivador de aplicación a partir de source. Este source (origen), puede ser cualquiera de los siguientes:

  • El nombre de un directorio, o un path-like object que se refiera a un directorio, en cuyo caso un nuevo archivador de aplicación se creará a partir del contenido de dicho directorio.

  • El nombre de un archivador de aplicación existente o un path-like object que refiera a dicho archivo, en cuyo caso el archivo se copiará al destino (modificándolo para reflejar el valor dado por el argumento interpreter. El nombre de archivo debería incluir la extensión .pyz, si se requiere.

  • Un objeto archivo abierto para lectura en modo bytes. El contenido del archivo debería ser un archivador de aplicación. Se infiere que el objeto archivo está posicionado al comienzo del archivador.

El argumento target determina dónde quedará escrito el archivador resultante:

  • Si es el nombre de un archivo, o un path-like object, el archivador será escrito a ese archivo.

  • Si es un objeto archivo abierto, el archivador se escribirá en ese objeto archivo, el cual debe estar abierto para escritura en modo bytes.

  • Si el destino (target) se omite (o es None), el origen (source) debe ser un directorio, y el destino será un archivo con el mismo nombre que el origen, con la extensión .pyz añadida.

El argumento interpreter especifica el nombre del intérprete Python con el que el archivador será ejecutado. Se escribe como una línea «shebang» al comienzo del archivador. En POSIX, el Sistema Operativo será quien lo interprete, y en Windows será gestionado por el lanzador Python. Omitir el interpreter tendrá como consecuencia que no se escribirá ninguna línea shebang. Si se especifica un intérprete y el destino (target) es un nombre de archivo, el bit de ejecución del archivo destino será activado.

El argumento main especifica el nombre de un invocable (callable) que se utilizará como programa principal para el archivador. Solamente se puede especificar si el origen (source) es un directorio que no contiene un archivo __main__.py. El argumento main debería tener la forma «pkg.module:callable», y el archivador será ejecutado importando «pkg.module» y ejecutando el callable sin argumentos. Es un error omitir main si el origen es un directorio que no contiene un archivo __main__.py, ya que esto resultaría en un archivador no ejecutable.

El argumento opcional filter especifica una función callback que se pasa como objeto Path, para representar el path (ruta) al archivo que se está añadiendo (ruta relativa al directorio origen, source). Debería retornar True si el archivo será añadido.

El argumento opcional compressed determina si los archivos están comprimidos. Si se define como True, los archivos en el archivador serán comprimidos con el método deflate.

Si se especifica un objeto archivo para source o * target*, es responsabilidad de quien invoca cerrarlo luego de invocar a create_archive.

Al copiar un archivador existente, los objetos archivo provistos, solamente necesitan los métodos read y readline, o bien write. Al crear un archivador a partir de un directorio, si el destino (target) es un objeto archivo, éste se pasará a la clase zipfile.ZipFile, y debe proveer los métodos que esa clase necesita.

Nuevo en la versión 3.7: Añadidos los argumentos filter y compressed.

zipapp.get_interpreter(archive)

Retorna el intérprete especificado en la línea #! al comienzo del archivador. Si no hay línea #!, retorna None. El argumento archive (archivador), puede ser un nombre de archivo o un objeto tipo archivo abierto para lectura en modo bytes. Se supone que está al principio del archivador.

Ejemplos

Empaqueta un directorio en un archivador, y lo ejecuta.

$ python -m zipapp myapp
$ python myapp.pyz
<output from myapp>

Lo mismo puede lograrse utilizando la función create_archive():

>>> import zipapp
>>> zipapp.create_archive('myapp', 'myapp.pyz')

Para que la aplicación sea ejecutable directamente en POSIX, especifica un intérprete.

$ python -m zipapp myapp -p "/usr/bin/env python"
$ ./myapp.pyz
<output from myapp>

Para reemplazar la línea shebang en un archivador existente, cree un archivador modificado, utilizando la función create_archive():

>>> import zipapp
>>> zipapp.create_archive('old_archive.pyz', 'new_archive.pyz', '/usr/bin/python3')

Para actualizar el archivo en el lugar, reemplaza en memoria utilizando un objeto BytesIO, y luego sobreescribe el origen (source). Nótese que hay un riesgo al sobreescribir un archivo en el lugar, ya que un error resultará en la pérdida del archivo original. Este código no ofrece protección contra este tipo de errores, sino que el código de producción debería hacerlo. Además, este método solamente funcionará si el archivador cabe en la memoria:

>>> import zipapp
>>> import io
>>> temp = io.BytesIO()
>>> zipapp.create_archive('myapp.pyz', temp, '/usr/bin/python2')
>>> with open('myapp.pyz', 'wb') as f:
>>>     f.write(temp.getvalue())

Especificar el intérprete

Nótese que si se especifica el intérprete y luego se distribuye el archivador de aplicación, es necesario asegurarse de que el intérprete utilizado es portable. El lanzador Python para Windows soporta las formas más comunes de líneas #! POSIX, pero hay otras cuestiones a considerar:

  • Si se utiliza «/usr/bin/env python» (u otras formas del comando «python», como «/usr/bin/python»), es necesario considerar que los usuarios quizá tengan tanto Python2 como Python3 como versión por defecto, y el código debe escribirse bajo ambas versiones.

  • Si se utiliza una versión específica, por ejemplo «/usr/bin/env python3», la aplicación no funcionará para los usuarios que no tengan esa versión. (Esta puede ser la opción deseada si no se hecho el código compatible con Python 2).

  • No hay manera de decir «python X.Y o posterior», así que se debe ser cuidadoso al utilizar una versión exacta, tal como «/usr/bin/env python3.4», ya que será necesario cambiar la línea shebang para usuarios de Python 3.5, por ejemplo.

Normalmente, se debería utilizar «/usr/bin/env python2» o «/usr/bin/env python3», según si el código está escrito para Python 2 ó 3.

Creando aplicaciones independientes con zipapp

Utilizando el módulo zipapp, es posible crear programas Python auto-contenidos, que pueden ser distribuidos a usuarios finales que solo necesitarán una versión adecuada de Python instalada en sus sistemas. La clave es empaquetar todas las dependencias de la aplicación dentro del archivador, junto al código de la misma.

Los pasos para crear un archivador independiente son los siguientes:

  1. Crea tu aplicación en un directorio normalmente, tal que tengas una directorio myapp que contenga un archivo __main__.py, y cualquier código extra de la aplicación.

  2. Instala todas las dependencias de la aplicación en el directorio myapp, usando pip:

    $ python -m pip install -r requirements.txt --target myapp

    (se supone que tienes los requisitos de tu proyecto en un archivo requirements.txt, de lo contrario, puedes listar manualmente las dependencias en la línea de comandos de pip).

  3. Opcionalmente, borra los directorios .dist-info creados por pip en el directorio myapp. Éstos tienen metadatos para que pip gestione los paquetes, y como ya no se utilizará pip, no hace falta que permanezcan (aunque no causará ningún problema si los dejas).

  4. Empaqueta la aplicación utilizando:

    $ python -m zipapp -p "interpreter" myapp

Esto producirá un ejecutable independiente, que puede ser ejecutado en cualquier máquina que disponga del intérprete apropiado. Véase Especificar el intérprete para más detalles. Puede enviarse a los usuarios como un solo archivo.

En Unix, el archivo myapp.pyz será ejecutable tal como está. Puede ser renombrado, para quitar la extensión .pyz si se prefiere un nombre de comando «simple». En Windows, el archivo myapp.pyz[w] es ejecutable, ya que el intérprete Python registra las extensiones .pyz y pyzw al ser instalado.

Hacer un ejecutable para Windows

En Windows, registrar la extensión .pyz es opcional, y además hay ciertos sitios que no reconocen las extensiones registradas de manera «transparente» (el ejemplo más simple es que subprocess.run(['myapp']) no va a encontrar la aplicación, es necesario especificar explícitamente la extensión).

Por lo tanto, en Windows, suele ser preferible crear un ejecutable a partir del zipapp. Esto es relativamente fácil, aunque requiere un compilador de C. La estrategia básica se basa en que los archivos zip pueden tener datos arbitrarios antepuestos, y los archivos exe de Windows pueden tener datos arbitrarios agregados. Entonces, si se crea un lanzador adecuado mudando el archivo .pyz al final del mismo, se obtiene un solo archivo ejecutable que corre la aplicación.

Un lanzador adecuado puede ser así de simple:

#define Py_LIMITED_API 1
#include "Python.h"

#define WIN32_LEAN_AND_MEAN
#include <windows.h>

#ifdef WINDOWS
int WINAPI wWinMain(
    HINSTANCE hInstance,      /* handle to current instance */
    HINSTANCE hPrevInstance,  /* handle to previous instance */
    LPWSTR lpCmdLine,         /* pointer to command line */
    int nCmdShow              /* show state of window */
)
#else
int wmain()
#endif
{
    wchar_t **myargv = _alloca((__argc + 1) * sizeof(wchar_t*));
    myargv[0] = __wargv[0];
    memcpy(myargv + 1, __wargv, __argc * sizeof(wchar_t *));
    return Py_Main(__argc+1, myargv);
}

Si se define el símbolo de preprocesador WINDOWS, se generará una GUI (interfaz gráfica de usuario) ejecutable, y sin este símbolo, un ejecutable de consola.

Para compilar el ejecutable, se puede usar únicamente la línea de comando estándar MSVC, o se puede aprovechar la ventaja de que distutils sabe cómo compilar código fuente Python:

>>> from distutils.ccompiler import new_compiler
>>> import distutils.sysconfig
>>> import sys
>>> import os
>>> from pathlib import Path

>>> def compile(src):
>>>     src = Path(src)
>>>     cc = new_compiler()
>>>     exe = src.stem
>>>     cc.add_include_dir(distutils.sysconfig.get_python_inc())
>>>     cc.add_library_dir(os.path.join(sys.base_exec_prefix, 'libs'))
>>>     # First the CLI executable
>>>     objs = cc.compile([str(src)])
>>>     cc.link_executable(objs, exe)
>>>     # Now the GUI executable
>>>     cc.define_macro('WINDOWS')
>>>     objs = cc.compile([str(src)])
>>>     cc.link_executable(objs, exe + 'w')

>>> if __name__ == "__main__":
>>>     compile("zastub.c")

El lanzador resultante utiliza «Limited ABI», así que correrá sin cambios con cualquier versión de Python 3.x. Todo lo que necesita es que Python (python3.dll) esté en el PATH del usuario.

Para una distribución completamente independiente, se puede distribuir el lanzador con la aplicación incluida, empaquetada con la distribución «embedded» de Python. Va a funcionar en cualquier PC con la arquitectura adecuada (32 o 64 bits).

Advertencias

Hay algunas limitaciones para empaquetar la aplicación en un solo archivo. In la mayoría, si no en todos los casos, se pueden abordar sin que haga falta ningún cambio importante en la aplicación.

  1. Si la aplicación depende de un paquete que incluye una extensión C, ese paquete no puede ser ejecutado desde un archivo zip (esta es una limitación del sistema operativo, dado que el código ejecutable debe estar presente en el sistema de archivos para que el loader del SO lo pueda cargar). En este caso, se puede excluir la dependencia del archivo zip, y requerir que los usuarios la tengan instalada, o bien distribuirla conjuntamente con el archivo zip, y agregar código al __main__.py para que incluya el directorio que contiene el módulo descomprimido en sys.path. En este caso, será necesario asegurarse de distribuir los binarios adecuados para la/s arquitectura/s a las que esté destinada la aplicación (y potencialmente elegir la versión correcta para agregar a sys.path en tiempo de ejecución, basándose en la máquina del usuario).

  2. Al distribuir ejecutables Windows tal como se describe más arriba, hay que asegurarse de que los usuarios tienen python3.dll en su PATH (lo cual no es una opción por defecto en el instalador), o bien empaquetar la aplicación con la distribución embedded.

  3. El lanzador que se sugiere más arriba, utiliza la API de incrustación de Python (Python embedding API). Esto significa que sys.executable será la aplicación, y no el intérprete Python convencional. El código y sus dependencias deben estar preparados para esta posibilidad. Por ejemplo, si la aplicación utiliza el módulo multiprocessing, necesitará invocar a multiprocessing.set_executable() para permitir que el módulo sepa dónde encontrar el intérprete Python estándar.

El formato de archivado Zip de aplicaciones Python

Python puede ejecutar archivadores zip que contengan un archivo __main__.py desde la versión 2.6. Para que sea ejecutada por Python, basta con que una aplicación de archivador sea un archivo zip estándar que contenga un archivo __main__.py, el cual será ejecutado como punto de entrada para la aplicación. Como es usual para cualquier script Python, el elemento padre del script (en este caso, el archivo zip), será ubicado en sys.path, por lo que pueden importarse otros módulos desde el archivo zip.

El formato de archivo zip, permite que se antepongan al archivo datos arbitrarios. El formato de aplicación zip utiliza esta capacidad para anteponer una línea «shebang» POSIX estándar al archivo (#!/ruta/al/interprete).

Formalmente, el Formato de archivado Zip de aplicaciones Python es:

  1. Una línea shebang opcional, conteniendo los caracteres``b”#!”`` seguidos por un nombre de intérprete, y luego un carácter de nueva línea (b'\n'). El nombre del intérprete puede ser cualquiera que sea aceptable para el procesamiento de shebang del Sistema Operativo, o el lanzador Python en Windows. El intérprete debería estar codificado en UTF-8 en Windows, y en sys.getfilesystemencoding() en POSIX.

  2. Los datos estándares de archivo zip, tal como se generan en el módulo zipfile. El contenido del archivo zip debe incluir un archivo llamado __main__.py (que debe estar en la «raíz» del archivo zip, es decir, no puede estar en un subdirectorio). El los datos del archivo zip pueden estar comprimidos o no.

Si un archivador de aplicación tiene una línea de shebang, puede tener el bit de ejecución activado en los sistemas POSIX, para permitir que sea ejecutado directamente.

No se requiere que las herramientas de este módulo sean las que se utilicen para crear archivadores de aplicación. El módulo es útil, pero cualquier archivo que esté en el formato descripto anteriormente es aceptable para Python, no importa cómo haya sido creado.