"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 as the name of the source file in
   error messages instead of *file*.  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.

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
