9. Référence de l'API

Voir aussi

Arguments nouveaux et modifiés de *setup.py* dans setuptools

Le projet setuptools ajoute de nouvelles capacités à la fonction setup et à d'autres API, il rend l'API cohérente entre les différentes versions de Python ; il est donc recommandé de l'utiliser plutôt que d'utiliser directement les distutils.

Note

Cette page est conservée uniquement jusqu'à ce que la documentation setuptool sur https://setuptools.readthedocs.io/en/latest/setuptools.html couvre de manière indépendante toutes les informations pertinentes actuellement incluses ici.

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 ; s'il est 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 nommés de setup()
config	S'arrête une fois que les fichiers de configuration ont été parcourus (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é parcourue (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 n-uplets
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

Modifié dans la version 3.8: Sur Unix, les extensions C ne sont plus liées à libpython sauf sur Android et Cygwin.

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 nommé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 : le compilateur Unix classique 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 à 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 ordinaire renvoyée 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és.

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 offrent 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é 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 objects. output_filename doit ê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 relatif 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 Windows.)

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.

For macOS systems the OS version reflects the minimal version on which binaries will run (that is, the value of MACOSX_DEPLOYMENT_TARGET during the build of Python), not the OS version of the current system.

For universal binary builds on macOS the architecture value reflects the universal binary status instead of the architecture of the current processor. For 32-bit universal binaries the architecture is fat, for 64-bit universal binaries the architecture is fat64, and for 4-way universal binaries the architecture is universal. Starting from Python 2.7 and Python 3.2 the architecture fat3 is used for a 3-way universal build (ppc, i386, x86_64) and intel is used for a universal build with the i386 and x86_64 architectures

Examples of returned values on macOS:

• macosx-10.3-ppc

• macosx-10.3-fat

• macosx-10.5-universal

• macosx-10.6-intel

Pour AIX, à partir de Python 3.9, une chaîne de caractères est renvoyée commençant par aix, puis des champs additionnels (séparés par '-') qui représentent les valeurs combinées de la version d'AIX accompagnée du numéro de publication et du « niveau de technologie » (premier champ), la date de la version (deuxième champ), et taille en bits (troisième champ). En Python 3.8 et avant, seul un champ additionnel avec la version d'AIX et le numéro de publication étaient renvoyés.

Exemples de valeurs renvoyées sur AIX :

• aix-5307-0747-32 # build 32-bit sur AIX oslevel -s: 5300-07-00-0000

• aix-7105-1731-64 # build 64-bit sur AIX oslevel -s: 7100-05-01-1731

• aix-7.2 # Ancienne forme renvoyée par Python 3.8 et version précédentes

Modifié dans la version 3.9: Le format de chaîne de caractères de plateforme AIX inclut désormais la génération, la date de construction et la taille en bits de l'architecture matérielle de l'ABI.

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.

Note that this is not a full-fledged string interpolation function. A valid $variable can consist only of upper and lower case letters, numbers and an underscore. No { } or ( ) style quoting is available.

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 standards ; 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 ':'. short_option doit être None si l'option n'a pas de forme courte 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ée une nouvelle instance de la classe OptionDummy, stocke les valeurs d'options dans l'instance et renvoie un couple (args, object). Si object 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 n'est pas elle-même 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

Obsolète depuis la version 3.10: distutils.sysconfig has been merged into sysconfig.

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)

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

The following functions are deprecated together with this module and they have no direct replacement.

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 False 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 False 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 antislashs.

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 : supprimer les commentaires (tant que # est votre caractère de commentaire), passer des lignes vides, joindre les lignes adjacentes (les lignes se terminant par un antislash) en une seule nouvelle ligne, supprimer les blancs avant et après le texte. 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 un 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, un 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 un antislash, alors N+1 lignes physiques seront liées pour former une seule ligne logique.	false
collapse_join	Supprime les espaces blancs des lignes qui sont jointes à leur prédécesseur ; n'est utile 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 fichiers ! 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ées comme non lues 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

Obsolète depuis la version 3.9: Utilisez bdist_wheel (paquet au format wheel) à la place.

Construit un installateur Windows Installeur (.msi)

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

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

9.32. distutils.command.build — Construit tous les fichiers d'un paquet

9.33. distutils.command.build_clib — Construit toutes les bibliothèques C d'un paquet

9.34. distutils.command.build_ext — Construit toutes les extensions d'un paquet

9.35. 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.36. distutils.command.build_scripts — Construit les scripts d'un paquet

9.37. 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.38. distutils.command.config — Effectue la configuration d'un paquet

9.39. distutils.command.install — Installe un paquet

9.40. distutils.command.install_data — Installe les fichiers de données d'un paquet

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

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

9.43. distutils.command.install_scripts — Installe les fichiers de script d'un paquet

9.44. 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.45. 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().