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.

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.