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, aPyCompileError
is raised when an error is encountered while compiling file. If doraise is false (the default), an error string is written tosys.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 retornaNone
en vez de una ruta. Si doraise es verdadero, se lanzará unPyCompileError
. 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 esPycInvalidationMode.CHECKED_HASH
si la variable de entornoSOURCE_DATE_EPOCH
está establecida, de otra manera el predeterminado esPycInvalidationMode.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 queimportlib
hace, por ejemplo permisos, semántica de escribir-y-mover, etc. Además se agregó la consideración de queFileExistsError
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 aPycInvalidationMode.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.