"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 type "PyCompileError" 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 dans
   "sys.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 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
