"compileall" --- Bibliotecas de Python de compilación de bytes
**************************************************************

**Código fuente:** Lib/compileall.py

======================================================================

Este módulo proporciona algunas funciones de utilidad para admitir la
instalación de bibliotecas Python. Estas funciones compilan archivos
fuente de Python en un árbol de directorios. Este módulo se puede usar
para crear los archivos de código de bytes almacenados en caché en el
momento de la instalación de la biblioteca, que los hace disponibles
para su uso incluso por usuarios que no tienen permiso de escritura en
los directorios de la biblioteca.


Uso de la línea de comandos
===========================

Este módulo puede funcionar como un *script* (usando  **python -m
compileall**) para compilar fuentes de Python.

directory ...
file ...

   Los argumentos posicionales son archivos para compilar o
   directorios que contienen archivos fuente, recorridos
   recursivamente. Si no se proporciona ningún argumento, se comporta
   como si la línea de comando fuera  "-l <directories from
   sys.path>".

-l

   No se recurre en subdirectorios, solo compila archivos de código
   fuente contenidos en directorios nombrados o implícitos.

-f

   Forzar la reconstrucción incluso si las marcas de tiempo están
   actualizadas.

-q

   No imprimir la lista de archivos compilados. Si se pasa una vez,
   los mensajes de error se imprimirán. Si se pasa dos veces, ("-qq"),
   se suprime toda la salida.

-d destdir

   Directorio antepuesto a la ruta de cada archivo que está siendo
   compilado. Esto aparecerá en las devoluciones de tiempo de
   compilación, y también se compila en el archivo de código de bytes,
   donde se usará en las devoluciones de seguimiento y otros mensajes
   en casos donde el archivo fuente no existe al momento en que el
   archivo de código de bytes se ejecuta.

-x regex

   regex se usa para buscar la ruta completa a cada archivo
   considerado para compilación, y si la regex produce una
   coincidencia, se omite el archivo.

-i list

   Leer el archivo "list" y cada línea que contiene la lista de
   archivos y directorios a compilar. Si "list" es "-", leer líneas
   desde "stdin".

-b

   Escribir los archivos de código de byte en las locaciones y nombres
   de herencia, que pueden sobreescribir los archivos de código de
   bytes creado para otra versión de Python. El comportamiento por
   defecto es escribir archivos en sus locaciones y nombres **PEP
   3147**, lo cual permite que archivos de código de byte de versiones
   múltiples de Python coexistan.

-r

   Controlar el nivel máximo de recurrencia para subdirectorios. Si
   esto está dado, la opción "-l" no se tendrá en cuenta. **python -m
   compileall <directory> -r 0** es equivalente a **python -m
   compileall <directory> -l**.

-j N

   Usar *workers* *N* para compilar los archivos dentro del directorio
   dado. Si "`0" se usa, entonces se usa el resultado de
   "os.cpu_count()".

--invalidation-mode [timestamp|checked-hash|unchecked-hash]

   Controlar cómo los archivos de código de byte generados se
   invalidan al momento de ejecución. El valor "timestamp" significa
   que se generarán los archivos ".pyc" con la marca de tiempo fuente
   y el tamaño insertados. Los valores "checked-hash" y "unchecked-
   hash" generan *pycs* basados en hash. Los *pycs* basados en hash
   del archivo insertan un hash de los contenidos del archivo fuente,
   en lugar de una marca de tiempo. Véase Invalidación del código de
   bytes en caché para mayor información sobre cómo Python valida
   archivos de cache de código de bytes. El valor por defecto es
   "timestamp"  si la variable de entorno "SOURCE_DATE_EPOCH" no está
   definida, y "checked-hash" si la variable de entorno
   *SOURCE_DATE_EPOCH`* está definida.

Distinto en la versión 3.2: Se agregaron las opciones "-i", "-b" y
"-h".

Distinto en la versión 3.5: Se agregaron las opciones "-j", "-r", and
"-qq". La opción "-q" se cambió a un valor multinivel. "-b" siempre
producirá un archivo de código de byte que termina en ".pyc", nunca
".pyo".

Distinto en la versión 3.7: Se agregó la opción "--invalidation-mode".

No hay opción de línea de comando para controlar el nivel de
optimización que usa la función "compile()" porque el intérprete de
Python en sí mismo ya proporciona la opción: **python -O -m
compileall**.

De manera similar, la función "compile()" respeta la configuración
"sys.pycache_prefix". El cache de código de byte generado sólo será
útil si "compile()" se ejecuta con el mismo "sys.pycache_prefix" (si
es que existe alguno) que se utilizará en el momento de ejecución.


Funciones públicas
==================

compileall.compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None)

   Descender recursivamente el árbol de directorio invocado por *dir*,
   compilando todos los archivos ".py" que encuentra en el camino.
   Devolver un valor verdadero si todos los archivos se compilan
   exitosamente, y un valor falso en el caso contrario.

   El parámetro *maxlevels* se usar para limitar la profundidad de la
   recursión; toma como valor predeterminado "10".

   Si *ddir* está dado, se antepone a la ruta de cada archivo que se
   compila para usar en los rastreos de tiempo de compilación, y
   también se compilar en el archivo código de byte, donde se usarán
   en trazas y otros mensajes en casos donde el archivo fuente no
   existe en el momento cuando el archivo de código de byte se
   ejecuta.

   Si *force* es verdadero, los módulos se re-compilan aun cuando las
   marcas de tiempo están actualizadas.

   Si *rx* está dado, su método de búsqueda en la ruta completa de
   cada archivo considerado para compilación, y si devuelve un valor
   verdadero, el archivo se saltea.

   Si *quiet* es "False" o "0" (el valor predeterminado), los nombres
   de archivo y otra información se imprimen en salida estándar. Si se
   configura en "1", solo se imprimen los errores. Si se configura en
   "2", se suprime toda la salida.

   Si *legacy* es verdadero, los archivos de código de byte se
   escriben en sus locaciones y nombres de herencia, que pueden
   sobreescribir los archivos de código de byte creado por otra
   versión de Python. El comportamiento por defecto es escribir
   archivos en sus locaciones y nombres **PEP 3147**, lo cual permite
   que archivos de código de byte de múltiples versiones de Python
   coexistan.

   *optimize* especifica el nivel de optimización para el compilador.
   Se pasa a una función incorporada "compile()".

   El argumento *workers* especifica cuántos workers se usan para
   compilar archivos en paralelo. El comportamiento por defecto es no
   usar múltiples workers. Si la plataforma no puede usar workers
   múltiples y el argumento *workers* está dado, la compilación
   secuencial se usará como *fallback*. Si *workers* es 0, el número
   de núcleos se usa en el sistema. Si *workers* es menor que "0", se
   genera un "ValueError".

   *invalidation_mode* debería ser un miembro de la enumeración
   "py_compile.PycInvalidationMode" y controla cómo se invalidan los
   pycs generados en el momento de ejecución.

   Distinto en la versión 3.2: Se agregó el parámetro *legacy* y
   *optimize*.

   Distinto en la versión 3.5: Se agregó el parámetro *workers*.

   Distinto en la versión 3.5: El parámetro *quiet* se cambió a un
   valor multinivel.

   Distinto en la versión 3.5: El parámetro *legacy* solo escribe
   archivos ".pyc", no archivos ".pyo", no import cuál sea el valor de
   *optimize*.

   Distinto en la versión 3.6: Acepta un *path-like object*.

   Distinto en la versión 3.7: Se agregó el parámetro
   *invalidation_mode*.

   Distinto en la versión 3.7.2: El valor predeterminado del parámetro
   *invalidation_mode* se actualiza a *None*.

   Distinto en la versión 3.8: Configurar *workers* a 0 ahora elige el
   número óptimo de núcleos.

compileall.compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)

   Compilar el archivo con ruta *fullname*. Retorna un valor verdadero
   si el archivo se compila exitosamente, y uno falso en el caso
   contrario.

   Si *ddir* está dado, se antepone a la ruta del archivo que está
   siendo compilado para su uso en las trazas de tiempo de
   compilación, y también se compilar en el archivo de código de
   bytes, donde será utilizado en trazas y otros mensajes en casos
   donde el archivo fuente no existe en el momento en que el archivo
   de código de bytes es ejecutado.

   Si *rx* está dado, su método de búsqueda recibe el nombre de ruta
   completo hacia el archivo que está siendo compilado, y si devuelve
   un valor verdadero, el archivo no se compila y retorna "True".

   Si *quiet* es "False" o "0" (el valor predeterminado), los nombres
   de archivo y otra información se imprimen en salida estándar. Si se
   configura en "1", solo se imprimen los errores. Si se configura en
   "2", se suprime toda la salida.

   Si *legacy* es verdadero, los archivos de código de byte se
   escriben en sus locaciones y nombres de herencia, que pueden
   sobreescribir los archivos de código de byte creado por otra
   versión de Python. El comportamiento por defecto es escribir
   archivos en sus locaciones y nombres **PEP 3147**, lo cual permite
   que archivos de código de byte de múltiples versiones de Python
   coexistan.

   *optimize* especifica el nivel de optimización para el compilador.
   Se pasa a una función incorporada "compile()".

   *invalidation_mode* debería ser un miembro de la enumeración
   "py_compile.PycInvalidationMode" y controla cómo se invalidan los
   pycs generados en el momento de ejecución.

   Nuevo en la versión 3.2.

   Distinto en la versión 3.5: El parámetro *quiet* se cambió a un
   valor multinivel.

   Distinto en la versión 3.5: El parámetro *legacy* solo escribe
   archivos ".pyc", no archivos ".pyo", no import cuál sea el valor de
   *optimize*.

   Distinto en la versión 3.7: Se agregó el parámetro
   *invalidation_mode*.

   Distinto en la versión 3.7.2: El valor predeterminado del parámetro
   *invalidation_mode* se actualiza a *None*.

compileall.compile_path(skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)

   Compila en bytes todos los archivos ".py" a lo largo de "sys.path".
   Retorna un valor verdadero si todos los archivos se compilan
   exitosamente, y uno falso en el caso contrario.

   Si *skip_curdir* es verdadero (el valor predeterminado), el
   directorio actual no está incluido en la búsqueda. Todos los otros
   parámetros se pasan a la función "compile_dir()". Nótese que, al
   contrario de las otras funciones de compilación, "maxlevels" tomar
   "0" como valor predeterminado.

   Distinto en la versión 3.2: Se agregó el parámetro *legacy* y
   *optimize*.

   Distinto en la versión 3.5: El parámetro *quiet* se cambió a un
   valor multinivel.

   Distinto en la versión 3.5: El parámetro *legacy* solo escribe
   archivos ".pyc", no archivos ".pyo", no import cuál sea el valor de
   *optimize*.

   Distinto en la versión 3.7: Se agregó el parámetro
   *invalidation_mode*.

   Distinto en la versión 3.7.2: El valor predeterminado del parámetro
   *invalidation_mode* se actualiza a *None*.

Para forzar la re-compilación del los archivos ".py" en el
subdirectorio "Lib/" y todos sus subdirectorios:

   import compileall

   compileall.compile_dir('Lib/', force=True)

   # Perform same compilation, excluding files in .svn directories.
   import re
   compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True)

   # pathlib.Path objects can also be used.
   import pathlib
   compileall.compile_dir(pathlib.Path('Lib/'), force=True)

Ver también:

  Module "py_compile"
     Byte-compile a single source file.
