"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.
