py_compile
— Compilation de sources Python¶
Code source : Lib/py_compile.py
Le module py_compile
définit une fonction principale qui génère un fichier de code intermédiaire à partir d'un fichier source. Il exporte également la fonction qu'il exécute quand il est lancé en tant que script.
Bien que ce module ne soit pas d'usage fréquent, il peut servir lors de l'installation de bibliothèques partagées, notamment dans le cas où tous les utilisateurs n'ont pas les privilèges d'écriture dans l'emplacement d'installation.
-
exception
py_compile.
PyCompileError
¶ Exception levée quand une erreur se produit à la compilation.
-
py_compile.
compile
(file, cfile=None, dfile=None, doraise=False, optimize=-1, invalidation_mode=PycInvalidationMode.TIMESTAMP, quiet=0)¶ Compile un fichier source en un fichier de code intermédiaire, mis en cache. Le code source est lu dans le fichier file. Par défaut, le code intermédiaire est écrit dans l'emplacement prescrit par la PEP 3147, avec l'extension
.pyc
. Par exemple, si file est/ga/bu/zo/meu.py
, le code intermédiaire ira dans/ga/bu/zo/__pycache__/meu.cpython-32.pyc
(pour l'interpréteur Python 3.2). La destination peut être modifiée à l'aide du paramètre cfile. Si dfile est fourni, il est utilisé comme nom du fichier source dans les messages d'erreur à la place de file. Si doraise est vrai, une exception de typePyCompileError
est levée dans le cas où la compilation de la source produit une erreur. Sinon (comportement par défaut), l'erreur est affichée danssys.stderr
, mais l'exécution se poursuit normalement. Cette fonction renvoie le chemin du fichier de code intermédiaire, c'est-à-dire l'emplacement choisi automatiquement, ou bien cfile s'il est précisé.Plus précisément, ce sont les arguments doraise et quiet qui déterminent la stratégie de gestion des erreurs. En effet, si quiet vaut 0 ou 1, et doraise est faux, le comportement par défaut s'applique : un message d'erreur est affiché dans
sys.stderr
, et la fonction renvoieNone
au lieu d'un chemin. Au contraire, si doraise est vrai, une exceptionPyCompileError
est levée, sauf si quiet vaut 2. Dans ce dernier cas, aucun message n'est émis, et doraise reste sans effet.Si le chemin de destination, explicité par cfile ou choisi automatiquement, est un lien symbolique, ou n'est pas un véritable fichier, une exception de type
FileExistsError
est levée. Ceci, dans le but de vous avertir que le système d'importation changera ces chemins en fichiers s'il est autorisé à y écrire des fichiers de code intermédiaire. En effet, les importations passent par un renommage final du fichier de code intermédiaire vers sa destination, afin d'éviter les problèmes liés à l'écriture simultanée d'un même fichier par plusieurs processus.optimize règle le niveau d'optimisation. Ce paramètre est passé directement à la fonction native
compile()
. Avec la valeur par défaut de-1
, le code intermédiaire hérite du niveau d'optimisation de l'interpréteur courant.invalidation_mode précise la manière dont le code intermédiaire produit est invalidé à son exécution. Il doit être un membre de l'énumération
PycInvalidationMode
. La valeur par défaut estPycInvalidationMode.TIMESTAMP
. Elle passe toutefois àPycInvalidationMode.CHECKED_HASH
si la variable d'environnementSOURCE_DATE_EPOCH
est définie.Modifié dans la version 3.2: la méthode de choix de destination a changé au profit de celle décrite dans la PEP 3147. Auparavant, le nom du fichier de code intermédiaire était file +
'c'
(ou'o'
lorsque les optimisations étaient actives). Le paramètre optimize a été ajouté.Modifié dans la version 3.4: le code a été modifié pour faire appel à
importlib
dans les opérations d'écriture du code intermédiaire. Ce module se comporte donc exactement commeimportlib
en ce qui concerne, par exemple, les permissions, ou le renommage final qui garantit une opération atomique.FileExistsError
est désormais levée si la destination est un lien symbolique ou n'est pas un véritable fichier.Modifié dans la version 3.7: le paramètre invalidation_mode a été ajouté comme requis par la PEP 552. Si la variable d'environnement
SOURCE_DATE_EPOCH
est définie, invalidation_mode est ignoré, etPycInvalidationMode.CHECKED_HASH
s'applique dans tous les cas.Modifié dans la version 3.7.2: La variable d'environnement
SOURCE_DATE_EPOCH
n'a plus préséance sur le paramètre invalidation_mode, mais détermine seulement le comportement par défaut lorsque ce paramètre n'est pas passé.Modifié dans la version 3.8: ajout du paramètre quiet.
-
class
py_compile.
PycInvalidationMode
¶ Énumération des méthodes que l'interpréteur est susceptible d'appliquer afin de déterminer si un fichier de code intermédiaire est périmé par rapport à sa source. Les fichiers
.pyc
portent le mode d'invalidation désiré dans leur en-tête. Veuillez-vous référer à Invalidation de bytecode mis en cache pour plus d'informations sur la manière dont Python invalide les fichiers.pyc
à l'exécution.Nouveau dans la version 3.7.
-
TIMESTAMP
¶ Le fichier
.pyc
contient l'horodatage et la taille de la source. L'interpréteur inspecte les métadonnées du fichier source au moment de l'exécution, et régénère le fichier.pyc
si elles ont changé.
-
CHECKED_HASH
¶ Le fichier
.pyc
porte une empreinte du code source. À l'exécution, elle est recalculée à partir de la source éventuellement modifiée, et le fichier.pyc
est régénéré si les deux empreintes sont différentes.
-
UNCHECKED_HASH
¶ Le principe est le même que
CHECKED_HASH
, mais à l'exécution, l'interpréteur considère systématiquement que le fichier.pyc
est à jour, sans regarder la source.Cette option est utile lorsque les fichiers
.pyc
sont maintenus par un outil externe, comme un système d'intégration.
-
-
py_compile.
main
(args=None)¶ Compile et met en cache tous les fichiers de la séquence args, ou ceux passés comme arguments en ligne de commande si args est
None
. Cette fonction n'effectue aucune recherche des fichiers sources dans des dossiers. Elle compile simplement les fichiers nommés un par un. Si'-'
est le seul paramètre dans args, la liste des fichiers est lue sur l'entrée standard.Modifié dans la version 3.2: prise en charge de
'-'
.
Lorsque ce module est exécuté en tant que script, la fonction main()
compile tous les fichiers passés comme arguments sur la ligne de commande. Le code de retour vaut zéro si tous ont été compilés sans erreur.
Voir aussi
- Module
compileall
Utilitaires pour compiler des fichiers source Python dans une arborescence