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)

Compila un archivo fuente en código de bytes y escriba el archivo de caché de código de bytes. El código fuente se carga desde el archivo llamado file. El código de bytes se escribe en cfile, que por defecto es la ruta PEP 3147/PEP 488, que termina en .pyc. Por ejemplo, si file es /foo/bar/baz.py cfile se establecerá de forma predeterminada en /foo/bar/__pycache__/baz.cpython-32.pyc para Python 3.2. Si se especifica dfile, se usa como el nombre del archivo de origen en los mensajes de error en lugar de file. Si doraise es verdadero, se lanza un PyCompileError cuando se encuentra un error al compilar file. Si doraise es falso (el valor predeterminado), se escribe una cadena de error en sys.stderr, pero no se genera ninguna excepción. Esta función retorna la ruta al archivo compilado por bytes, es decir, cualquier valor cfile que se haya utilizado.

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.