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

-s strip_prefix

-p prepend_prefix

   Retire ("-s") ou ajoute ("-p") le préfixe aux chemins stockés dans
   les fichiers ".pyc". Cette option ne peut pas être combinée avec
   "-d".

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

-o level

   Compile avec un certain niveau d'optimisation. Cette option peut
   être passée plusieurs fois afin de compiler pour plusieurs niveaux
   d'un seul coup (par exemple, "compileall -o 1 -o 2").

-e dir

   Ignore les liens symboliques qui redirigent en dehors du dossier.

--hardlink-dupes

   Si deux fichiers ".pyc" compilés avec des niveaux d'optimisation
   différents ont finalement le même contenu, emploie des liens
   physiques pour les fusionner.

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

Modifié dans la version 3.9: ajout des options "-s", "-p", "-e" et "--
hardlink-dupes". Rehaussement de la limite de récursion par défaut à
"sys.getrecursionlimit()" au lieu de 10 précédemment. L'option "-o"
peut être passée plusieurs fois.

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=sys.getrecursionlimit(), ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=- 1, workers=1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)

   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.

   Le paramètre *maxlevels* permet de limiter la profondeur de
   récursion. Sa valeur par défaut est celle de
   "sys.getrecursionlimit()".

   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.

   Si *rx* est donné, sa méthode "search" est appelée sur le chemin
   complet de chaque fichier source, et si elle renvoie une valeur
   vraie, le fichier est sauté. *rx* sera habituellement une
   expression régulière (objet re.Pattern).

   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* définit le niveau d'optimisation qu'applique le
   compilateur. Cet argument est passé directement à la fonction
   native "compile()". Il peut également être fourni sous la forme
   d'une séquence de niveaux d'optimisation, ce qui permet de compiler
   chaque fichier ".py" plusieurs fois en appliquant divers niveaux
   d'optimisation.

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

   The *stripdir*, *prependdir* and *limit_sl_dest* arguments
   correspond to the "-s", "-p" and "-e" options described above. They
   may be specified as "str" or "os.PathLike".

   Un argument *hardlink_dupes* vrai correspond à l'utilisation de
   l'option "--hardlink-dupes".

   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 *objet simili-chemin*.

   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.

   Modifié dans la version 3.9: ajout des arguments *stripdir*,
   *prependdir*, *limit_sl_dest* et *hardlink_dupes*. La valeur par
   défaut de *maxlevels* a été changée pour "sys.getrecursionlimit()"
   (elle était de 10 auparavant).

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

   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.

   Si *rx* est donné, sa méthode "search" est appelée sur le chemin
   complet de chaque fichier source, et si elle renvoie une valeur
   vraie, le fichier est sauté. *rx* sera habituellement une
   expression régulière (objet re.Pattern).

   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* définit le niveau d'optimisation qu'applique le
   compilateur. Cet argument est passé directement à la fonction
   native "compile()". Il peut également être fourni sous la forme
   d'une séquence de niveaux d'optimisation, ce qui permet de compiler
   chaque fichier ".py" plusieurs fois en appliquant divers niveaux
   d'optimisation.

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

   The *stripdir*, *prependdir* and *limit_sl_dest* arguments
   correspond to the "-s", "-p" and "-e" options described above. They
   may be specified as "str" or "os.PathLike".

   Un argument *hardlink_dupes* vrai correspond à l'utilisation de
   l'option "--hardlink-dupes".

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

   Modifié dans la version 3.9: Ajout des arguments *stripdir*,
   *prependdir*, *limit_sl_dest* et *hardlink_dupes*.

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.
