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.