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

# 7. Extension de 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.

Distutils peut être étendu de multiples façons. La plupart des extensions sont soit des nouvelles commandes soit des remplacements de commandes existantes. De nouvelles commandes pourraient par exemple servir à l'empaquetage pour des plateformes spécifiques tandis que des remplacements peuvent modifier certains aspects des commandes existantes.

La plupart des extensions de distutils sont faites dans le script `setup.py`. La plupart ajoutent simplement quelques extensions de fichiers qui devraient être copiés dans le paquet en plus des fichiers `.py`.

La plupart des implémentations des commandes distutils sont des sous-classes de `distutils.cmd.Command`. Les nouvelles commandes peuvent hériter directement de `Command`, alors que les remplacements dérivent souvent de `Command` indirectement, directement sous-classant la commande qu'ils remplacent. Les commandes doivent dériver de la classe `Command`.

## 7.1. Intégrer de nouvelles commandes

Il y a différentes façons d’intégrer de nouvelles implémentations de commandes dans distutils. La plus difficile est de faire pression pour inclure une nouvelle fonctionnalité dans distutils même, et d’attendre (et demander) une version de Python l'implémentant. C'est très difficile pour beaucoup de raisons.

La plus commune, et possiblement la plus raisonnable pour la plupart des cas, est d'inclure les nouvelles implémentations dans votre fichier `setup.py`, et de faire en sorte que la fonction `distutils.core.setup()` les utilise :

    from distutils.command.build_py import build_py as _build_py
    from distutils.core import setup

    class build_py(_build_py):
        """Specialized Python source builder."""

        # implement whatever needs to be different...

    setup(cmdclass={'build_py': build_py},
          ...)

Cette approche est la plus valable si les nouvelles implémentations doivent être utilisées pour utiliser un paquet particulier, vu que toutes les personnes intéressées par le paquet devront avoir ces nouvelles implémentations de commandes.

Depuis Python 2.4, une troisième option est disponible, prévue pour permettre d'ajouter de nouvelles commandes compatibles avec le script existant `setup.py` sans avoir besoin de modifier l'installation Python. C'est fait pour que les extensions tierces puissent rester compatibles avec d'autres systèmes d'empaquetage, mais les commandes peuvent être utilisées pour tout ce que les commandes de distutils peuvent faire. Une nouvelle option de configuration, `command_packages` (option shell `--command-packages`), peut être utilisée pour spécifier des recherches de paquets additionnels pour des modules qui implémentent des commandes. Comme toutes les options distutils, cela peut être spécifié en ligne de commande ou dans un fichier de configuration. Cette option peut être fixée dans la section `[global]` d'un fichier de configuration, ou avant n'importe quelle commande dans un shell. Si définie dans un fichier de configuration, elle peut être écrasée depuis la ligne de commande. Mettre une chaine de caractères vide en valeur de cette option forcera l'utilisation de la valeur par défaut. Cela ne devrait jamais être fixé dans un fichier de configuration donné avec un paquet.

Cette nouvelle option peut être utilisée pour ajouter n'importe quel nombre de paquet à la liste des paquets recherchés pour les implémentations de commandes ; plusieurs noms de paquets doivent être séparés par des virgules. Quand non spécifié, la recherche est seulement faite dans le paquet `distutils.command`. Cependant, lorsque `setup.py` est lancé avec l'option `--command-packages distcmds,buildcmds`, les paquets `distutils.command`, `distcmds`, et `buildcmds` seront cherchés dans cet ordre. Il est attendu des nouvelles commandes d’être implémentées en modules du même nom que la commande en utilisant des classes partageant le même nom. Comme dans l'exemple shell donné ci-dessus, la commande bdist_openpkg pourrait être implémentée avec la classe `distcmds.bdist_openpkg.bdist_openpkg` ou `buildcmds.bdist_openpkg.bdist_openpkg`.

## 7.2. Ajout de nouveaux types de distribution

Les commandes qui créent des distributions (fichiers dans le dossier `dist/`) doivent ajouter la paire `(command, filename)` à `self.distribution.dist_files` pour que upload puisse publier sur PyPI. Le nom de fichier (filename) dans la paire ne contiens pas de chemin, juste le nom du fichier lui-même. En mode dry-run, les paires doivent toujours être ajoutées pour représenter ce qui aurait été créé.