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