9. Référence de l'API
*********************


9.1. "distutils.core" --- Fonctionnalités principales du module Distutils
=========================================================================

Le module "distutils.core" est le seul module qui a besoin d'être
installé pour utiliser Distutils. Il fournit le "setup()" (qui est
appelé par le script *setup.py*). Il fournit indirectement les classes
"distutils.dist.Distribution" et "distutils.cmd.Command".

distutils.core.setup(arguments)

   La fonction de base à tout faire qui fait presque tout ce dont vous
   pourriez attendre d'une méthode Distutils.

   La fonction "setup" prend un grand nombre d'arguments. Ils sont
   présentés dans le tableau suivant.

   +----------------------+----------------------------------+---------------------------------------------------------------+
   | nom de l'argument    | valeur                           | type                                                          |
   |======================|==================================|===============================================================|
   | *name*               | Le nom du paquet                 | une chaîne de caractères                                      |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *version*            | Le numéro de version du paquet,  | une chaîne de caractères                                      |
   |                      | voir "distutils.version"         |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *description*        | Une ligne unique décrivant le    | une chaîne de caractères                                      |
   |                      | paquet                           |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *long_description*   | Une description plus longue du   | une chaîne de caractères                                      |
   |                      | paquet                           |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *author*             | Le nom de l'auteur du paquet     | une chaîne de caractères                                      |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *author_email*       | L'adresse e-mail de l'auteur du  | une chaîne de caractères                                      |
   |                      | paquet                           |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *maintainer*         | Le nom de l'actuel mainteneur,   | une chaîne de caractères                                      |
   |                      | s'il est différent de l'auteur.  |                                                               |
   |                      | Remarquez que si *maintainer*    |                                                               |
   |                      | est fourni, *distutils*          |                                                               |
   |                      | l'utilise à la place de *author* |                                                               |
   |                      | dans "PKG-INFO".                 |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *maintainer_email*   | Le courriel de l'actuel          | une chaîne de caractères                                      |
   |                      | mainteneur, si différent de      |                                                               |
   |                      | l'auteur                         |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *url*                | Une URL pour le paquet (page     | une chaîne de caractères                                      |
   |                      | d'accueil)                       |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *download_url*       | Une URL pour télécharger le      | une chaîne de caractères                                      |
   |                      | paquet                           |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *packages*           | Une liste des paquets Python que | une liste de chaînes de caractères                            |
   |                      | *distutils* va manipuler         |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *py_modules*         | Une liste de modules Python que  | une liste de chaînes de caractères                            |
   |                      | *distutils* va manipuler         |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *scripts*            | Une liste de scripts autonomes à | une liste de chaînes de caractères                            |
   |                      | construire et à installer        |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *ext_modules*        | Une liste des extensions Python  | une liste d'instances de "distutils.core.Extension"           |
   |                      | à construire                     |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *classifiers*        | Une liste de catégories pour le  | une liste des chaînes de caractères, les classificateurs      |
   |                      | paquet                           | valides sont listés sur PyPI.                                 |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *distclass*          | la classe "Distribution" à       | une sous classe de "distutils.core.Distribution"              |
   |                      | utiliser                         |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *script_name*        | Le nom du script *setup.py* .    | une chaîne de caractères                                      |
   |                      | Initialisé par "sys.argv[0]"     |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *script_args*        | Arguments à fournir au script    | une liste de chaînes de caractères                            |
   |                      | d'installation                   |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *options*            | options par défaut pour le       | un dictionnaire                                               |
   |                      | script d'installation            |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *license*            | La licence pour le paquet        | une chaîne de caractères                                      |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *keywords*           | Méta-données descriptives, voir  | Une liste de chaînes de caractères ou une chaîne de caractère |
   |                      | **PEP 314**                      | dont les éléments sont séparés par des virgules.              |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *platforms*          |                                  | Une liste de chaînes de caractères ou une chaîne de caractère |
   |                      |                                  | dont les éléments sont séparés par des virgules.              |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *cmdclass*           | Un dictionnaire des noms de      | un dictionnaire                                               |
   |                      | commandes et des sous-classes    |                                                               |
   |                      | "Command"                        |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *data_files*         | Une liste de fichiers de données | une liste                                                     |
   |                      | à installer                      |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *package_dir*        | Un dictionnaire des paquets et   | un dictionnaire                                               |
   |                      | des noms de dossiers             |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+

distutils.core.run_setup(script_name[, script_args=None, stop_after='run'])

   Exécute un script d'installation dans un environnement quelque peu
   contrôlé, et renvoie une instance "distutils.dist.distribution" qui
   contrôle l’exécution. Ceci est utile si vous avez besoin de
   connaître les méta-données de la distribution (passées sous forme
   d'arguments nommés de *script* à la fonction "setup()"), ou le
   contenu des fichiers de configuration ou de la ligne de commande.

   *script_name* est un fichier qui sera lu et exécuté avec "exec()".
   "sys.argv[0]" sera remplacé par *script* par la durée de l'appel.
   *script_args* est une liste de chaînes de caractères; si fourni,
   "sys.argv[1:]" sera remplacé par *script_args* pour la durée de
   l'appel.

   *stop_after* dit à "setup()" quand s'arrêter; valeurs possibles:

   +-----------------+-----------------------------------------------+
   | valeur          | description                                   |
   |=================|===============================================|
   | *init*          | S'arrête une fois que l'instance              |
   |                 | "Distribution" a été créée et renseignée avec |
   |                 | les arguments-clés de "setup()"               |
   +-----------------+-----------------------------------------------+
   | *config*        | S'arrête une fois que les fichiers de         |
   |                 | configuration ont été parcouru (et que leurs  |
   |                 | données ont été stockées dans l'instance      |
   |                 | "Distribution")                               |
   +-----------------+-----------------------------------------------+
   | *commandline*   | S'arrête une fois que la ligne de commande    |
   |                 | ("sys.argv[1:]" ou *script_args*) a été       |
   |                 | parcouru (et les données stockées dans        |
   |                 | l'instance "Distribution")                    |
   +-----------------+-----------------------------------------------+
   | *run*           | S'arrête une fois que toutes les commandes    |
   |                 | ont été exécutées (comme si "setup()" fût     |
   |                 | appelé de la manière habituelle). Ceci est la |
   |                 | valeur par défaut.                            |
   +-----------------+-----------------------------------------------+

De plus, le module "distutils.core" a exposé un nombre de classe qui
existent ailleurs.

* "Extension" du module "distutils.extension"

* "Command" du module "distutils.cmd"

* "Distribution" du module "distutils.dist"

Une courte description de chacune d'elle suit, mais consultez le
module concerné pour une référence complète.

class distutils.core.Extension

   La classe *Extension* décrit un seul module d'extension C ou C++
   dans un script d'installation. Elle accepte dans son constructeur
   les arguments nommés suivants:

   +--------------------------+----------------------------------+-----------------------------+
   | nom de l'argument        | valeur                           | type                        |
   |==========================|==================================|=============================|
   | *name*                   | Le nom complet de l'extension,   | une chaîne de caractères    |
   |                          | incluant n'importe quel paquet   |                             |
   |                          | --- c-à-d *pas* un nom de        |                             |
   |                          | fichier ou de chemin mais un nom |                             |
   |                          | Python séparé par des points.    |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *sources*                | Listes des noms de fichier des   | une liste de chaînes de     |
   |                          | sources, relatifs à la racine de | caractères                  |
   |                          | la distribution (où est placé le |                             |
   |                          | script *setup.py*), dans un      |                             |
   |                          | format Unix (séparé par des      |                             |
   |                          | slashs) dans un souci de         |                             |
   |                          | portabilité. Les fichiers de     |                             |
   |                          | code source peuvent être du C,   |                             |
   |                          | C++, SWIG (*.i*), des fichiers   |                             |
   |                          | de ressources spécifiques à la   |                             |
   |                          | plateforme ou tout autre reconnu |                             |
   |                          | par la commande **build_ext**    |                             |
   |                          | comme source d'une extension     |                             |
   |                          | Python.                          |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *include_dirs*           | Liste des répertoires où         | une liste de chaînes de     |
   |                          | chercher les fichiers d'entêtes  | caractères                  |
   |                          | C/C++ (en format Unix dans un    |                             |
   |                          | souci de portabilité).           |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *define_macros*          | Liste de macros à définir ;      | une liste de tuples         |
   |                          | chaque macro est définie à       |                             |
   |                          | l'aide d'un couple "(name,       |                             |
   |                          | value)", où *value* correspond   |                             |
   |                          | soit à la chaîne sur laquelle la |                             |
   |                          | macro doit être définie, soit à  |                             |
   |                          | "None" pour définir la macro sur |                             |
   |                          | aucune valeur particulière       |                             |
   |                          | (équivalent à "#define TRUC"     |                             |
   |                          | dans la source ou à "-DTRUC"     |                             |
   |                          | dans la ligne de commande du     |                             |
   |                          | compilateur C Unix.              |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *undef_macros*           | Liste de macros à ignorer        | une liste de chaînes de     |
   |                          | explicitement.                   | caractères                  |
   +--------------------------+----------------------------------+-----------------------------+
   | *library_dirs*           | Liste de répertoires à parcourir | une liste de chaînes de     |
   |                          | pour chercher les bibliothèques  | caractères                  |
   |                          | C/C++ lors de la phase d'édition |                             |
   |                          | de liens.                        |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *libraries*              | Liste de noms de bibliothèques à | une liste de chaînes de     |
   |                          | lier à la compilation. Pas de    | caractères                  |
   |                          | noms de fichiers ou de chemin.   |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *runtime_library_dirs*   | Liste de répertoires à parcourir | une liste de chaînes de     |
   |                          | pour les bibliothèques C/C++     | caractères                  |
   |                          | lors de la phase d'exécution.    |                             |
   |                          | Pour les extensions partagées,   |                             |
   |                          | c'est à ce moment que            |                             |
   |                          | l'extension est chargée.         |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *extra_objects*          | Liste des fichiers               | une liste de chaînes de     |
   |                          | supplémentaires à lier (par      | caractères                  |
   |                          | exemple les fichiers d'objets    |                             |
   |                          | non explicités dans les          |                             |
   |                          | 'sources', bibliothèque statique |                             |
   |                          | qui doit être explicitement      |                             |
   |                          | spécifiée, fichiers de           |                             |
   |                          | ressources binaires, etc. ).     |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *extra_compile_args*     | Toute information supplémentaire | une liste de chaînes de     |
   |                          | spécifique à la plate-forme et   | caractères                  |
   |                          | au compilateur à utiliser lors   |                             |
   |                          | de la compilation des fichiers   |                             |
   |                          | sources dans 'sources'. Pour les |                             |
   |                          | plates-formes et les             |                             |
   |                          | compilateurs où une ligne de     |                             |
   |                          | commande a du sens, il s'agit    |                             |
   |                          | généralement d'une liste         |                             |
   |                          | d'arguments de ligne de          |                             |
   |                          | commande, mais pour d'autres     |                             |
   |                          | plates-formes, cela peut être    |                             |
   |                          | n'importe quoi.                  |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *extra_link_args*        | Toute information supplémentaire | une liste de chaînes de     |
   |                          | spécifique à la plate-forme et   | caractères                  |
   |                          | au compilateur à utiliser lors   |                             |
   |                          | de la liaison de fichiers objets |                             |
   |                          | pour créer l'extension (ou pour  |                             |
   |                          | créer un nouvel interpréteur     |                             |
   |                          | Python statique). Interprétation |                             |
   |                          | similaire à celle de             |                             |
   |                          | *extra_compile_args*.            |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *export_symbols*         | Liste des symboles à exporter à  | une liste de chaînes de     |
   |                          | partir d'une extension partagée. | caractères                  |
   |                          | N'est pas utilisé sur toutes les |                             |
   |                          | plates-formes et n'est           |                             |
   |                          | généralement pas nécessaire pour |                             |
   |                          | les extensions Python, qui       |                             |
   |                          | exportent généralement           |                             |
   |                          | exactement un symbole : "init" + |                             |
   |                          | nom_de_l'extension.              |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *depends*                | Liste des fichiers dont dépend   | une liste de chaînes de     |
   |                          | l'extension.                     | caractères                  |
   +--------------------------+----------------------------------+-----------------------------+
   | *language*               | Langage de l'extension (par      | une chaîne de caractères    |
   |                          | exemple "'c'", "'c++'",          |                             |
   |                          | "'objc'"). Il sera détecté selon |                             |
   |                          | l'extension de la source s'il    |                             |
   |                          | n'est pas précisé.               |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *optional*               | Spécifie qu'un échec de          | un booléen                  |
   |                          | compilation dans l'extension ne  |                             |
   |                          | doit pas interrompre le          |                             |
   |                          | processus de compilation, mais   |                             |
   |                          | simplement ignorer l'extension.  |                             |
   +--------------------------+----------------------------------+-----------------------------+

class distutils.core.Distribution

   Une classe "Distribution" décrit comment compiler, installer et
   empaqueter un paquet logiciel Python.

   Voir la fonction "setup()" pour une liste des arguments de mots-
   clés acceptés par le constructeur *Distribution*. "setup()" crée
   une instance de Distribution.

   Modifié dans la version 3.7: "Distribution" avertit maintenant si
   les champs "classifiers", "keywords" et "platforms" ne sont pas
   spécifiés comme une liste ou une chaîne de caractères.

class distutils.core.Command

   Une classe "Command" (ou plutôt une instance d'une de ses sous-
   classes) implémente une commande *distutils* unique.


9.2. "distutils.ccompiler" — Classe de base CCompiler
=====================================================

Ce module fournit la classe de base abstraite pour les classes
"CCompiler".  Une instance de "CCompiler" peut être utilisée pour
toutes les étapes de compilation et de liaison nécessaires à la
compilation d'un projet unique. Des méthodes sont fournies pour
définir des options pour le compilateur --- définitions de macros,
inclusion des répertoires, des chemins de liens, des bibliothèques,
etc.

Ce module fournit les fonctions suivantes.

distutils.ccompiler.gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)

   Génère des options de liaison pour chercher dans les répertoires
   des bibliothèques et pour effectuer les liaisons avec des
   bibliothèques spécifiques.  *libraries* et *library_dirs* sont,
   respectivement, des listes de noms de bibliothèques (pas de noms de
   fichiers !) et de répertoires à rechercher.  Renvoie une liste
   d'options de ligne de commande utilisables avec certains
   compilateurs (en fonction des deux chaînes de format transmises).

distutils.ccompiler.gen_preprocess_options(macros, include_dirs)

   Génère les options du préprocesseur C ("-D", "-U", "-I") utilisées
   par au moins deux types de compilateurs : les compilateurs type
   Unix et Visual C++. *macros* est une liste de couples où "(name,)"
   est traité comme *non définie* ("-U"); "(name, value)" est traité
   comme *définie* ("-D"). *include_dirs* est la liste de noms de
   répertoires à ajouter au chemin de recherche du fichier d'en-tête
   ("-I"). Renvoie une liste d'options de ligne de commande pour les
   compilateurs Unix ou Visual C+++.

distutils.ccompiler.get_default_compiler(osname, platform)

   Détermine le compilateur par défaut a utiliser par une plateforme
   donnée.

   *osname* doit être l'un des noms d'OS Python standard (c'est-à-dire
   un des noms renvoyés par "os.name") et *platform* la valeur commune
   renvoyés par "sys.platform" pour la plate-forme en question.

   Les valeurs par défaut sont "os.name" et "sys.platform" si les
   paramètres ne sont pas fournis.

distutils.ccompiler.new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0)

   Fonction de génération produisant une instance d'une sous-classe
   CCompiler pour la combinaison plateforme/compilateur fournie. Par
   défaut, *plat* est le "os.name" (par exemple "'posix'", "'nt'"), et
   *compiler* est le compilateur par défaut pour cette plate-forme.
   Actuellement, seuls "'posix'" et "'nt'" sont gérés, et les
   compilateurs par défaut sont ceux qui gèrent une "interface Unix
   traditionnelle" ("UnixCCompiler") et Visual C++ ("MSVCCompiler").
   Notez qu'il est tout à fait possible de demander un objet
   compilateur Unix sous Windows, et un objet compilateur Microsoft
   sous Unix. Si vous fournissez une valeur pour *compiler*, *plat*
   est ignoré.

distutils.ccompiler.show_compilers()

   Affiche la liste des compilateurs disponibles (utilisés par
   l'option "--help-compiler" pour les commandes **build**,
   **build_ext**, **build_clib**).

class distutils.ccompiler.CCompiler([verbose=0, dry_run=0, force=0])

   La classe de base abstraite "CCompiler" définit l'interface qui
   doit être implémentée par des classes de compilateur concrètes.  La
   classe possède également quelques méthodes utilitaires utilisées
   par plusieurs classes de compilateurs.

   L'idée de base derrière une classe abstraite de compilateur est que
   chaque instance peut être utilisée pour toutes les étapes de
   compilation/lien dans la construction d'un seul projet.  Ainsi, les
   attributs communs à toutes ces étapes de compilation et de liaison
   (ce qui inclut les répertoires, les macros à définir, les
   bibliothèques à relier, etc.) sont des attributs de l'instance du
   compilateur.  Pour tenir compte des variations dans la façon dont
   chaque fichier est traité, la plupart de ces attributs peuvent être
   modifiés en fonction de chaque compilation ou de chaque lien.

   Le constructeur de chaque sous-classe crée une instance de l'objet
   *Compiler*. Les paramètres optionnels sont *verbose* (affiche plus
   d'information à l'exécution), *dry_run* (ne pas exécuter les
   étapes) et *force* (tout reconstruire, indépendamment des
   dépendances). Tous ces paramètres ont la valeur par défaut "0"
   (désactivé). Notez que vous ne voulez probablement pas instancier
   directement la classe "CCompiler" ou une de ses sous-classes.
   Utilisez plutôt la fonction génératrice
   "distutils.CCompiler.new_compiler()".

   Les méthodes suivantes vous permettent de modifier manuellement les
   options du compilateur de l'instance de la classe *Compiler*.

   add_include_dir(dir)

      Ajoute *dir* à la liste des répertoires qui sont recherchés pour
      les fichiers d'en-tête. Le compilateur est chargé de rechercher
      les répertoires dans l'ordre dans lequel ils sont fournis par
      des appels successifs à "add_include_dir()".

   set_include_dirs(dirs)

      Affecte la liste des répertoires qui seront recherchés à la
      valeur de *dirs* (une liste de chaînes). Remplace tous les
      appels précédents de "add_include_dir()" ; les appels suivants
      de "add_include_dir()" s'ajoutent à la liste transmise par
      "set_include_dirs()". Ceci n'affecte pas la liste des
      répertoires d'inclusion standard que le compilateur peut
      rechercher par défaut.

   add_library(libname)

      Ajoute *libname* à la liste des bibliothèques qui seront
      incluses dans tous les liens gérés par l'objet compilateur.
      Notez que *libname* ne *doit pas être* le nom d'un fichier
      contenant une bibliothèque, mais le nom de la bibliothèque elle-
      même : le nom du fichier sera déduit par l'éditeur de liens, le
      compilateur ou la classe de compilation (selon la plate-forme).

      L'éditeur de liens est chargé de lier les bibliothèques dans
      l'ordre dans lequel elles sont fournies à "add_library()" et/ou
      "set_libraries()".  Il est parfaitement valide de dupliquer les
      noms de bibliothèques ; l'éditeur de liens est chargé de créer
      des liens avec les bibliothèques autant de fois que les noms
      sont mentionnées.

   set_libraries(libnames)

      Affecte la liste des bibliothèques à inclure dans tous les liens
      gérés par l'objet compilateur avec la valeur de *libnames* (une
      liste des chaînes de caractères).  Ceci n'affecte pas les
      bibliothèques système standard que l'éditeur de liens peut
      inclure par défaut.

   add_library_dir(dir)

      Ajoute *dir* à la liste des répertoires qui seront recherchés
      pour les bibliothèques spécifiées dans "add_library()" et
      "set_libraries()".  L'éditeur de liens est chargé de rechercher
      les bibliothèques dans l'ordre dans lequel elles sont fournies à
      "add_library_dir()" et/ou "set_library_dirs()".

   set_library_dirs(dirs)

      Affecte la liste des répertoires de recherche de bibliothèque
      avec la valeur de *dirs* (une liste de chaînes de caractères).
      Cela n'affecte pas le chemin de recherche standard de la
      bibliothèque que l'éditeur de liens peut rechercher par défaut.

   add_runtime_library_dir(dir)

      Ajoute *dir* à la liste des répertoires qui seront recherchés
      par les bibliothèques partagées au moment de l'exécution.

   set_runtime_library_dirs(dirs)

      Affecte la liste des répertoires pour rechercher les
      bibliothèques partagées au moment de l'exécution à la valeur de
      *dirs* (une liste des chaînes de caractères).  Ceci n'affecte
      aucun chemin de recherche standard que l'éditeur de liens
      d'exécution peut rechercher par défaut.

   define_macro(name[, value=None])

      Définit une macro de préprocesseur pour toutes les compilations
      gérées par cet objet compilateur. Le paramètre optionnel *value*
      doit être une chaîne de caractères ; s'il n'est pas fourni,
      alors la macro sera définie sans valeur explicite et le résultat
      exact dépendra du compilateur utilisé.

   undefine_macro(name)

      Désactive une macro de préprocesseur pour toutes les
      compilations gérées par cet objet compilateur.  Si la même macro
      est définie par "define_macro()" et ensuite désactivée par un
      appel à "undefine_macro()", le dernier appel est prioritaire (y
      compris en cas de redéfinitions multiples).  Si la macro est
      redéfinie/désactivée par compilation (c'est-à-dire dans l'appel
      à "compile()"), alors cet appel prévaut.

   add_link_object(object)

      Ajoute *objet* à la liste des fichiers objets (ou analogues,
      tels que les fichiers de bibliothèque explicitement nommés ou la
      sortie des "compilateurs de ressources") à inclure dans chaque
      lien qui est géré par ce compilateur d'objets.

   set_link_objects(objects)

      Définit la liste des fichiers objets (ou analogues) à inclure
      dans chaque lien à la valeur de *objects*.  Ceci n'affecte pas
      les fichiers d'objets standard que l'éditeur de liens peut
      inclure par défaut (comme les bibliothèques système).

   Les méthodes suivantes offre des services pour l'auto-détection des
   options du compilateur. Elles offrent des fonctionnalités
   similaires à celles du programme GNU **autoconf**.

   detect_language(sources)

      Détecte le langage d'un fichier donné, ou d'une liste de
      fichiers. Utilise les attributs d'instance "language_map" (un
      dictionnaire) et "language_order" (une liste) pour faire le
      travail.

   find_library_file(dirs, lib[, debug=0])

      Recherche dans la liste des répertoires spécifiés un fichier de
      bibliothèque statique ou partagée *lib* et renvoie le chemin
      complet vers ce fichier. Si *debug* est vrai, recherche une
      version de débogage (si cela a du sens sur la plate-forme
      actuelle). Renvoie "None" si *lib* n'a pas été trouvé dans l'un
      des répertoires spécifiés.

   has_function(funcname[, includes=None, include_dirs=None, libraries=None, library_dirs=None])

      Renvoie un booléen indiquant si *funcname* est pris en charge
      sur la plate-forme courante.  Les arguments optionnels peuvent
      être utilisés pour enrichir l'environnement de compilation en
      fournissant des fichiers, des répertoires de fichiers, des
      bibliothèques, des répertoires de bibliothèques supplémentaires

   library_dir_option(dir)

      Renvoie l'option de compilation pour ajouter *dir* à la liste
      des répertoires recherchés pour les bibliothèques.

   library_option(lib)

      Renvoie l'option de compilation pour ajouter *lib* à la liste
      des bibliothèques liées à la bibliothèque partagée ou à
      l'exécutable.

   runtime_library_dir_option(dir)

      Renvoie l'option de compilation pour ajouter *dir* à la liste
      des répertoires recherchés par les bibliothèques d'exécution.

   set_executables(**args)

      Définit les exécutables (et leurs options) qui seront exécutés
      pour effectuer les différentes étapes de compilation.
      L'ensemble exact des exécutables qui peuvent être spécifiés ici
      dépend de la classe du compilateur (via l'attribut de classe
      *executables*), mais la plupart utilisent :

      +----------------+--------------------------------------------+
      | attribut       | description                                |
      |================|============================================|
      | *compiler*     | Le compilateur C/C++.                      |
      +----------------+--------------------------------------------+
      | *linker_so*    | L'éditeur de liens utilisé pour la         |
      |                | création d'objets ou de bibliothèques      |
      |                | partagées.                                 |
      +----------------+--------------------------------------------+
      | *linker_exe*   | L'éditeur de lien utilisé pour créer des   |
      |                | exécutables binaires.                      |
      +----------------+--------------------------------------------+
      | *archiver*     | Créateur de bibliothèque statique.         |
      +----------------+--------------------------------------------+

      Sur les plates-formes disposant d'un outil de ligne de commande
      (Unix, DOS/Windows), chacun de ces éléments est une chaîne qui
      sera fractionnée en un nom exécutable et, éventuellement, une
      liste d'arguments. Le fractionnement de la chaîne est réalisée
      selon la même procédure que celle appliquée par les *shells*
      Unix : les mots sont délimités par des espaces, mais les
      guillemets et les antislashs permettent de les ignorer. Voir
      "distutils.util.split_quoted()".

   Les méthodes suivantes permettent d'exécuter des étapes lors de
   processus de construction.

   compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])

      Compile un ou plusieurs fichiers source. Génère des fichiers
      objets (par exemple, transforme un fichier ".c" en fichier
      ".o").

      *sources* doit être une liste de noms de fichiers, généralement
      des fichiers C/C++, mais elle pourrait contenir n'importe quel
      fichier géré par un compilateur et une classe de compilateur
      (par exemple, "MSVCCompiler" peut gérer les fichiers de
      ressources dans *sources*). Renvoie une liste de noms de
      fichiers objet : un objet par nom de fichier dans *sources*.
      Selon les cas, tous les fichiers source ne seront pas forcément
      compilés, mais tous les noms de fichiers objet correspondants
      seront renvoyés.

      Si *output_dir* est donné, les fichiers objets seront placés à
      l'intérieur, tout en conservant leurs chemins relatifs.  Par
      exemple, le "truc/machin.c" compile normalement en
      "truc/machin.o" (pour une implémentation Unix) ; si *output_dir*
      a la valeur *build*, alors il compilera en
      "build/truc/machin.o".

      Le paramètre *macros*, s'il est donné, doit être une liste de
      définitions de macros.  Une définition de macro est soit un
      couple "(nom, valeur)", ou un singleton "(nom,)". Le premier
      définit une macro ; si la valeur est "None", la macro est
      définie sans valeur explicite.  L'utilisation d'un singleton
      désactive la macro.  Les définitions, redéfinitions ou
      désactivations ultérieures priment.

      *include_dirs* doit être une liste de chaînes de caractères
      contenant les répertoires à ajouter au chemin de recherche par
      défaut pour cette compilation uniquement.

      *debug* est un booléen ; si sa valeur est *vraie*, le
      compilateur est chargé d'afficher les symboles de débogage dans
      (ou à côté) du ou des fichiers objets.

      *extra_preargs* et *extra_postargs* dépendent de
      l'implémentation. Sur les plates-formes qui ont une ligne de
      commande (par exemple Unix, DOS/Windows), il s'agit très
      probablement de listes de chaînes de caractères. Ce sont des
      arguments supplémentaires à ajouter avant (*preargs*) et après
      (*postargs*) la ligne de commande du compilateur.  Sur d'autres
      plates-formes, consultez la documentation de la classe
      d'implémentation. Ces paramètres sont exposés pour permettre de
      sortir du cadre de la classe abstraite en cas de nécessité.

      *depends* est une liste de noms de fichiers dont dépendent
      toutes les cibles.  Si un fichier source est plus ancien qu'un
      fichier dans *depends*, alors le fichier source sera recompilé.
      Cela permet un suivi des dépendances à un niveau macro.

      Lève "CompileError" en cas d'échec.

   create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])

      Relie un ensemble d'éléments pour créer un fichier de
      bibliothèque statique. L'ensemble d'éléments se compose de la
      liste des fichiers d'objets fournis comme *objets*, des fichiers
      d'objets supplémentaires fournis à "add_link_object()" et/ou
      "set_link_objects()", des bibliothèques fournies à
      "add_library()" et/ou "set_libraries()" et les bibliothèques
      fournies à *libraries* (le cas échéant).

      *output_libname* doit être un nom de bibliothèque et non un nom
      de fichier ; le nom de fichier sera déduit du nom de
      bibliothèque.  *output_dir* est le répertoire dans lequel le
      fichier bibliothèque sera placé.

      *debug* est un booléen ; si sa valeur est *vraie*, les
      informations de débogage seront incluses dans la bibliothèque
      (notez que sur la plupart des plateformes, c'est à l'étape de
      compilation que ce paramètre est pris en compte : le paramètre
      *debug* est inclus ici pour assurer une cohérence).

      *target_lang* est le langage cible pour lequel les objets donnés
      sont compilés. Cela permet un traitement spécifique du temps de
      liaison dans certains langages.

      Lève "LibError" en cas d'échec.

   link(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])

      Relie un ensemble d'éléments pour créer un fichier exécutable ou
      une bibliothèque partagée.

      L'ensemble d'éléments se compose de la liste des fichiers objets
      fournis comme *objets*. *output_filename* devrait être un nom de
      fichier.  Si *output_dir* est fourni, *output_filename* lui est
      relatif (c'est-à-dire que *output_filename* peut  être un chemin
      vers un fichier ).

      *libraries* est une liste de bibliothèques avec lesquelles il
      est possible d'établir des liens.  Ce sont des noms de
      bibliothèques, pas des noms de fichiers, puisqu'ils sont
      traduits en noms de fichiers d'une manière spécifique à la
      plate-forme (par exemple *truc* devient "libtruc.a" sous Unix et
      "truc.lib" sous DOS/Windows).  Cependant, ils peuvent inclure un
      chemin, ce qui signifie que l'éditeur de liens cherchera dans ce
      chemin spécifique plutôt que de rechercher tous les emplacements
      standard.

      *library_dirs*, s'il est fourni, doit être une liste de
      répertoires à rechercher pour les bibliothèques qui ont été
      spécifiées comme des bibliothèques pures (c'est-à-dire sans
      aucun répertoire).  Celles-ci s'ajoutent aux valeurs par défaut
      du système et à celles fournies à "add_library_dir()" et/ou
      "set_library_dirs()".  *runtime_library_dirs* est une liste de
      répertoires qui seront intégrés dans la bibliothèque partagée et
      utilisés pour rechercher d'autres bibliothèques partagées dont
      elle dépend à l'exécution.  (Ceci est probablement valable
      uniquement sous UNIX.)

      *export_symbols* est une liste de symboles que la bibliothèque
      partagée va exporter. (Ceci est probablement valable uniquement
      sous Window.)

      *debug* s'utilise comme pour "compile()" et
      "create_static_lib()", avec la nuance qu'elle a ici une
      importance sur la plupart des plateformes (par opposition à
      "create_static_lib()" qui inclut une option *debug* pour se
      conformer à l'interface).

      *extra_preargs* et *extra_postargs* s'utilisent comme pour
      "compile()" (sauf bien sûr qu'ils fournissent des arguments à la
      ligne de commande pour l'éditeur de liens spécifique utilisé).

      *target_lang* est le langage cible pour lequel les objets donnés
      sont compilés. Cela permet un traitement spécifique du temps de
      liaison dans certains langages.

      Lève "LinkError" en cas d'échec.

   link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None])

      Lie un exécutable.  *output_progname* est le nom de l'exécutable
      du fichier, tandis que *objects* est une liste de noms de
      fichiers objets à lier. Les autres arguments sont les mêmes que
      pour la méthode "link()".

   link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])

      Lie une bibliothèque partagée. *output_libname* est le nom de la
      bibliothèque de sortie, tandis que *objects* est une liste de
      noms de fichiers d'objets à lier.  Les autres arguments sont les
      mêmes que pour la méthode "link()".

   link_shared_object(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])

      Lie un objet partagé. *output_filename* est le nom de l'objet
      partagé qui sera créé, tandis que *objects* est une liste de
      noms de fichiers d'objets à lier. Les autres arguments sont les
      mêmes que pour la méthode "link()".

   preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])

      Prétraitement d'un seul fichier source C/C++, désigné dans
      *source*. La sortie du traitement est écrite dans un fichier
      nommé *output_file*, ou dans *stdout* si *output_file* n'est pas
      fourni. *macros* est une liste de définitions de macros comme
      pour "compile()", qui vont s'ajouter aux macros définies avec
      "define_macro()" et "undefine_macro()". *include_dirs* est une
      liste de noms de répertoires qui seront ajoutés à la liste par
      défaut, de la même manière que "add_include_dir()".

      Lève  "PreprocessError" en cas d'échec.

   Les méthodes utilitaires suivantes sont définies par la classe
   "CCompiler", à l'usage des différentes sous-classes concrètes.

   executable_filename(basename[, strip_dir=0, output_dir=''])

      Renvoie le nom de fichier de l'exécutable pour un  *nom de base*
      donné.  Généralement, pour les plates-formes non Windows, c'est
      le même nom que le nom de base, tandis que sur Windows
      l'extension ".exe" sera ajouté.

   library_filename(libname[, lib_type='static', strip_dir=0, output_dir=''])

      Renvoie le nom de fichier pour le nom de bibliothèque donné sur
      la plate-forme actuelle. Sous Unix, une bibliothèque avec un
      *lib_type* de type "static" sera généralement de la forme
      "liblibname.a", tandis qu'un *lib_type* de type "dynamic" sera
      de la forme "liblibname.so".

   object_filenames(source_filenames[, strip_dir=0, output_dir=''])

      Renvoie le nom des fichiers objets pour les fichiers sources
      donnés. *source_filenames* doit être une liste de noms de
      fichiers.

   shared_object_filename(basename[, strip_dir=0, output_dir=''])

      Renvoie le nom d'un fichier objet partagé pour le nom de fichier
      *basename*.

   execute(func, args[, msg=None, level=1])

      Invoque "distutils.util.execute()". Cette méthode invoque une
      fonction Python *func* avec les arguments *args* , après
      journalisation et prise en compte de l'option *dry_run*.

   spawn(cmd)

      Invoque "distutils.util.spawn()".  Invoque un processus externe
      pour exécuter la commande donnée.

   mkpath(name[, mode=511])

      Invoque "distutils.dir_util.mkpath()". Crée un répertoire et
      tous les répertoires parents manquants.

   move_file(src, dst)

      Invoque "distutils.file_util.move_file()". Renomme *src* en
      *dst*.

   announce(msg[, level=1])

      Écrit un message en utilisant "distutils.log.debug()".

   warn(msg)

      Écris un message d'avertissement *msg* dans la sortie d'erreur
      standard.

   debug_print(msg)

      Si l'option *debug* est activée pour cette instance de
      "CCompiler", affiche *msg* sur la sortie standard, sinon  rien
      ne s'affiche.


9.3. "distutils.unixccompiler" — Compilateur C Unix
===================================================

Ce module fournit la classe "UnixCCompiler", une sous-classe de la
classe "CCompiler" qui gère les compilateurs C ayant une interface en
ligne de commande conforme au standard Unix :

* macros définies avec l'option "-Dname[=value]".

* macros désaffectées avec "-Uname".

* inclut les répertoires de recherche spécifiés avec l'option "-Idir".

* bibliothèques spécifiées avec l'option "-llib"

* répertoires de recherche des bibliothèques définis avec l'option
  "-Ldir".

* compilation gérée par **cc** (ou similaire) exécutable avec l'option
  "-c" compile ".c" vers ".o".

* édition de liens pour une bibliothèque statique gérée par le
  programme en ligne de commande **ar** (éventuellement avec le
  programme **ranlib**).

* édition de liens pour une bibliothèque gérée par **cc** "-shared".


9.4. "distutils.msvccompiler" — Compilateur Microsoft
=====================================================

Ce module fournit "MSVCCompiler", une implémentation de la classe
abstraite "CCompiler" pour Microsoft Visual Studio. Généralement, les
modules d'extension doivent être compilés avec le même compilateur que
celui utilisé pour compiler Python. Pour Python 2.3 et les versions
antérieures, le compilateur était Visual Studio 6. Pour Python 2.4 et
2.5, le compilateur est Visual Studio .NET 2003.

La classe "MSVCCompiler" sélectionnera normalement le bon compilateur,
éditeur de liens, etc. Pour remplacer ces choix, les variables
d'environnement *DISTUTILS_USE_SDK* et *MSSdk* doivent être toutes les
deux définies. *MSSdk* indique que l'environnement courant a été
configuré par le script "SetEnv.Cmd" du kit de développement logiciel
(*SDK*), ou que les variables d'environnement ont été enregistrées
lorsque le kit a été installé ; *DISTUTILS_USE_SDK* indique que
l'utilisateur de *distutils* a choisi explicitement de remplacer le
compilateur utilisé par "MSVCCompiler".


9.5. "distutils.bcppcompiler" — Compilateur Borland
===================================================

Ce module fournit "BorlandCCompiler", une sous-classe de la classe
abstraite "CCompiler" classe pour le compilateur Borland C++.


9.6. "distutils.cygwincompiler" — Compilateur Cygwin
====================================================

Ce module fournit la classe "CygwinCCompiler", une sous-classe de la
classe "UnixCCompiler" qui gère *Cygwin*, le portage du compilateur
GNU C sur Windows.  Il contient également la classe Mingw32CCompiler
qui gère le portage *mingw32* de GCC (comme *cygwin* en mode *no-
cygwin*).


9.7. "distutils.archive_util" — Utilitaires d'archivage
=======================================================

Ce module fournit quelques fonctions pour créer des fichiers
d'archive, tels que des archives aux formats *tarballs* ou *zipfiles*.

distutils.archive_util.make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])

   Crée un fichier d'archive (par exemple "zip" ou "tar").
   *base_name* est le nom du fichier à créer, sans extension
   spécifique indiquant le format. *format* est le format d'archive :
   un parmi "zip", "tar", "gztar", "bztar", "xztar", "xztar", ou
   "ztar". *root_dir* est un répertoire qui sera le répertoire racine
   de l'archive ; c'est-à-dire que le programme se positionne dans
   *root_dir* avant de créer l'archive.  *base_dir* est le répertoire
   à partir duquel se lance l'archivage ; par exemple, *base_dir* est
   le préfixe commun à tous les fichiers et répertoires de l'archive.
   *root_dir* et *base_dir* sont tous deux par défaut dans le
   répertoire courant. Renvoie le nom du fichier archive.

   Modifié dans la version 3.5: Ajout du support des fichiers "xztar".

distutils.archive_util.make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])

   Crée une archive (compressée en option) sous forme de fichier au
   format *tar* à partir de tous les fichiers dans et sous *base_dir*.
   *compress* doit être "'gzip'" (par défaut), "'bzip2'", "'xz'",
   "'compress'" ou "None".  Pour la méthode "'compress'" l'utilitaire
   de compression nommé par **compress** doit être sur le chemin de
   recherche par défaut, donc c'est sans doute spécifique à Unix.  Le
   fichier *tar* de sortie sera nommé "base_dir.tar", avec l'extension
   de compression appropriée (".gz", ".bz2", ".xz" ou ".Z").  Renvoie
   le nom du fichier de sortie.

   Modifié dans la version 3.5: Ajout du support de la compression
   "xz".

distutils.archive_util.make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])

   Crée un fichier zip à partir de tous les fichiers dans et sous
   *base_dir*.  Le fichier zip de sortie est nommé *base_name* +
   ".zip".  Utilise soit le module Python "zipfile" (si disponible) ou
   l'utilitaire InfoZIP "zip" (s'il est installé et trouvé sur le
   chemin de recherche par défaut).  Si aucun des deux outils n'est
   disponible, lève "DistutilsExecError".   Renvoie le nom du fichier
   zip de sortie.


9.8. "distutils.dep_util" — Vérification des dépendances
========================================================

Ce module fournit des fonctions permettant d'effectuer des tests de
dépendance simples, basés sur les horodatages de fichiers et de
groupes de fichiers, ainsi que des fonctionnalités entièrement basées
sur ces analyses de dépendance par rapport aux horodatages.

distutils.dep_util.newer(source, target)

   Renvoie la valeur *true* si *source* existe et a été modifiée plus
   récemment que *target*, ou si *source* existe et *target* n'existe
   pas. Renvoie la valeur *false* si les deux existent et que *target*
   est aussi ou plus récent que *source*. Lève "DistutilsFileError" si
   *source* n'existe pas.

distutils.dep_util.newer_pairwise(sources, targets)

   Parcourt en parallèle deux listes de noms de fichiers, en vérifiant
   si chaque source est plus récente que sa cible correspondante.
   Renvoie une paire de listes (*sources*, *cibles*) où la source est
   plus récente que la cible, selon la sémantique de "newer()".

distutils.dep_util.newer_group(sources, target[, missing='error'])

   Renvoie la valeur *True* si *target* a une date dépassée par
   rapport à un fichier figurant dans *sources* En d'autres termes, si
   *target* existe et est plus récente que chaque fichier dans
   *sources*, renvoie la valeur *False* ; sinon renvoie la valeur
   *True*. *missing* contrôle ce qui se passe lorsqu'un fichier source
   est manquant ; la valeur par défaut ("'error'") est de lever une
   exception "OSError" à l'intérieur de "os.stat()" ; si *missing*
   vaut "'ignore'",tout fichier source manquant est ignoré. Si
   *missing* vaut "'newer'", tout fichier source manquant indique que
   *target* n'est plus à jour (ce qui est utile en mode *dry-run* :
   cela permet d'exécuter des commandes qui ne fonctionneraient pas
   parce que des entrées sont manquantes sans les exécuter
   réellement).


9.9. "distutils.dir_util" --- Opérations sur l'arborescence des répertoires
===========================================================================

Ce module fournit des fonctions pour travailler sur des répertoires et
des arborescences de répertoires.

distutils.dir_util.mkpath(name[, mode=0o777, verbose=0, dry_run=0])

   Crée un répertoire et tous les répertoires parents manquants.  Si
   le répertoire existe déjà (ou si *name* est la chaîne vide,
   c'est-à-dire le répertoire courant, qui existe bien sûr), alors ne
   fait rien.  Lève "DistutilsFileError" s'il n'est pas possible de
   créer un répertoire en cours de route (par exemple, un sous-chemin
   existe, mais est un fichier plutôt qu'un répertoire).  Si *verbose*
   est vrai, affiche un résumé d'une ligne de chaque *mkdir* vers
   *stdout*.  Renvoie la liste des répertoires réellement créés.

distutils.dir_util.create_tree(base_dir, files[, mode=0o777, verbose=0, dry_run=0])

   Crée tous les répertoires vides sous *base_dir* nécessaires pour
   placer *files*. *base_dir* est le nom d'un répertoire qui n'existe
   pas encore nécessairement ; *files* est une liste de noms de
   fichiers relatifs à *base_dir*. *base_dir* + la partie répertoire
   de chaque fichier dans *files* est créée si elle n'existe pas déjà.
   Les options *mode*, *verbose* et *dry_run* sont les mêmes que pour
   "mkpath()".

distutils.dir_util.copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])

   Copie une arborescence de répertoires entière *src* vers un nouvel
   emplacement *dst*.  *src* et *dst* doivent tous deux être des noms
   de répertoire.  Si *src* n'est pas un répertoire, lève
   "DistutilsFileError".  Si *dst* n'existe pas, il est créé avec
   "mkpath()".  Le résultat final de la copie est que chaque fichier
   dans *src* est copié dans *dst*, et les répertoires sous *src* sont
   récursivement copiés dans *dst*. Renvoie la liste des fichiers qui
   ont été copiés ou qui auraient pu l'être, en utilisant leur nom de
   sortie. La valeur renvoyée n'est pas affectée par *update* ou
   *dry_run* : c'est tout simplement la liste de tous les fichiers
   sous *src*, avec les noms modifiés pour être sous *dst*.

   Les modes *preserve_mode* et *preserve_times* sont les mêmes que
   pour "distutils.file_util.copy_file()" ; il faut savoir que cela ne
   concerne que les fichiers réguliers, et non les dossiers.  Si
   *preserve_symlinks* est vrai, les liens symboliques seront copiés
   en tant que liens symboliques (sur les plateformes qui les gèrent
   !); sinon (par défaut), la destination du lien sera copiée.
   *update* et *verbose* sont les mêmes que pour "copy_file()".

   Les fichiers dans *src* qui commencent par ".nfs" sont ignorés
   (plus d'informations sur ces fichiers sont disponibles dans la
   réponse *D2* de la page NFS FAQ page).

   Modifié dans la version 3.3.1: Les fichiers NFS sont ignorés.

distutils.dir_util.remove_tree(directory[, verbose=0, dry_run=0])

   Supprime récursivement *directory* et tous les fichiers et
   répertoires en dessous. Toutes les erreurs sont ignorées (sauf si
   *verbose* est vrai, elles sont affichées sur "sys.stdout").


9.10. "distutils.file_util" — Traitements mono-fichier
======================================================

Ce module contient quelques fonctions de service pour travailler sur
des fichiers individuels.

distutils.file_util.copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])

   Copie le fichier *src* dans *dst*. Si *dst* est un répertoire,
   alors *src* y est copié avec le même nom ; sinon, il faut que ce
   soit un nom de fichier. Si *preserve_mode* est vrai (par défaut),
   le mode du fichier (son type et ses bits de permission, ou ce qui
   est analogue sur la plate-forme actuelle) sont copiés. Si
   *preserve_times* est vrai (par défaut), les horodatages de la
   dernière modification et du dernier accès sont également copiés. Si
   *update* est vrai, *src* ne peut être copié que si *dst* n'existe
   pas, ou si *dst* existe mais est plus ancien que *src*.

   *link* permets de créer des liens physiques (en utilisant
   "os.link()") ou symboliques (en utilisant "os.symlink()") au lieu
   de les copier : paramétrez la valeur a "'hard'" ou "'sym'" ; si
   elle vaut "None" (par défaut), les fichiers sont copiés. Ne
   définissez pas *link* sur les systèmes qui ne les gèrent pas :
   "copy_file()" ne vérifie pas si des liens symboliques ou physiques
   sont disponibles.  La fonction "_copy_file_contents()" est utilisée
   pour copier le contenu des fichiers.

   Renvoie un couple "(dest_name, copied)" : *dest_name* est le nom
   réel du fichier de sortie, et *copied* est vrai si le fichier a été
   copié (ou aurait été copié, si *dry_run* est vrai).

distutils.file_util.move_file(src, dst[, verbose, dry_run])

   Déplace le fichier *src* vers *dst*. Si *dst* est un répertoire, le
   fichier y est déplacé avec le même nom ; sinon, *src* est
   simplement renommé *dst*.  Renvoie le nouveau nom complet du
   fichier.

   Avertissement:

     Gère les déplacements inter-périphériques sous Unix en utilisant
     "copy_file()". Qu'en est-il sur les autres systèmes ?

distutils.file_util.write_file(filename, contents)

   Crée un fichier appelé *filename* et y écrit *contents* (une
   séquence de chaînes sans terminaison de ligne).


9.11. "distutils.util" — Autres fonctions de service
====================================================

Ce module contient d'autres éléments qui ne correspondent à aucun
autre module de service.

distutils.util.get_platform()

   Renvoie une chaîne qui identifie la plate-forme courante.  Ceci est
   utilisé pour distinguer les répertoires de compilation spécifiques
   aux plates-formes et les distributions construites spécifiques aux
   plates-formes.  Cette chaîne inclut en règle générale le nom et la
   version de l'OS et l'architecture (tels que fournis par la fonction
   "os.uname()" ). Bien que l'information exacte dépend de l'OS, par
   exemple, sous Linux, la version noyau ne joue pas un grand rôle.

   Exemples de valeurs renvoyées :

   * "linux-i586"

   * "linux-alpha"

   * "solaris-2.6-sun4u"

   Pour les plates-formes qui ne sont pas POSIX, renvoie simplement
   "sys.platform".

   Pour les systèmes Mac OS X, la version du système d'exploitation
   correspond à la version minimale sur laquelle les binaires pourront
   être exécutés (c'est-à-dire la valeur de "MACOSX_DEPLOYMENT_TARGET"
   pendant la compilation de Python), et non la version du système
   actuel.

   Pour les binaires universels construits sur Mac OS X, la valeur de
   l'architecture reflète l'état du binaire universel au lieu de celle
   de l'architecture du processeur en cours. Pour les binaires
   universels 32 bits, l'architecture est "fat",  pour les binaires
   universels 64 bits, l'architecture est "fat64", et pour les
   binaires universels 4 voies, l'architecture est "universelle". A
   partir de Python 2.7 et Python 3.2, l'architecture "fat3" est
   utilisée pour une compilation universelle à 3 voies (*ppc*, *i386*,
   *x86_64*) et "intel" est utilisée pour une compilation universelle
   avec les architectures *i386* et *x86_64*

   Exemples de valeurs renvoyées sous Mac OS X :

   * "macosx-10.3-ppc"

   * "macosx-10.3-fat"

   * "macosx-10.5-universal"

   * "macosx-10.6-intel"

distutils.util.convert_path(pathname)

   Renvoie un chemin *pathname* qui fonctionne sur le système de
   fichiers natif. Par exemple, il sépare le chemin sur */* et le
   recompose en utilisant le séparateur de répertoires courant. Cela
   est nécessaire parce que les noms de fichiers dans les scripts
   d'installations sont toujours fournis dans le style Unix, et
   doivent être convertis dans la convention du système avant d'être
   utilisé par le système de fichiers.  Lève "ValueError" sur les
   systèmes non UNIX si *pathname* commence ou se termine par une
   barre oblique (*slash* en anglais).

distutils.util.change_root(new_root, pathname)

   Renvoie un chemin *pathname* préfixé avec *new_root*. Si *pathname*
   est relatif, c`est l'équivalent de
   "os.path.join(new_root,pathname)" Sinon, il faut rendre *pathname*
   relatif et joindre les deux, ce qui est dangereux sous DOS/Windows.

distutils.util.check_environ()

   Vérifie que 'os.environ' possède toutes les variables
   d'environnement utilisables dans les fichiers de configuration, les
   options en ligne de commande, etc.  À l'heure actuelle, cela
   comprend :

   * "HOME". Répertoire d’accueil de l'utilisateur (Unix uniquement)

   * "PLAT". Description de la plate-forme actuelle, y compris le
     matériel et le l'OS (voir "get_platform()")

distutils.util.subst_vars(s, local_vars)

   Exécute la substitution de variable de style shell/Perl sur *s*.
   Chaque occurrence de "$" suivie d'un nom est considérée comme une
   variable, et la variable est remplacée par la valeur trouvée dans
   le dictionnaire *local_vars*, ou dans "os.environ" si elle ne se
   trouve pas dans *local_vars*. *os.environ* est d'abord
   vérifié/étendu pour garantir qu'elle contient certaines valeurs :
   voir "check_environ()". Lève "ValueError" pour toute variable non
   trouvée dans *local_vars* ou "os.environ".

   Remarquez qu'il ne s'agit pas d'une fonction d'interpolation de
   chaîne à part entière. Une "$variable" valide ne peut être composée
   que de lettres majuscules et minuscules, de chiffres et d'un tiret
   bas. Aucune syntaxe de type {} ou () pour indiquer des variables
   n'est disponible.

distutils.util.split_quoted(s)

   Sépare une chaîne de caractères selon les règles de type shell Unix
   pour les guillemets et les barres obliques inverses. En bref : les
   mots sont délimités par des espaces, tant que ces espaces ne sont
   pas échappées par une barre oblique inversée, ou à l'intérieur
   d'une chaîne guillemets. Les guillemets simples et doubles sont
   équivalents, et les caractères entre guillemets peuvent être
   échappés à l'aide d'une barre oblique inversée.  La barre oblique
   inversée est supprimée de toute séquence d'échappement à deux
   caractères, ne laissant que le caractère échappé.  Les caractères
   guillemets sont supprimés de toute chaîne de caractères entre
   guillemets.  Renvoie une liste de mots.

distutils.util.execute(func, args[, msg=None, verbose=0, dry_run=0])

   Exécute une action qui affecte le monde extérieur (par exemple,
   écrire dans le système de fichiers).  De telles actions sont
   spéciales car elles sont désactivées par l'option *dry_run*.  Cette
   méthode s'occupe de tout. Vous devez simplement fournir la fonction
   à appeler avec un couple d'argument lui correspondant et un message
   facultatif à afficher.

distutils.util.strtobool(val)

   Convertit une chaîne de caractères représentant une valeur
   booléenne en "1" (si elle est évaluée comme vraie) ou "0" (si elle
   est évaluée comme fausse).

   Les valeurs *vraies* sont , "y", "yes", "t", "true", "on"  et  "1".
   Les valeurs *fausses* sont "n", "no", "f", "false", "off" et "0".
   Lève "ValueError" si *val* est autre chose.

distutils.util.byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])

   Effectue une compilation vers du *bytecode* Python à partir d'un
   ensemble de fichiers sources Python dans un fichier ".pyc" dans un
   sous répertoire "__pycache__" (voir **PEP 3147** et **PEP 488**).
   *py_files* est une liste de fichiers à compiler ; tous les fichiers
   qui ne se terminent pas par ".py" sont ignorés en silence.
   *optimize* doit être l'un des éléments suivants :

   * "0": ne pas optimiser

   * "1": optimisation normale (comme "python -O")

   * "2": optimisation supplémentaire (comme "python -OO")

   Si *force* est vrai, tous les fichiers sont recompilés
   indépendamment des horodatages.

   Le nom du fichier source encodé dans chaque fichier *bytecode* est
   par défaut le nom présent dans la liste des noms de fichiers source
   *py_files* ; vous pouvez modifier dynamiquement ses noms avec
   *prefix* et *basedir*. *prefix* est une chaîne de caractères qui
   sera supprimée de chaque nom de fichier source, et *base_dir* est
   un nom de répertoire qui sera préfixé au nom (après que le
   *prefixe* soit supprimé).  Vous pouvez choisir de fournir l'un ou
   l'autre (ou les deux) paramètres : *prefixe* et *base_dir*.

   Si *dry_run* est vrai, ne fait rien qui puisse affecter le système
   de fichiers.

   La compilation binaire se fait soit directement dans l'interpréteur
   courant avec le module standard "py_compile", soit indirectement en
   écrivant un script temporaire et en l'exécutant.  Normalement, vous
   devez laisser "byte_compile()" choisir d'utiliser la compilation
   directe ou non (voir le code-source pour les détails).  Le
   paramètre *direct* est utilisé par le script généré en mode
   indirect ; à moins que vous ne sachiez ce que vous faites, laissez
   le paramètre à "None" (Aucun).

   Modifié dans la version 3.2.3: Crée des fichiers ".pyc" avec un
   sous-répertoire "import magic tag" dans leur nom, dans le sous
   répertoire "__pycache__" plutôt que dans le répertoire courant,
   sans tag.

   Modifié dans la version 3.5: Crée des fichiers ".pyc" selon la
   **PEP 488**.

distutils.util.rfc822_escape(header)

   Renvoie une version de *header* traitée avec les échappements
   compatibles avec les en-têtes **RFC 822**, en s'assurant qu'il y a
   8 espaces après chaque nouvelle ligne. Notez qu'il ne fait aucune
   autre modification de la chaîne de caractères.


9.12. "distutils.dist" — La classe Distribution
===============================================

Ce module fournit la classe "Distribution", qui représente le module
*distribution* en cours de construction/installation/distribution.


9.13. "distutils.extension" — La classe Extension
=================================================

Ce module fournit la classe "Extension", utilisée pour décrire les
modules d'extension C/C++ dans les scripts de configuration.


9.14. "distutils.debug" — Mode de débogage du module *Distutils*
================================================================

Ce module fournit l'option *DEBUG*.


9.15. "distutils.errors" — Exceptions du module *Distutils*
===========================================================

Fournit les exceptions utilisées par les modules de *Distutils*.
Notez que les modules *Distutils* peuvent soulever des exceptions
standard ; en particulier, "SystemExit" est généralement levée pour
les erreurs qui sont manifestement de la responsabilité de
l'utilisateur final (ex : mauvais argument en ligne de commande).

Ce module est utilisable avec la syntaxe "from ... import *" ; il
n'exporte que des symboles dont le nom commence par "Distutils" et se
termine par "Error".


9.16. "distutils.fancy_getopt" --- Encapsulation du module *getopt* standard
============================================================================

Ce module est une encapsulation du module standard "getopt" qui
apporte les fonctionnalités supplémentaires suivantes :

* Les options *short* et *long* sont liées entre elles.

* Les options ont des pages d'aide, donc "fancy_getopt()" pourrait
  potentiellement créer un résumé d'utilisation complet

* Les options définissent les attributs à partir d'un objet fourni.

* Les options booléennes peuvent avoir des "alias négatifs" --- par
  exemple l'option "-quiet" est *l'alias négatif* de "--verbose",
  l'option "-quiet" sur la ligne de commande met *verbose* à faux.

distutils.fancy_getopt.fancy_getopt(options, negative_opt, object, args)

   Encapsulation de la fonction "getopt". *options* est une liste de
   triplets "(long_option, short_option, help_string)" comme décrit
   dans le constructeur de la classe "FancyGetopt". *negative_opt*
   doit être un dictionnaire associant les noms des options aux noms
   des options, la clé et la valeur doivent être dans la liste
   *options*. *object* est un objet qui sera utilisé pour stocker des
   valeurs (voir la méthode "getopt()" de la classe  "FancyGetopt").
   *args* est la liste des arguments. Utilise "sys.argv[1 :]" si
   "None" est passé à *args*.

distutils.fancy_getopt.wrap_text(text, width)

   Ajoute des retours à la ligne à *texte* de manière à ce que la
   largeur soit inférieure à *largeur*.

class distutils.fancy_getopt.FancyGetopt([option_table=None])

   La liste *option_table* est constituée de triplets : "(long_option,
   short_option, help_string*)"

   Si une option prend un argument, sa *long_option* doit se terminer
   par "'='". *short_option* doit être un seul caractère, jamais
   "':'`'. *option_courte* doit être ``None" si *long_option* n'a pas
   de *short_option* correspondante. Tous les triplets d'options
   doivent avoir des options longues.

La classe "FancyGetopt" fournit les méthodes suivantes :

FancyGetopt.getopt([args=None, object=None])

   Analyse les options de ligne de commande des arguments. Les stocke
   en tant qu'attributs de *objet*.

   Si *args* est "None" ou n'est pas définie, utilise "sys.argv[1:]".
   Si *object* est "None" ou n'est pas définie, créer une nouvelle
   instance de la classe "OptionDummy" , stocke les valeurs d'options
   dans l'instance et renvoie un couple "(args, object)". Si *objet*
   est fourni, il est modifié sur place et "getopt()" renvoie
   simplement *args*; dans les deux cas, Les arguments *args* renvoyés
   sont une copie modifiée de la liste *args* transmise, qui est n'est
   pas modifiée.

FancyGetopt.get_option_order()

   Renvoie la liste des couples "(option, valeur)" traités par
   l'exécution précédente de "getopt()". Déclenche "RuntimeError" si
   "getopt()" n'a pas encore été appelée.

FancyGetopt.generate_help([header=None])

   Génère un texte d'aide (une liste de chaînes, une par ligne de
   sortie suggérée) de la liste d'options pour l'objet de la classe
   "FancyGetopt".

   S'il est fourni, affiche l'en-tête *header* en haut de l'aide.


9.17. "distutils.filelist" — La classe *FileList* liste des fichiers
====================================================================

Ce module fournit la classe "FileList", utilisée pour parcourir le
système de fichiers et construire des listes de fichiers.


9.18. "distutils.log" --- Journalisation basée sur le style de la PEP 282
=========================================================================


9.19. "distutils.spawn" — Crée un sous-processus
================================================

Ce module offre la fonction "spawn()", une interface avec diverses
fonctions spécifiques à la plate-forme pour lancer un autre programme
dans un sous-processus. Inclut également "find_executable()" pour
rechercher le chemin d'accès pour un nom d'exécutable donné.


9.20. "distutils.sysconfig" --- Informations de configuration du système
========================================================================

Le module "distutils.sysconfig" donne accès aux informations de
configuration bas niveau de Python.  Les variables de configuration
spécifiques disponibles dépendent de la plate-forme et de la
configuration. Les variables spécifiques dépendent du processus de
compilation de la version *spécifique* de Python en cours d'exécution.
Les variables sont celles qui se trouvent dans le fichier "Makefile"
et dans les entêtes de configuration installés avec Python sur des
systèmes Unix.  Le fichier des entêtes de configuration s'appelle
"pyconfig.h" pour les versions de Python commençant par 2.2, et
"config.h" pour les versions antérieures de Python.

Quelques fonctions supplémentaires sont fournies pour effectuer des
manipulations utiles pour d'autres parties du paquet "distutils".

distutils.sysconfig.PREFIX

   Le résultat de "os.path.normpath(sys.prefix)".

distutils.sysconfig.EXEC_PREFIX

   Le résultat de "os.path.normpath(sys.exec_prefix)".

distutils.sysconfig.get_config_var(name)

   Retourne la valeur d'une seule variable.  C'est l'équivalent de
   "get_config_vars().get(name)".

distutils.sysconfig.get_config_vars(...)

   Retourne un ensemble de définitions de variables.  S'il n'y a pas
   d'arguments, cela renvoie un dictionnaire qui associe les noms des
   variables de configuration aux valeurs.  Si des arguments sont
   spécifiés, ils doivent être des chaînes de caractères, et la valeur
   renvoyée sera une séquence donnant les valeurs correspondantes. Si
   un nom donné n'a pas de valeur correspondante, la valeur "None"
   sera utilisée pour cette variable.

distutils.sysconfig.get_config_h_filename()

   Renvoie le nom complet du chemin d'accès de l'en-tête de
   configuration.  Pour Unix, c'est l'en-tête généré par le script
   **configure** ; pour les autres plates-formes, l'en-tête provient
   directement de la distribution source Python.  Le fichier est un
   fichier texte spécifique à la plate-forme.

distutils.sysconfig.get_makefile_filename()

   Renvoie le nom complet du chemin d'accès du fichier "Makefile"
   utilisé pour construire Python.  Pour Unix, c'est le fichier généré
   par le script **configure**. La définition pour les autres
   plateformes varie.  S'il existe, il s'agit d'un fichier texte
   spécifique à la plate-forme. Cette fonction n'est utile que sur les
   plates-formes POSIX.

distutils.sysconfig.get_python_inc([plat_specific[, prefix]])

   Renvoie le répertoire pour les fichiers d'inclusion C standards ou
   dépendants de la plate-forme.  Si *plat_specific* est vrai, le
   répertoire *include* dépendant de la plate-forme est renvoyé ; si
   la valeur est *faux* ou *None*, le répertoire indépendant de la
   plate-forme est renvoyé. Si *prefix* est donné, il est utilisé soit
   comme préfixe au lieu de "PREFIX", soit comme préfixe d'exécution
   au lieu de "EXEC_PREFIX" si *plat_specific* est vrai.

distutils.sysconfig.get_python_lib([plat_specific[, standard_lib[, prefix]]])

   Renvoie le répertoire pour l'installation de la bibliothèque
   standard ou dépendante de la plate-forme.  Si *plat_specific* est
   vrai, le répertoire *include* dépendant de la plate-forme est
   renvoyé ; si la valeur est *faux* ou *None*, le répertoire
   indépendant de la plate-forme est renvoyé.  Si *prefix* est donné,
   il est utilisé soit comme préfixe au lieu de "PREFIX", soit comme
   préfixe d'exécution au lieu de "EXEC_PREFIX" si *plat_specific* est
   vrai. Si *standard_lib* est vrai, le répertoire de la bibliothèque
   standard est renvoyé plutôt que le répertoire d'installation des
   extensions tierces.

La fonction suivante est uniquement destinée à être utilisée dans le
paquet "distutils".

distutils.sysconfig.customize_compiler(compiler)

   Exécute toute personnalisation spécifique à la plate-forme d'une
   instance "distutils.ccompiler.CCompiler".

   Cette fonction n'est nécessaire que sous Unix pour le moment, mais
   doit être appelée de manière cohérente pour supporter la
   compatibilité ascendante.  Elle insère des informations qui varient
   d'une version à l'autre d'Unix et qui sont stockées dans le fichier
   Python "Makefile".  Ces informations comprennent le compilateur,
   les options du compilateur et de l'éditeur de liens sélectionnés,
   ainsi que l'extension utilisée par l'éditeur de liens pour les
   objets partagés.

Cette fonction est encore plus spéciale, et ne devrait être utilisée
que dans les procédures de compilation de Python.

distutils.sysconfig.set_python_build()

   Informe le module "distutils.sysconfig" qu'il est utilisé dans le
   cadre du processus de compilation de Python.  Cela change beaucoup
   d'emplacements relatifs pour les fichiers, ce qui les place dans la
   zone de compilation plutôt que dans un interpréteur Python
   installé.


9.21. "distutils.text_file" — La classe TextFile
================================================

Ce module fournit la classe "TextFile", qui donne une interface aux
fichiers texte qui s'occupe (optionnellement) de supprimer les
commentaires, d'ignorer les lignes vides et de joindre les lignes avec
des antislash.

class distutils.text_file.TextFile([filename=None, file=None, **options])

   Cette classe fournit un objet de type fichier qui se charge de tout
   ce que vous voulez généralement faire lors du traitement d'un
   fichier texte ayant une syntaxe ligne par ligne : Suppression des
   commentaires (tant que "#" est votre caractère de commentaire),
   passer les lignes vides, joindre des lignes adjacentes en échappant
   la nouvelle ligne (les lignes se terminant par une antislash),
   supprime les espace blancs avant et après le texte etc.  Toutes ces
   fonctions sont optionnelles et peuvent être commandées
   indépendamment.

   La classe fournit une méthode "warn()" pour pouvoir générer des
   messages d'avertissement qui renvoie le numéro de ligne physique,
   même si la ligne logique en question couvre plusieurs lignes
   physiques.  Fournit également "unreadline()" pour implémenter un
   système prospectif ligne par ligne.

   Les instances de "TextFile" sont créées soit avec *filename*, soit
   avec *file* ou bien les deux. "RuntimeError" est levé si les deux
   valent "None". *filename* doit être une chaîne de caractères, et
   *file* un objet fichier (ou quelque chose qui fournit les méthodes
   "readline()" et "close()"). Il est recommandé de fournir au moins
   *filename*, afin que "TextFile" puisse l'inclure dans les messages
   d'avertissement.  Si *file* n'est pas fourni, "TextFile" crée son
   propre fichier en utilisant la fonction "open()".

   Les options sont toutes booléennes et affectent les valeurs
   renvoyées par "readline()".

   +--------------------+----------------------------------+-----------+
   | Nom des options    | description                      | default   |
   |====================|==================================|===========|
   | *strip_comments*   | Supprime les caractères à partir | *true*    |
   |                    | de "'#'" jusqu'à la fin de la    |           |
   |                    | ligne, ainsi que tout espace     |           |
   |                    | blanc menant au premier "'#'"    |           |
   |                    | --- à moins qu'il ne soit        |           |
   |                    | échappé par une antislash        |           |
   +--------------------+----------------------------------+-----------+
   | *lstrip_ws*        | Efface les espaces blancs en     | *false*   |
   |                    | début de chaque ligne avant de   |           |
   |                    | la renvoyer.                     |           |
   +--------------------+----------------------------------+-----------+
   | *rstrip_ws*        | Efface les espaces blancs de fin | *true*    |
   |                    | de ligne (y compris le           |           |
   |                    | terminateur de ligne !) de       |           |
   |                    | chaque ligne avant de la         |           |
   |                    | renvoyer.                        |           |
   +--------------------+----------------------------------+-----------+
   | *skip_blanks*      | Ignore les lignes qui sont vides | *true*    |
   |                    | *après* la suppression des       |           |
   |                    | commentaires et des espaces.     |           |
   |                    | (Si *lstrip_ws* et *rstrip_ws*   |           |
   |                    | sont tous les deux faux, alors   |           |
   |                    | certaines lignes peuvent être    |           |
   |                    | composées uniquement d'espaces : |           |
   |                    | elles ne seront pas ignorées,    |           |
   |                    | même si *skip_blanks* est vrai.  |           |
   +--------------------+----------------------------------+-----------+
   | *join_lines*       | Si sur la ligne, une antislash   | *false*   |
   |                    | est le dernier caractère et que  |           |
   |                    | ce caractère n'est pas le        |           |
   |                    | caractère de nouvelle ligne.     |           |
   |                    | Joint la ligne suivante pour     |           |
   |                    | former une ligne logique. Si N   |           |
   |                    | lignes consécutives se terminent |           |
   |                    | par une antislash, alors N+1     |           |
   |                    | lignes physiques seront liées    |           |
   |                    | pour former une seul ligne       |           |
   |                    | logique.                         |           |
   +--------------------+----------------------------------+-----------+
   | *collapse_join*    | Supprime les espaces blancs des  | *false*   |
   |                    | lignes qui sont jointes à leur   |           |
   |                    | prédécesseur. n'est utile que    |           |
   |                    | que si "(join_lines and not      |           |
   |                    | lstrip_ws)".                     |           |
   +--------------------+----------------------------------+-----------+

   Notez que puisque *rstrip_ws* peut effacer la fin de la ligne, la
   sémantique de "readline()" doit être différente de celle de la
   méthode standard "readline()" des objets fichier !  En particulier,
   "readline()" renvoie "None" pour indiquer la fin du fichier: une
   chaîne vide peut être juste une ligne blanche (ou une ligne
   entièrement blanche), si *rstrip_ws* est vrai mais pas si
   *skip_blanks* est faux.

   open(filename)

      Ouvre un nouveau fichier *filename*.  Remplace tous les
      arguments du constructeur *file* ou *filename*.

   close()

      Ferme le fichier courant et oublie toutes les informations
      connues à son sujet (y compris le nom du fichier et le numéro de
      la ligne courante).

   warn(msg[, line=None])

      Affiche (vers *stderr*) un message d'avertissement lié à la
      ligne logique courante dans le fichier courant. Si la ligne
      logique courante dans le fichier s'étend sur plusieurs lignes
      physiques, l'avertissement se réfère à une plage de lignes
      physiques, telles que ""lignes 3-5"". Si *line* est fourni, il
      remplace le numéro de la ligne courante ; il peut s'agir d'une
      liste ou d'un couple pour indiquer une plage de lignes
      physiques, ou d'un entier pour une seule ligne physique.

   readline()

      Lit et renvoie une seule ligne logique à partir du fichier
      courant (ou à partir d'un tampon interne si les lignes ont déjà
      été marqué comme non lue avec "unreadline()").  Si l'option
      *join_lines* est vraie, cela peut impliquer la lecture de
      plusieurs lignes physiques concaténées en une seule chaîne.  Met
      à jour le numéro de la ligne courante. Appeler "warn()" après
      "readline()" émet donc un avertissement sur la ou les lignes
      physiques qui viennent d'être lues. Renvoie "None" à la fin du
      fichier, puisque la chaîne vide peut se produire si *rstrip_ws*
      est vrai mais pas si *strip_blanks* est faux.

   readlines()

      Lit et renvoie la liste de toutes les lignes logiques restant
      dans le fichier courant. Met à jour le numéro de la ligne
      courante à la dernière ligne du fichier.

   unreadline(line)

      Insère la ligne *line* (une chaîne de caractères) dans un tampon
      interne qui sera vérifié par les futurs appels de "readline()".
      Utile pour implémenter un analyseur prospectif ligne par ligne.
      Notez que les lignes qui sont "non lues" avec "unreadline()" ne
      sont ensuite pas traitées de nouveau (espace blancs, ou autre)
      quand elles sont lues avec "readline()". Si plusieurs appels
      sont faits à "unreadline()" avant un appel à "readline()", les
      lignes sont renvoyées dans l'ordre de la plus récente première à
      la plus ancienne.


9.22. "distutils.version" — Classes de numéros de version
=========================================================


9.23. "distutils.cmd" --- Classe de base abstraite pour les commandes *Distutils*
=================================================================================

Ce module fournit la classe de base abstraite "Command".

class distutils.cmd.Command(dist)

   Classe de base abstraite pour définir les classes de commandes, les
   "ouvrières" de *Distutils*. Une analogie utile pour les classes de
   commandes est de les considérer comme des sous-routines avec des
   variables locales appelées *options*.  Les options sont déclarées
   dans "initialiser_options()" et définies (compte tenu de leur
   valeur finale) dans "finalize_options()", qui doivent être définies
   pour chaque classe de commande.  La distinction entre les deux est
   nécessaire parce que les valeurs des options peuvent venir de
   l'extérieur (ligne de commande, fichier de configuration, ....), et
   toutes les options dépendantes d'autres options doivent être
   calculées après que ces options externes aient été traitées --- ce
   qui explique "finalize_options()". Le corps de la sous-routine, où
   s'effectue tout le travail est basé sur les valeurs de ses options,
   est la méthode "run()", qui doit être implémentée par chaque classe
   de commande.

   Le constructeur prend un seul argument, *dist*, une instance de
   "Distribution".


9.24. Créer une nouvelle commande *Distutils*
=============================================

Cette section décrit les étapes pour créer une nouvelle commande
*Distutils*.

Une nouvelle commande doit résider dans un module du package
"distutils.command". Il existe un exemple de modèle dans ce répertoire
nommé "command_template". Copiez ce fichier dans un nouveau module
portant le même nom que la nouvelle commande que vous implémentez. Ce
module doit implémenter une classe portant le même nom que le module
(et la commande). Par exemple, pour créer la commande "peel_banana"
(afin que les utilisateurs puissent exécuter "setup.py peel_banana"),
vous devez copier le fichier "commande_template" dans
"distutils/command/peel_banana.py", puis l'éditer pour qu'il
implémente la classe "peel_banana", une sous-classe de la classe
"distutils.cmd.Command".

Les sous-classes de la classe "Command" doivent définir les méthodes
suivantes.

Command.initialize_options()

   Définit des valeurs par défaut pour toutes les options que cette
   commande gère. Notez que ces valeurs par défaut peuvent être
   remplacées par d'autres commandes, par le script d'installation,
   par des fichiers de configuration ou par la ligne de commande. Ce
   n'est donc pas l'endroit idéal pour introduire des dépendances
   entre les options. En règle générale, les méthodes suivantes
   "initialize_options()" ne font que des assignations de type
   "self.truc = None".

Command.finalize_options()

   Définit les valeurs finales pour toutes les options que cette
   commande gère. Cette méthode doit toujours être appelée le plus
   tard possible, c'est-à-dire après que toutes les affectations des
   options de la ligne de commande ou que d'autres commandes ont été
   faites. C'est donc l'endroit idéal pour introduire des dépendances
   d'options : si *truc* dépend de *machin*, alors il est sûr de
   mettre *truc* de *machin* aussi longtemps que *truc* a toujours la
   même valeur qui lui a été attribué par "initialize_options()".

Command.run()

   La raison d'être d'une commande : exécuter l'action programmée en
   étant contrôlée par les options initialisées dans
   "initialize_options()", personnalisées par d'autres commandes, par
   le script de configuration, par la ligne de commande et les
   fichiers de configuration, puis finalisée dans
   "finalize_options()". Toutes les interactions avec le système de
   fichiers et la sortie du terminal doivent être effectuées par
   "run()".

Command.sub_commands

   *sub_commands* formalise la notion de "famille" de commandes, par
   exemple. "install" est le parent des sous-commandes "install_lib",
   "install_headers", etc. Le parent d'une famille de commandes
   définit *sub_commands* en tant qu'attribut de classe ; c'est une
   liste de couples "(command_name, predicate)", avec *command_name*
   le nom de la commande et *predicate* une fonction, une chaîne ou
   "None". *predicate* est une méthode de la commande parent qui
   détermine si la commande correspondante est applicable dans la
   situation actuelle. Par exemple : "install_headers" n'est
   applicable que s'il existe des fichiers d'en-tête C à installer. Si
   *predicate* est "None", cette commande est toujours effectuée.

   *sub_commands* est généralement défini à la *fin* d'une classe, car
   les prédicats peuvent être des méthodes de la classe, ils doivent
   donc déjà avoir été définis. L'exemple canonique est la commande
   **install**.


9.25. "distutils.command" — Commandes *Distutils* individuelles
===============================================================


9.26. "distutils.command.bdist" — Construit un installateur binaire
===================================================================


9.27. "distutils.command.bdist_packager" --- Classe de base abstraite pour empaqueteurs
=======================================================================================


9.28. "distutils.command.bdist_dumb" --- Construit un installateur passif (*dumb*)
==================================================================================


9.29. "distutils.command.bdist_msi" --- Construit un installateur Microsoft
===========================================================================

class distutils.command.bdist_msi.bdist_msi

   Construit un installateur Windows Installeur (*.msi*)

   Dans la plupart des cas, l'installateur "bdist_msi" est un meilleur
   choix que l'installateur "bdist_wininst", car il gère mieux les
   plates-formes *Win64*, et permet en plus aux administrateurs
   d'effectuer des installations non interactives ainsi que des
   installations via des stratégies de groupe.


9.30. "distutils.command.bdist_rpm" --- Construit une distribution binaire au format Redhat RPM et SRPM
=======================================================================================================


9.31. "distutils.command.bdist_wininst" --- Construit un installateur Windows
=============================================================================


9.32. "distutils.command.sdist" — Construit une distribution source
===================================================================


9.33. "distutils.command.build" --- Construit tous les fichiers d'un paquet
===========================================================================


9.34. "distutils.command.build_clib" --- Construit toutes les bibliothèques C d'un paquet
=========================================================================================


9.35. "distutils.command.build_ext" --- Construit toutes les extensions d'un paquet
===================================================================================


9.36. "distutils.command.build_py" --- Construit les fichiers *.py/.pyc* d'un paquet
====================================================================================

class distutils.command.build_py.build_py

class distutils.command.build_py.build_py_2to3

   Implémentation alternative de *build_py* qui exécute également la
   bibliothèque de conversion *2to3* sur chaque fichier *.py* qui va
   être installé. Pour l'utiliser dans un fichier *setup.py* pour une
   distribution conçue pour fonctionner avec *Python 2.x* et *3.x*,
   ajouter :

      try:
          from distutils.command.build_py import build_py_2to3 as build_py
      except ImportError:
          from distutils.command.build_py import build_py

   à votre *setup.py* et, plus tard :

      cmdclass = {'build_py': build_py}

   à l'appel de *setup()*.


9.37. "distutils.command.build_scripts" --- Construit les scripts d'un paquet
=============================================================================


9.38. "distutils.command.clean" --- Nettoie un dossier de compilation d'un paquet
=================================================================================

Cette commande supprime les fichiers temporaires créés par la commande
**build** et ses sous-commandes, comme les fichiers objets compilés
intermédiaires.  Avec l'option "--all", le répertoire de compilation
sera supprimé.

Les modules d'extension construits sur place ne seront pas effacés,
car ils ne sont pas dans le répertoire *build*.


9.39. "distutils.command.config" --- Effectue la configuration d'un paquet
==========================================================================


9.40. "distutils.command.install" — Installe un paquet
======================================================


9.41. "distutils.command.install_data" --- Installe les fichiers de données d'un paquet
=======================================================================================


9.42. "distutils.command.install_headers" --- Installe les fichiers d'en-tête C/C++ d'un paquet
===============================================================================================


9.43. "distutils.command.install_lib" --- Installe les fichiers de bibliothèque à partir d'un paquet
====================================================================================================


9.44. "distutils.command.install_scripts" --- Installe les fichiers de script d'un paquet
=========================================================================================


9.45. "distutils.command.register" --- Enregistre un module dans l'Index des paquets Python (*Python Package Index* ou *PyPI* en anglais)
=========================================================================================================================================

La commande "register" enregistre le paquet dans l'index des paquets
Python. Plus de détails à ce sujet dans la **PEP 301**.


9.46. "distutils.command.check" --- Vérifie les méta-données d'un paquet
========================================================================

La commande "check" effectue des tests sur les méta-données d'un
paquet. Par exemple, elle vérifie que toutes les méta-données requises
sont fournies lorsque les arguments sont passés à la fonction
"setup()".
