4. Créer une Distribution Source

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

(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éé une archive au format par défaut pour la plateforme utilisé. Le format par défaut est un fichier tar gzippé (.tar.gz) sur Unix et un fichier ZIP sur Windows.

You can specify as many formats as you like using the --formats option, for example:

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

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

Format Description Notes
zip Fichier zip (.zip) (1),(3)
gztar Fichier tar gzippé (.tar.gz) (2)
bztar Fichier tar bzip2 (.tar.bz2)  
ztar Fichier tar compressé (.tar.Z) (4)
tar Fichier tar (.tar)  

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 déprécié et sera enlevé des prochaines version de Python.

When using any tar format (gztar, bztar, ztar or tar), under Unix you can specify the owner and group names that will be set for each member of the archive.

Par exemple, si vous voulez que tout 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:

  • tout les fichiers source Python necessaires selon py_modules et packages
  • tout les fichiers source C mentionnés dans les arguments ext_modules ou libraries
  • scripts identifiés par l’argument scripts. Voir Installing Scripts.
  • tout ce qui ressemble a un script de test test/test*.py (pour l’instant, Distutils ne fait rien avec ces scripts de test a part les inclure dans les distributions source, mais dans le futur un standard sera implémenté pour tester les distributions de module Python)
  • README.txt (ou README), setup.py (ou peut importe la manière dont vous avez appelé votre script d’installation) et setup.cfg
  • tout les fichier qui sont associés aux métadonnées package_data. Voir Installing Package Data.
  • tout les fichiers qui sont associés aux métadonnées data_files. Voir Installing Additional Files.

Parfois ce fonctionnement suffit, mais généralement vous voudrez spécifier des fichier supplémentaire a distribuer. La voie courante pour le faire est d’écrire un manifeste modèle, appelé MANIFEST.in par défaut. Ce modèle manifeste est juste une liste d’instructions pour générer votre fichier manifeste final, MANIFEST, qui est liste exacte des fichiers à inclure dans votre distribution source. La commande sdist traite ce modèle et génère un manifeste basé sur ces instructions et ce qu’il trouve dans le système de fichier.

Si vous préferez 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: le groupe de fichier par défaut décrit au dessus ne sera pas inclu automatiquement dans ce cas

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

Modifié dans la version 3.1.3: Les fichiers MANIFEST commence avec 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 si il n’existe pas de MANIFEST.in , tel qu’il y en a d’habitude.

The manifest template has one command per line, where each command specifies a set of files to include or exclude from the source distribution. For an example, again we turn to the Distutils” own manifest template:

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

The meanings should be fairly clear: include all files in the distribution root matching *.txt, all files anywhere under the examples directory matching *.txt or *.py, and exclude all directories matching examples/sample?/build. All of this is done after the standard include set, so you can exclude files from the standard set with explicit instructions in the manifest template. (Or, you can use the --no-defaults option to disable the standard set entirely.) There are several other commands available in the manifest template mini-language; see section Creating a source distribution: the sdist command.

L’ordre des commandes dans le modèle manifeste compte: nous avons a la base la liste de fichier par défaut tel que décrit plus haut et chaque commande du modèle ajoute ou supprime des fichier de cette liste. Une fois que vous avez fini de traiter le modèle manifeste, nous enlevons les fichiers qui ne doivent pas être inclut dans la distribution source:

  • tout les fichiers dans l’arborescence de « construction » de Distutils (par défaut build/)
  • tout les fichiers dans les dossiers nommés RCS, CVS, .svn, .hg, .git, .bzr ou _darcs

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

You can disable the default set of included files with the --no-defaults option, and you can disable the standard exclude set with --no-prune.

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

  1. inclure tout les fichier source Python dans les sous-dossiers distutils et distutils/command (parce que des packages correspondant a ces deux dossiers ont été mentionnés dans l’argument packages du script d’installation —voir le chapitre Writing the Setup Script)
  2. inclure README.txt, setup.py, et setup.cfg (fichiers standard)
  3. inclure test/test*.py (fichiers standard)
  4. inclure *.txt à la racine de la distribution (ceci trouvera README.txt une seconde fois, mais les redondances sont supprimées plus tard)
  5. inclure tout fichier ressemblant à *.txt ou *.py dans la sous-arborescence de examples,
  6. exclure tout les fichiers dans la sous-arborescence démarrant au dossier ressemblant à examples/sample?/build— Ceci peut exclure des fichiers inclut dans les étapes précédentes, il est donc important que la commande prune dans le modèle manifeste 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 fichier et des dossiers dans le modèle manifeste doivent toujours être séparés par des slash; Distutils s’occupera de les convertir a la représentation standard de votre plateforme. De cette manière, le modèle manifeste est portable sur tout système d’exploitation