"compileall" — Génération du code intermédiaire des bibliothèques Python
************************************************************************

**Code source :** Lib/compileall.py

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

Ce module contient des fonctions qui facilitent l'installation de
bibliothèques Python. Elles compilent, sous forme de code
intermédiaire (*bytecode*), les fichiers source situés dans un dossier
de votre choix. Ce module est particulièrement utile pour générer les
fichiers de code intermédiaire lors de l'installation d'une
bibliothèque, les rendant disponibles même pour les utilisateurs qui
n'ont pas les privilèges d'écriture dans l'emplacement d'installation.


Utilisation en ligne de commande
================================

On peut se servir de ce module comme d'un script (avec **python -m
compileall**) pour compiler les fichiers source Python.

directory ...
file ...

   Les arguments positionnels sont les fichiers à compiler. Ils
   peuvent aussi être des dossiers, qui sont alors parcourus
   récursivement pour compiler tous les fichiers de code ".py" qu'ils
   contiennent. Lorsque le script ne reçoit aucun argument, il fait
   comme s'il avait été appelé avec *-l <tous les dossiers de
   sys.path>*.

-l

   Compiler uniquement les fichiers situés directement dans les
   dossiers passés en argument ou implicites, sans descendre
   récursivement dans les sous-dossiers.

-f

   Forcer la recompilation même si les horodatages sont à jour.

-q

   Supprimer l'affichage des noms des fichiers compilés.Si cette
   option est donnée une seule fois, les erreurs sont affichées malgré
   tout. Vous pouvez les supprimer en passant l'option deux fois
   (c'est-à-dire avec "-qq").

-d destdir

   Ce nom de dossier est ajouté en tête du chemin de chaque fichier
   compilé. Il aura une influence sur les traces d'appels pour les
   erreurs levées lors de la compilation, et sera reflété dans les
   fichiers de code intermédiaire, pour utilisation dans les traces
   d'appels et autres messages si le fichier source n'existe pas au
   moment de l'exécution.

-x regex

   Exclut tous les fichiers dont les noms correspondent à l'expression
   régulière *regex*.

-i list

   Ajoute chaque ligne du fichier *list* aux fichiers et dossiers à
   compiler. *list* peut être "-", auquel cas le script lit l'entrée
   standard.

-b

   Utilise l'ancienne manière de nommer et placer les fichiers de code
   intermédiaire, en écrasant éventuellement ceux générés par une
   autre version de Python. Par défaut, les règles décrites dans la
   **PEP 3147** s'appliquent. Elles permettent à différentes versions
   de l'interpréteur Python de coexister en conservant chacune ses
   propres fichiers ".pyc".

-r

   Règle le niveau de récursion maximal pour le parcours des sous-
   dossiers. Lorsque cette option est fournie, "-l" est ignorée.
   **python -m compileall <dossier> -r 0** revient au même que
   **python -m compileall <dossier> -l**.

-j N

   Effectue la compilation avec *N* processus parallèles. Si *N* vaut
   0, autant de processus sont créés que la machine dispose de
   processeurs (résultat de "os.cpu_count()").

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

   Définit la manière dont les fichiers de code intermédiaire seront
   invalidés au moment de l'exécution. Avec "timestamp", les fichiers
   ".pyc" générés comportent l'horodatage de la source et sa taille.
   Avec "checked-hash" ou "unchecked-hash", ce seront des pyc
   utilisant le hachage, qui contiennent une empreinte du code source
   plutôt qu'un horodatage. Voir Invalidation de bytecode mis en cache
   pour plus d'informations sur la manière dont Python valide les
   fichiers de code intermédiaire conservés en cache lors de
   l'exécution. La valeur par défaut est "timestamp". Cependant, si la
   variable d'environnement "SOURCE_DATE_EPOCH" a été réglée, elle
   devient "checked-hash".

Modifié dans la version 3.2: ajout des options "-i", "-b" et "-h".

Modifié dans la version 3.5: ajout des options "-j", "-r" et "-qq"
(l'option "-q" peut donc prendre plusieurs niveaux). "-b" produit
toujours un fichier de code intermédiaire portant l'extension ".pyc",
et jamais ".pyo".

Modifié dans la version 3.7: ajout de l'option "--invalidation-mode".

Il n'y a pas d'option en ligne de commande pour contrôler le niveau
d'optimisation utilisé par la fonction "compile()". Il suffit en effet
d'utiliser l'option "-O" de l'interpréteur Python lui-même : **python
-O -m compileall**.

De même, la fonction "compile()" utilise le réglage
"sys.pycache_prefix". Le code intermédiaire généré ne pourra servir
que dans la mesure où "compile()" est exécutée avec la même valeur de
"sys.pycache_prefix" (si tant est qu'elle soit définie) que celle en
vigueur au moment d'exécuter le programme.


Fonctions publiques
===================

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

   Parcourt récursivement le dossier *dir*, en compilant tous les
   fichiers ".py". Renvoie une valeur vraie si tous les fichiers ont
   été compilés sans erreur, et une valeur fausse dans le cas
   contraire.

   The *maxlevels* parameter is used to limit the depth of the
   recursion; it defaults to "10".

   Si *ddir* est fourni, il est ajouté en tête du chemin de chaque
   fichier compilé, ce qui modifie l'affichage des traces d'appels
   pour les erreurs qui seraient levées lors de la compilation. De
   plus, il se retrouve dans les fichiers de code intermédiaire, pour
   utilisation dans les traces et autres messages si le fichier source
   n'existe pas au moment de l'exécution.

   Si *force* est vrai, les modules sont recompilés même si leurs
   horodatages sont à jour.

   If *rx* is given, its search method is called on the complete path
   to each file considered for compilation, and if it returns a true
   value, the file is skipped.

   Si *quiet* est "False" ou bien "0" (la valeur par défaut), les noms
   de fichiers et d'autres informations sont affichés sur la sortie
   standard. Avec "1", seules les erreurs sont affichées. Avec "2",
   aucune sortie n'est émise.

   Si *legacy* est vrai, les fichiers de code intermédiaire sont
   nommés et placés selon l'ancienne méthode, en écrasant
   éventuellement ceux générés par une autre version de Python. Par
   défaut, les règles décrites dans la **PEP 3147** s'appliquent.
   Elles permettent à différentes versions de l'interpréteur Python de
   coexister en conservant chacune ses propres fichiers ".pyc".

   *optimize* specifies the optimization level for the compiler.  It
   is passed to the built-in "compile()" function.

   *workers* est le nombre de tâches lancées en parallèle pour la
   compilation. Par défaut, les fichiers sont compilés
   séquentiellement. Cette même stratégie s'applique dans tous les cas
   lorsque le parallélisme n'est pas possible sur la plateforme
   d'exécution. Si *workers* vaut 0, autant de tâches sont lancées que
   le système comporte de cœurs. Si *workers* est strictement négatif,
   une exception de type "ValueError" est levée.

   *invalidation_mode* doit être un membre de l'énumération
   "py_compile.PycInvalidationMode" et détermine la manière dont les
   fichiers ".pyc" sont invalidés lorsque l'interpréteur tente de les
   utiliser.

   Modifié dans la version 3.2: ajout des paramètres *legacy* et
   *optimize*.

   Modifié dans la version 3.5: ajout du paramètre *workers*.

   Modifié dans la version 3.5: le paramètre *quiet* peut prendre
   plusieurs niveaux.

   Modifié dans la version 3.5: Lorsque le paramètre *legacy* est
   vrai, des fichiers ".pyc", et jamais ".pyo", sont générés, quel que
   soit le niveau d'optimisation.

   Modifié dans la version 3.6: Accepte un *path-like object*.

   Modifié dans la version 3.7: ajout du paramètre
   *invalidation_mode*.

   Modifié dans la version 3.7.2: La valeur par défaut du paramètre
   *invalidation_mode* est changée à "None".

   Modifié dans la version 3.8: Un nombre de processus adapté à la
   machine est choisi lorsque *workers* vaut 0.

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

   Compile le fichier dont le chemin est donné par *fullname*. Renvoie
   une valeur vraie si et seulement si le fichier est compilé sans
   erreur.

   Si *ddir* est fourni, il est ajouté en tête du chemin de chaque
   fichier compilé, ce qui modifie l'affichage des traces pour les
   erreurs qui seraient levées lors de la compilation. De plus, il se
   retrouve dans les fichiers de code intermédiaire, pour utilisation
   dans les traces et autres messages si le fichier source n'existe
   pas au moment de l'exécution.

   If *rx* is given, its search method is passed the full path name to
   the file being compiled, and if it returns a true value, the file
   is not compiled and "True" is returned.

   Si *quiet* est "False" ou bien "0" (la valeur par défaut), les noms
   de fichiers et d'autres informations sont affichés sur la sortie
   standard. Avec "1", seules les erreurs sont affichées. Avec "2",
   aucune sortie n'est émise.

   Si *legacy* est vrai, les fichiers de code intermédiaire sont
   nommés et placés selon l'ancienne méthode, en écrasant
   éventuellement ceux générés par une autre version de Python. Par
   défaut, les règles décrites dans la **PEP 3147** s'appliquent.
   Elles permettent à différentes versions de l'interpréteur Python de
   coexister en conservant chacune ses propres fichiers ".pyc".

   *optimize* specifies the optimization level for the compiler.  It
   is passed to the built-in "compile()" function.

   *invalidation_mode* doit être un membre de l'énumération
   "py_compile.PycInvalidationMode" et détermine la manière dont les
   fichiers ".pyc" sont invalidés lorsque l'interpréteur tente de les
   utiliser.

   Nouveau dans la version 3.2.

   Modifié dans la version 3.5: le paramètre *quiet* peut prendre
   plusieurs niveaux.

   Modifié dans la version 3.5: Lorsque le paramètre *legacy* est
   vrai, des fichiers ".pyc", et jamais ".pyo", sont générés, quel que
   soit le niveau d'optimisation.

   Modifié dans la version 3.7: ajout du paramètre
   *invalidation_mode*.

   Modifié dans la version 3.7.2: La valeur par défaut du paramètre
   *invalidation_mode* est changée à "None".

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

   Compile tous les fichiers ".py" contenus dans les dossiers de
   "sys.path". Renvoie une valeur vraie s'ils ont tous été compilés
   sans erreur, et une valeur fausse dans le cas contraire.

   Si *skip_curdir* est vrai (c'est le cas par défaut), le dossier
   courant est exclu de la recherche. Les autres paramètres sont
   passés à "compile_dir()". Notez que contrairement aux autres
   fonctions de ce module, la valeur par défaut de "maxlevels" est
   "0".

   Modifié dans la version 3.2: ajout des paramètres *legacy* et
   *optimize*.

   Modifié dans la version 3.5: le paramètre *quiet* peut prendre
   plusieurs niveaux.

   Modifié dans la version 3.5: Lorsque le paramètre *legacy* est
   vrai, des fichiers ".pyc", et jamais ".pyo", sont générés, quel que
   soit le niveau d'optimisation.

   Modifié dans la version 3.7: ajout du paramètre
   *invalidation_mode*.

   Modifié dans la version 3.7.2: La valeur par défaut du paramètre
   *invalidation_mode* est changée à "None".

Pour forcer la recompilation de tous les fichiers ".py" dans le
dossier "Lib/" et tous ses sous-dossiers :

   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)

Voir aussi:

  Module "py_compile"
     Compiler un fichier source unique.
