Ce document est relatif à une vieille version de Python qui n'est plus soutenue. Mettez à jour votre version et lisez Bienvenue sur la documentation de la version stable actuelle de Python.

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

`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, incluant n'importe quel paquet --- c-à-d pas un nom de fichier ou de chemin mais un nom Python séparé par des points. | une chaîne de caractères
  sources | Listes des noms de fichier des sources, relatifs à la racine de 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. | une liste de chaînes de caractères
  include_dirs | Liste des répertoires où chercher les fichiers d'entêtes C/C++ (en format Unix dans un souci de portabilité). | une liste de chaînes de caractères
  define_macros | Liste de macros à définir ; 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. | une liste de tuples
  undef_macros | Liste de macros à ignorer explicitement. | une liste de chaînes de caractères
  library_dirs | Liste de répertoires à parcourir pour chercher les bibliothèques C/C++ lors de la phase d'édition de liens. | une liste de chaînes de caractères
  libraries | Liste de noms de bibliothèques à lier à la compilation. Pas de noms de fichiers ou de chemin. | une liste de chaînes de caractères
  runtime_library_dirs | Liste de répertoires à parcourir pour les bibliothèques C/C++ lors de la phase d'exécution. Pour les extensions partagées, c'est à ce moment que l'extension est chargée. | une liste de chaînes de caractères
  extra_objects | Liste des fichiers supplémentaires à lier (par 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. ). | une liste de chaînes de caractères
  extra_compile_args | Toute information supplémentaire spécifique à la plate-forme et 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. | une liste de chaînes de caractères
  extra_link_args | Toute information supplémentaire spécifique à la plate-forme et 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. | une liste de chaînes de caractères
  export_symbols | Liste des symboles à exporter à partir d'une extension partagée. 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. | une liste de chaînes de caractères
  depends | Liste des fichiers dont dépend l'extension. | une liste de chaînes de caractères
  language | Langage de l'extension (par exemple `'c'`, `'c++'`, `'objc'`). Il sera détecté selon l'extension de la source s'il n'est pas précisé. | une chaîne de caractères
  optional | Spécifie qu'un échec de compilation dans l'extension ne doit pas interrompre le processus de compilation, mais simplement ignorer l'extension. | un booléen

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 de `'#'` jusqu'à la fin de la ligne, ainsi que tout espace blanc menant au premier `'#'` --- à moins qu'il ne soit échappé par une antislash | true
  lstrip_ws | Efface les espaces blancs en début de chaque ligne avant de la renvoyer. | false
  rstrip_ws | Efface les espaces blancs de fin de ligne (y compris le terminateur de ligne !) de chaque ligne avant de la renvoyer. | true
  skip_blanks | Ignore les lignes qui sont vides *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. | true
  join_lines | Si sur la ligne, une antislash 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. | false
  collapse_join | Supprime les espaces blancs des lignes qui sont jointes à leur prédécesseur. n'est utile que que si `(join_lines and not lstrip_ws)`. | false

  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()`.