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

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


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
