4. Créer une distribution source

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.

Comme montré dans le chapitre Un exemple simple, vous pouvez utiliser la commande sdist pour créer une distribution source. Dans le cas le plus simple,

python setup.py sdist

(en supposant que vous n'avez spécifié aucune option pour la commande sdist dans le script de préparation ou le fichier de configuration), sdist crée une archive au format par défaut pour la plateforme utilisée. Le format par défaut est un fichier tar compressé (.tar.gz) sur Unix et un fichier ZIP sur Windows.

Vous pouvez donner autant de formats que désiré via l'option --formats, par exemple :

python setup.py sdist --formats=gztar,zip

pour créer un fichier tarball compressé et un fichier ZIP. Les formats disponibles actuellement sont :

Format	Description	Notes
zip	Fichier zip (.zip)	(1), (3)
gztar	Fichier tar compressé par gzip (.tar.gz)	(2)
bztar	Fichier tar compressé par bzip2 (.tar.bz2)	(5)
xztar	Fichier tar compressé par xz (.tar.xz)	(5)
ztar	Fichier tar compressé par compress (.tar.Z)	(4),(5)
tar	fichier tar (.tar)	(5)

Modifié dans la version 3.5: Ajout du support des fichiers xztar.

Notes :

1. Par défaut sur Windows

2. Par défaut sur Unix

3. nécessite soit un utilitaire zip extérieur ou le module zipfile (inclut dans la bibliothèque standard depuis Python 1.6)

4. nécessite le programme compress. Remarquez que ce format sera bientôt obsolète et sera enlevé des prochaines version de Python.

5. deprecated by PEP 527; PyPI only accepts .zip and .tar.gz files.

Lorsque vous utilisez n'importe quel format tar (gztar, bztar, xztar, ztar or tar), vous pouvez spécifier sous Unix le propriétaire et le groupe qui seront appliqué pour chaque fichier de l'archive.

Par exemple, si vous voulez que tous les fichiers de l'archive soient détenu par root :

python setup.py sdist --owner=root --group=root

4.1. Spécifier les fichiers à distribuer

Si vous ne fournissez pas une liste explicite de fichiers (ou les instructions pour la générer), la commande sdist en met par défaut le minimum dans la distribution source :

• tous les fichiers source Python sous-entendus par les options py_modules et packages

• tous les fichiers source C mentionnés dans les arguments ext_modules ou libraries

• scripts identifiés par l'argument scripts. Voir Installation des scripts.

• tout ce qui ressemble à un script de test test/test*.py (pour l'instant, Distutils ne fait rien avec ces scripts de test, si ce n'est les inclure dans les distributions sources, mais dans le futur un standard sera implémenté pour tester les distributions de module Python)

• n'importe quel fichier README classique (README, README.txt, ou README.rst), ainsi que le fichier setup.py (ou votre script d'installation si vous l'avez appelé autrement) et le fichier setup.cfg.

• tous les fichiers associés aux méta-données package_data. Voir Installation de paquets de données.

• tous les fichiers associés aux méta-données data_files. Voir Installation de fichiers additionnels.

Parfois ce fonctionnement suffit, mais généralement vous voudrez spécifier des fichiers supplémentaires à distribuer. La façon classique de le faire est d'écrire un manifeste modèle, appelé MANIFEST.in par défaut. Ce manifeste modèle est juste une liste d'instructions pour générer votre fichier manifeste final, MANIFEST, qui est la liste exacte des fichiers à inclure dans votre distribution source. La commande sdist traite ce modèle et génère un manifeste à partir de ces instructions et de ce qu'elle trouve dans le système de fichiers.

Si vous préférez créer votre propre fichier manifeste, le format est simple : un nom de fichier par ligne, uniquement des fichiers normaux (ou leur lien symbolique). Si vous fournissez votre propre MANIFEST, vous devez tout spécifier : les groupes de fichiers par défaut décrits au-dessus ne sont pas inclus automatiquement dans ce cas.

Modifié dans la version 3.1: Un MANIFEST existant généré automatiquement sera régénéré sans que sdist ne compare son heure de modification à MANIFEST.in ou setup.py.

Modifié dans la version 3.1.3: Les fichiers MANIFEST commencent par un commentaire indiquant qu'ils sont générés. Les fichiers sans ce commentaire ne sont pas réécrits ou supprimés.

Modifié dans la version 3.2.2: sdist lira un ficher MANIFEST s'il n'existe pas de MANIFEST.in , tel qu'il en avait l'habitude.

Modifié dans la version 3.7: Le fichier README.rst est maintenant inclus dans la liste des fichiers README standards de distutils.

Le modèle de manifeste possède une commande par ligne, où chaque commande spécifie un ensemble de fichiers à inclure ou à exclure de la distribution source. Par exemple, regardons à nouveau le propre manifeste de Distutils :

include *.txt
recursive-include examples *.txt *.py
prune examples/sample?/build

La signification est assez claire : inclure tous les fichiers à la racine de la distribution correspondant à *.txt, tous les fichiers n'importe où dans le dossier examples correspondant à *.txt ou *.py, et exclure tous les dossiers correspondant à examples/sample?/build. Tout ceci est fait après l'ensemble d'inclusions standard, vous pouvez donc exclure des fichiers précédemment inclus en utilisant une instruction explicite dans le manifeste. (Vous pouvez aussi utiliser l'option --no-defaults pour désactiver complètement les inclusions standards). Il existe d'autres commandes dans le langage du fichier manifeste, consultez le chapitre Créer une distribution source: la commande sdist.

L'ordre des commandes dans le modèle manifeste compte : nous avons, à la base, la liste de fichiers par défaut telle que décrite plus haut. Ensuite, chaque commande du modèle ajoute ou supprime des fichiers de cette liste. Une fois que le traitement du manifeste modèle est fini, nous enlevons les fichiers qui ne doivent pas être inclus dans la distribution source :

• tous les fichiers dans l'arborescence de build de Distutils (par défaut build/)

• tous les fichiers dans les dossiers nommés RCS, CVS, .svn, .hg, .git, .bzr ou _darcs

Maintenant nous avons notre liste complète de fichiers ; elle est désormais écrite dans le manifeste pour une utilisation future et sera utilisée pour construire la ou les archive(s) de notre distribution source.

Vous pouvez désactiver l'ensemble des fichiers inclus par défaut en utilisant l'option --no-defaults, ainsi que désactiver les exclusions standards avec l'option --no-prune.

Voici le manifeste modèle de Distutils, suivons comment la commande sdist construit la liste des fichiers à inclure dans la distribution source de Distutils.

1. inclure tous les fichiers source Python dans les sous-dossiers distutils et distutils/command (parce que des paquets correspondant à ces deux dossiers ont été mentionnés dans l'argument packages du script d'installation --- voir le chapitre Rédaction du script setup.py)

2. inclure README.txt, setup.py et setup.cfg (fichiers standards)

3. inclure test/test*.py (fichiers standard)

4. inclure *.txt à la racine de la distribution (ceci trouve README.txt une seconde fois, mais les redondances sont supprimées plus tard)

5. inclure tout fichier de la forme *.txt ou *.py dans la sous-arborescence de examples,

6. exclure tous les fichiers dans les sous-arborescences dont les dossiers racines sont de la forme examples/sample?/build--- Ceci peut exclure des fichiers inclus dans les étapes précédentes, il est donc important que la commande prune dans le manifeste modèle vienne après la commande recursive-include

7. exclure l'arborescence de build ainsi que les dossiers RCS, CVS, .svn, .hg, .git, .bzr et _darcs

Comme dans le script de préparation, les chemins des fichiers et des dossiers dans le manifeste modèle doivent toujours être séparés par des barres obliques (slash en anglais) ; Distutils s'occupe de les convertir à la représentation standard de votre plateforme. De cette manière, le manifeste modèle est portable sur tout système d'exploitation.

4.2. Options pour le manifeste

L'ordre normal des opérations pour la commande sdist est le suivant :

• si le fichier manifeste (MANIFEST par défaut) existe et que la première ligne n'a pas de commentaire indiquant qu'il a été généré par MANIFEST.in, alors il est utilisé tel quel, inchangé

• si le manifeste n'existe pas ou s'il a été généré automatiquement, lire MANIFEST.in et créer le manifeste

• s'il n'existe ni MANIFEST, ni MANIFEST.in, alors créer un manifeste contenant uniquement le groupe de fichiers par défaut

• utiliser maintenant la liste de fichiers de MANIFEST (qu'il ait été généré ou lu) pour créer la ou les archive(s) de la distribution source

Il existe deux manières pour modifier ce comportement. D'abord utilisez les options --no-defaults et --no-prune pour désactiver les inclusions et exclusions standards.

Ensuite, si vous ne voulez que (ré)générer le manifeste, mais pas créer la distribution source :

python setup.py sdist --manifest-only

L'option -o est un raccourci pour l'option --manifest-only.