# `py_compile` --- Compile Python source files

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 a source file to byte-code and write out the byte-code cache file. The source code is loaded from the file named file. The byte-code is written to cfile, which defaults to the PEP 3147/PEP 488 path, ending in `.pyc`. For example, if file is `/foo/bar/baz.py` cfile will default to `/foo/bar/__pycache__/baz.cpython-32.pyc` for Python 3.2. If dfile is specified, it is used instead of file as the name of the source file from which source lines are obtained for display in exception tracebacks. If doraise is true, a `PyCompileError` is raised when an error is encountered while compiling file. If doraise is false (the default), an error string is written to `sys.stderr`, but no exception is raised. This function returns the path to byte-compiled file, i.e. whatever cfile value was used.

  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 renvoie `None` au lieu d'un chemin. Au contraire, si doraise est vrai, une exception `PyCompileError` 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 est `PycInvalidationMode.TIMESTAMP`. Elle passe toutefois à `PycInvalidationMode.CHECKED_HASH` si la variable d'environnement `SOURCE_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 comme `importlib` 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é, et `PycInvalidationMode.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

  An enumeration of possible methods the interpreter can use to determine whether a bytecode file is up to date with a source file. The `.pyc` file indicates the desired invalidation mode in its header. See Invalidation de bytecode mis en cache for more information on how Python invalidates `.pyc` files at runtime.

  Added in 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.

## Command-Line Interface

This module can be invoked as a script to compile several source files. The files named in filenames are compiled and the resulting bytecode is cached in the normal manner. This program does not search a directory structure to locate source files; it only compiles files named explicitly. The exit status is nonzero if one of the files could not be compiled.

<file> ... <fileN>
-

  Positional arguments are files to compile. If `-` is the only parameter, the list of files is taken from standard input.

-q, --quiet

  Suppress errors output.

Modifié dans la version 3.2: Added support for `-`.

Modifié dans la version 3.10: Added support for `-q`.

Voir aussi

Module `compileall`

  Utilitaires pour compiler des fichiers source Python dans une arborescence