1. Introduction à 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.

Ce document traite de l'utilisation de Distutils pour distribuer des modules Python, en se concentrant sur le rôle de développeur/distributeur : si vous cherchez des informations sur l'installation de modules Python, vous devriez vous référer au chapitre Installation des modules python (Version historique).

1.1. Concepts et Terminologie

Utiliser Distuils est assez simple, à la fois pour les développeurs de module et pour les utilisateurs/administrateurs qui installent des modules tiers. En tant que développeur, vos responsabilités (en plus d'écrire du code solide, bien documenté et bien testé, bien entendu !) sont :

• écrire un script d'installation (setup.py par convention) ;

• (optionnel) écrire un fichier de configuration pour l'installation ;

• créer une distribution source ;

• (optionnel) créer une ou plusieurs distributions compilées (binaires).

Chacune de ces tâches est couverte dans ce document.

Tous les développeurs de modules n'ont pas accès à une multitude de plateformes, donc on ne peut pas exiger d'eux qu'ils créent une multitude de distributions compilées. On s'attend à ce que certains intermédiaires, appelés packagers, prennent en charge ce besoin. Les packagers vont prendre les sources des distributions publiées par les développeurs de modules, les construire sur on ou plusieurs plateformes, et publier les distributions compilées résultantes. Ainsi, les utilisateurs sur les plateformes les plus populaires vont pouvoir installer la plupart des modules Python de la façon la plus naturelle qui soit pour leur plateforme, sans avoir à exécuter de script ou à compiler du code.

1.2. Un exemple simple

Le script d'installation est habituellement assez simple, même s'il n'y a pas de limite à ce qu'il peut faire (il est écrit en Python, n'est-ce pas ?). Veillez d'ailleurs à ne pas surcharger ce script avec des opérations coûteuses car, contrairement aux scripts de configuration façon Autoconf, le script d'installation peut être amené à être exécuté plusieurs fois au cours de la compilation et de l'installation du module.

Si tout ce que vous voulez est de distribuer un module appelé foo, contenu dans un fichier foo.py, alors votre script d'installation peut se résumer à :

from distutils.core import setup
setup(name='foo',
      version='1.0',
      py_modules=['foo'],
      )

Quelques observations :

• la plupart des informations que vous fournissez à Distutils sont fournies en tant que qu'arguments nommés à la fonction setup();

• ces arguments nommés tombent dans deux catégories : métadonnées du paquet (nom, numéro de version) et des informations sur le contenu du paquet paquet (une liste de purs modules Python, dans ce cas) ;

• les modules sont listés par nom de module, plutôt que par nom de fichier (le cas est similaire pour les paquets et extensions) ;

• il est recommandé de fournir un minimum de métadonnées, en particulier votre nom, une adresse de courriel et une URL pour le projet (voir section Rédaction du script setup.py pour un exemple).

Pour créer une distribution source pour ce module, il faut créer un script d'installation, setup.py, contenant le code ci-dessus, et exécuter cette commande depuis un terminal :

python setup.py sdist

Pour Windows, ouvrez une invite de commande (Démarrer ‣ Accessoires) et changez la commande en :

setup.py sdist

sdist va créer un fichier d'archive (p. ex. une archive tar sur Unix, un fichier ZIP sous Windows) contenant votre script d'installation setup.py, et votre module foo.py. Le fichier d'archive va être nommé foo-1.0.tar.gz (ou .zip), et va se décompresser dans un répertoire foo-1.0.

Si un utilisateur final souhaite installer votre module foo, tout ce qu'il aura à faire est de télécharger le fichier foo-1.0.tar.gz (ou .zip), le décompresser et ---depuis le répertoire foo-1.0--- exécuter :

python setup.py install

ce qui va finalement copier foo.py dans le répertoire approprié pour un module tiers dans son installation Python.

Ce simple exemple démontre des concepts fondamentaux de Distutils, Premièrement, les développeurs et installeurs ont la même interface utilisateur basique, p. ex. le script d'installation. La différence est quelle commande Distutils ils utilisent : la commande sdist est quasiment exclusivement pour les développeurs de modules Python, tandis que install est plus souvent pour les installeurs (bien que la plupart des développeurs vont vouloir installer leur code occasionnellement).

Si vous voulez rendre les choses vraiment faciles pour vos utilisateurs, vous pouvez créer on ou plusieurs distributions compilées pour eux. En l’occurrence, si vous tournez sous une machine Windows, et que vous voulez rendre les choses faciles pour les autres utilisateurs Windows, vous pouvez créer un installateur exécutable (le mode de distribution le plus approprié pour cette plateforme) avec la commande bdist_wininst. Par exemple :

python setup.py bdist_wininst

va créer une installeur exécutable, foo-1.0.win32.exe, dans le répertoire courant.

D'autres formats de distributions compilés utiles sont RPM, implémenté par la commande bdist_rpm, Solaris pkgtool (bdist_pkgtool), et HP-UX swinstall (bdist_sdux). Par exemple, la commande suivante va créer un fichier RPM appelé foo-1.0.noarch.rpm:

python setup.py bdist_rpm

(La commande bdist_rpm utilise l'exécutable rpm, cependant cela doit être exécuté sur un système basé sur RPM tel que Red Hat Linux, SuSE Linux, or Mandrake Linux.)

Vous pouvez trouver quelles sont les formats de distribution disponibles à n'importe quel moment en exécutant :

python setup.py bdist --help-formats

1.3. Terminologie Python générale

Si vous lisez ce document, vous avez probablement une bonne idée de ce que sont les modules, extensions, etc. Néanmoins, juste pour être sur que tout le monde opère depuis un point d'entrée commun, nous reprécisons le glossaire suivant des termes Python communs :

module

unité de base de la réutilisabilité en Python : un bloc de code importé par un autre code. Trois types de modules nous concernent ici : les purs modules Python, les modules d'extension, et les packages.

pur module Python

un module écrit en Python et contenu dans un seul fichier .py (et possiblement un fichier .pyc associé). Parfois appelé "pur module."

module d'extension

un module écrit dans un langage de bas niveau de l'implémentation Python: C/C++ pour Python, Java pour Jython. Typiquement contenu dans un unique fichier pré-compilé chargeable, p. ex. un fichier objet partagé (.so) pour des extensions Python sous Unix, un fichier DLL (étant donné l'extension .pyd) pour les extensions Python sous Windows, ou un fichier de classe Java pour les extensions Jython (notez qu'actuellement, Distutils gère seulement les extensions Python C/C++).

paquet

un module qui contient d'autres modules ; très souvent contenu dans un répertoire du système de fichier et qui se distingue des autres répertoires par la présence d'un fichier __init__.py.

paquet racine

la racine de la hiérarchie de paquets. (Ce n'est pas vraiment un paquet, puisqu'il n'a pas un fichier __init__.py. Mais nous devons bien le nommer.) La grande majorité de la bibliothèque standard est dans le package racine, comme le sont certains petits, des packages tiers autonomes qui n'appartiennent pas à une un module plus grand. Contrairement aux packages réguliers, les modules dans le package racine peuvent être trouvés dans plusieurs répertoires : en effet, tous les répertoires listés sys.path contribuent à faire partie du package racine.

1.4. Terminologie spécifique à Distutils

Les termes suivant s'appliquent plus spécifiquement au domaine de la distribution de modules Python en utilisant les Distutils :

module de distribution

une collection de modules Python distribués ensemble, comme une unique ressource téléchargeable et ayant pour but d'être installé en bloc. Des exemples de modules distribués bien connus sont NumPy, SciPy, Pillow, ou mxBase. (On pourrait les appeler des packages, malgré que le terme soit déjà pris dans le contexte Python : une distribution de module simple pourrait contenir zéro, on ou plusieurs packages Python

distribution de modules purs

une distribution de module qui contient seulement des modules purs et packages Python. Parfois appelée « distribution pure ».

distribution de module non pur

une distribution de module qui contient au moins un module d'extension. Parfois appelée « distribution non-pure ».

distribution racine

le répertoire de plus haut niveau de votre arborescence (ou distribution source) ; le répertoire ou setup.py existe. Généralement setup.py est exécuté depuis ce répertoire.