10. Référence de l’API

10.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	a list of strings; valid classifiers are listed on 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 is a file that will be run with execfile() sys.argv[0] will be replaced with script for the duration of the call. script_args is a list of strings; if supplied, sys.argv[1:] will be replaced by script_args for the duration of the call.

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

The Extension class describes a single C or C++ extension module in a setup script. It accepts the following keyword arguments in its constructor

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	list of macros to define; each macro is defined using a 2-tuple (name, value), where value is either the string to define it to or None to define it without a particular value (equivalent of #define FOO in source or -DFOO on Unix C compiler command line)	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

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.

class distutils.core.Command

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

10.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)

Generate C pre-processor options (-D, -U, -I) as used by at least two types of compilers: the typical Unix compiler and Visual C++. macros is the usual thing, a list of 1- or 2-tuples, where (name,) means undefine (-U) macro name, and (name, value) means define (-D) macro name to value. include_dirs is just a list of directory names to be added to the header file search path (-I). Returns a list of command-line options suitable for either Unix compilers or 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()

Print list of available compilers (used by the --help-compiler options to 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.

10.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 defined with -Dname[=value]

• macros undefined with -Uname

• include search directories specified with -Idir

• libraries specified with -llib

• library search directories specified with -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).

• link shared library handled by cc -shared

10.4. distutils.msvccompiler — Compilateur Microsoft

This module provides MSVCCompiler, an implementation of the abstract CCompiler class for Microsoft Visual Studio. Typically, extension modules need to be compiled with the same compiler that was used to compile Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python 2.4 and 2.5, the compiler is Visual Studio .NET 2003. The AMD64 and Itanium binaries are created using the Platform SDK.

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.

10.5. distutils.bcppcompiler — Compilateur Borland

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

10.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).

10.7. distutils.emxccompiler — OS/2 EMX Compiler

This module provides the EMXCCompiler class, a subclass of UnixCCompiler that handles the EMX port of the GNU C compiler to OS/2.

10.8. 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])

Create an archive file (eg. zip or tar). base_name is the name of the file to create, minus any format-specific extension; format is the archive format: one of zip, tar, ztar, or gztar. root_dir is a directory that will be the root directory of the archive; ie. we typically chdir into root_dir before creating the archive. base_dir is the directory where we start archiving from; ie. base_dir will be the common prefix of all files and directories in the archive. root_dir and base_dir both default to the current directory. Returns the name of the archive file.

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

“Create an (optional compressed) archive as a tar file from all files in and under base_dir. compress must be 'gzip' (the default), 'compress', 'bzip2', or None. Both tar and the compression utility named by compress must be on the default program search path, so this is probably Unix-specific. The output tar file will be named base_dir.tar, possibly plus the appropriate compression extension (.gz, .bz2 or .Z). Return the output filename.

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.

10.9. 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'])

Return true if target is out-of-date with respect to any file listed in sources. In other words, if target exists and is newer than every file in sources, return false; otherwise return true. missing controls what we do when a source file is missing; the default ('error') is to blow up with an OSError from inside os.stat(); if it is 'ignore', we silently drop any missing source files; if it is 'newer', any missing source files make us assume that target is out-of-date (this is handy in « dry-run » mode: it’ll make you pretend to carry out commands that wouldn’t work because inputs are missing, but that doesn’t matter because you’re not actually going to run the commands).

10.10. 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=0777, 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=0777, 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])

Copy an entire directory tree src to a new location dst. Both src and dst must be directory names. If src is not a directory, raise DistutilsFileError. If dst does not exist, it is created with mkpath(). The end result of the copy is that every file in src is copied to dst, and directories under src are recursively copied to dst. Return the list of files that were copied or might have been copied, using their output name. The return value is unaffected by update or dry_run: it is simply the list of all files under src, with the names changed to be under 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().

Files in src that begin with .nfs are skipped (more information on these files is available in answer D2 of the NFS FAQ page.

Modifié dans la version 2.7.4: 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).

10.11. 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).

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

Return a string that identifies the current platform. This is used mainly to distinguish platform-specific build directories and platform-specific built distributions. Typically includes the OS name and version and the architecture (as supplied by “os.uname()”), although the exact information included depends on the OS; eg. for IRIX the architecture isn’t particularly important (IRIX only runs on SGI hardware), but for Linux the kernel version isn’t particularly important.

Exemples de valeurs renvoyées :

• linux-i586

• linux-alpha

• solaris-2.6-sun4u

• irix-5.3

• irix64-6.2

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])

Byte-compile a collection of Python source files to either .pyc or .pyo files in the same directory. py_files is a list of files to compile; any files that don’t end in .py are silently skipped. optimize must be one of the following:

• 0 - don’t optimize (generate .pyc)

• 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).

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.

10.13. distutils.dist — La classe Distribution

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

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

10.15. distutils.debug — Mode de débogage du module Distutils

Ce module fournit l’option DEBUG.

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

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

• boolean options can have « negative aliases » — eg. if --quiet is the « negative alias » of --verbose, then --quiet on the command line sets verbose to false.

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.

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

10.19. distutils.log — Journalisation basée sur le style de la PEP 282

10.20. 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é.

10.21. 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é.

10.22. 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	strip from '#' to end-of- line, as well as any whitespace leading up to the '#'—unless it is escaped by a backslash	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.

10.23. distutils.version — Classes de numéros de version

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

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

10.26. distutils.command — Commandes Distutils individuelles

10.27. distutils.command.bdist — Construit un installateur binaire

10.28. distutils.command.bdist_packager — Classe de base abstraite pour empaqueteurs

10.29. distutils.command.bdist_dumb — Construit un installateur passif (dumb)

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

10.31. distutils.command.bdist_rpm — Construit une distribution binaire au format Redhat RPM et SRPM

10.32. distutils.command.bdist_wininst — Construit un installateur Windows

10.33. distutils.command.sdist — Construit une distribution source

10.34. distutils.command.build — Construit tous les fichiers d’un paquet

10.35. distutils.command.build_clib — Construit toutes les bibliothèques C d’un paquet

10.36. distutils.command.build_ext — Construit toutes les extensions d’un paquet

10.37. distutils.command.build_py — Construit les fichiers .py/.pyc d’un paquet

10.38. distutils.command.build_scripts — Construit les scripts d’un paquet

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

10.40. distutils.command.config — Effectue la configuration d’un paquet

10.41. distutils.command.install — Installe un paquet

10.42. distutils.command.install_data — Installe les fichiers de données d’un paquet

10.43. distutils.command.install_headers — Installe les fichiers d’en-tête C/C++ d’un paquet

10.44. distutils.command.install_lib — Installe les fichiers de bibliothèque à partir d’un paquet

10.45. distutils.command.install_scripts — Installe les fichiers de script d’un paquet

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

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