py_compile` — Compila archivos fuente Python

Código fuente Lib/py_compile.py

El módulo py_compile provee una función para generar un archivo de código de bytes de un archivo fuente, y otra función usada cuando el módulo archivo fuente es invocado como un script.

Aunque no es necesario seguidamente, esta función puede ser útil cuando se instalan módulos para uso compartido, especialmente si algunos de los usuarios pueden no tener permisos para escribir el archivo caché de bytes en el directorio conteniendo el código fuente.

exception py_compile.PyCompileError

Cuando un error ocurre mientras se intenta compilar el archivo, se lanza una excepción.

py_compile.compile(file, cfile=None, dfile=None, doraise=False, optimize=-1, invalidation_mode=PycInvalidationMode.TIMESTAMP, quiet=0)

Compile a source file to byte-code and write out the byte-code cache file. The source code is loaded from the file named file. The byte-code is written to cfile, which defaults to the PEP 3147/PEP 488 path, ending in .pyc. For example, if file is /foo/bar/baz.py cfile will default to /foo/bar/__pycache__/baz.cpython-32.pyc for Python 3.2. If dfile is specified, it is used as the name of the source file in error messages instead of file. If doraise is true, a PyCompileError is raised when an error is encountered while compiling file. If doraise is false (the default), an error string is written to sys.stderr, but no exception is raised. This function returns the path to byte-compiled file, i.e. whatever cfile value was used.

Los argumentos doraise y quiet determinan cómo los errores son gestionados mientras se compila el archivo. Si quiet es 0 o 1, y doraise es falso, la conducta por defecto es habilitada: un error cadena de caracteres es escrito a sys.stderr, y la función retorna None en vez de una ruta. Si doraise es verdadero, se lanzará un PyCompileError. Sin embargo si quiet es 2, ningún mensaje es escrito y doraise no tiene efecto.

Si la ruta que cfile se convierte (sea especificada explícitamente o computada) es un enlace simbólico o archivo no regular, se lanzará FileExistsError. Esto es para actuar como una advertencia que la importación convertirá esas rutas en archivos regulares si ésta tiene permitido escribir archivos compilados en bytes a esas rutas. Este es un efecto secundario de importar usando el renombramiento de archivos para colocar el archivo de bytes compilado final en el lugar para prevenir problemas de escritura en archivos simultáneos.

optimize controla el nivel de optimización y si es pasado a la función construida compile(). El predeterminado de -1 selecciona el nivel de optimización del intérprete actual.

invalidation_mode debería ser un miembro del enum PycInvalidationMode y controla cómo el caché de código de bytes generado es invalidado en el tiempo de ejecución. El predeterminado es PycInvalidationMode.CHECKED_HASH si la variable de entorno SOURCE_DATE_EPOCH está establecida, de otra manera el predeterminado es PycInvalidationMode.TIMESTAMP.

Distinto en la versión 3.2: Cambiado el valor por defecto de cfile para que cumpla PEP 3147. El por defecto anterior era file + 'c' ('o' si la optimización estaba habilitada). También agregado el parámetro optimize.

Distinto en la versión 3.4: Se cambió el código para usar importlib para la escritura del archivo almacenado de código de bytes. Esto significa que la semántica de la creación/escritura del archivo ahora coincide con lo que importlib hace, por ejemplo permisos, semántica de escribir-y-mover, etc. Además se agregó la consideración de que FileExistsError es lanzado si cfile es un enlace simbólico o un archivo no regular.

Distinto en la versión 3.7: El parámetro invalidation_mode fue agregado como se especificó en PEP 552. Si la variable de entorno SOURCE_DATE_EPOCH se establece, invalidation_mode será forzada a PycInvalidationMode.CHECKED_HASH.

Distinto en la versión 3.7.2: La variable de entorno SOURCE_DATE_EPOCH ya no sobreescribe el valor del argumento invalidation_mode, y en vez de eso determina su valor por defecto.

Distinto en la versión 3.8: El parámetro quiet fue agregado.

class py_compile.PycInvalidationMode

Una enumeración de métodos posibles que el intérprete puede usar para determinar si un archivo de bytes está actualizado con un archivo fuente. El archivo .pyc indica el modo invalidación deseado en su encabezado. Ver Invalidación del código de bytes en caché para más información en cómo Python invalida archivos .pyc en tiempo de ejecución.

Nuevo en la versión 3.7.

TIMESTAMP

El archivo .pyc incluye una marca de tiempo y tamaño del archivo fuente, el cual Python comparará contra los metadatos del archivo fuente durante el tiempo de ejecución para determinar si el archivo .pyc necesita ser regenerado.

CHECKED_HASH

El archivo .pyc incluye un hash del contenido del archivo fuente, el cual Python comparará contra la fuente durante el tiempo de ejecución para determinar si el archivo .pyc necesita ser regenerado.

UNCHECKED_HASH

Como CHECKED_HASH, el archivo .pyc incluye un has del contenido del archivo fuente. Sin embargo, Python asumirá durante el tiempo de ejecución que el archivo .pyc está actualizado y no validará el .pyc contra el archivo fuente en lo absoluto.

Esta opción es útil cuando los .pucs se mantienen actualizados al día por algún sistema externo a Python como un sistema de compilación.

py_compile.main(args=None)

Compila varios archivos fuente. Los archivos mencionados en args (o en la línea de comandos si args es None) son compilados y el código de bytes resultante es almacenado de la manera normal. Esta función no busca una estructura de directorio para localizar archivos fuente; éste sólo compila archivos nombrados explícitamente. Si '-' es el único parámetro en args, la lista de archivos es tomada de una entrada estándar.

Distinto en la versión 3.2: Agregado soporte para '-'.

Cuando este módulo se ejecuta como un script, el main() es usado para compilar todos los archivos llamados en la línea de comandos. El estado de salida es no cero si uno de los archivos no se pudo compilar.

Ver también

Módulo compileall

Utilidades para compilar todos los archivos fuente Python en el árbol del directorio.