Distribuer un projet en python
La plus simple manière de partager un projet écrit en python est de le paqueter dans une archive zip, et de laisser chacun extraire et installer votre projet là où c'est nécessaire. Ce procédé fastidieux a été automatisé par des librairies tierces, intégrées dans la librairies standard de python dès Python 1.6. Parmi tous les outils qui sont apparus pas la suite on peut citer distutils, easy_install, pkg_resources, setuptools, pip, buildout... La manière de paqueter son projet et de le distribuer ne cesse d'évoluer, ce livre essaie de vous aider à vous repérer dans cet univers. Une solide connaissance du langage python est nécessaire avant de continuer, vous pouvez lire ce livre pour cela : Programmation Python.
Module tiers.
Dans le vocabulaire python, le projet que vous chercher à paqueter et distribuer est appelé un « module tiers » ("third-party module"). Quel que soit l'outil que vous utilisez (easyinstall, pip...), l'endroit où vos fichiers s'installeront doit être trouvable par le module codice_1 de python, situé à codice_2). Pour simplifier, ce fichier va mettre à jour la propriété codice_3 avec le dossier codice_4 pour que vous puissiez simplement codice_5 dans vos projets, et que ceux-ci soient centralisés dans un unique dossier utilisable par tous vos projets. C'est très utile pour les librairies lourdes. Pour savoir comment site.py va altérer votre environnement, tapez simplement codice_6. Pour empêcher python d'exécuter ce script, lancez-le avec l'option -S, c'est à dire codice_7, cela vous laisse loisir de modifier l'environnement d'exécution puis d'importer vous même ce module via codice_8, sachant qu'il va faire beaucoup de lectures de dossiers et peut ralentir le démarrage de votre script python.
Pour résumer après avoir exécuté site.py, on peut simplement importer tout module tiers dans ses projets, sans avoir besoin d'avoir ces dits modules dans la même arborescence que le projet en question, mais au lieu de cela dans un environnement virtuel, dans un dossier utilisateur (/home sur Unix, AppData sur Windows…), ou dans un dossier de python lui même.
Environnement virtuel.
Non seulement d'inclure les site-packages, site.py essaie de détecter si l'instance de python courante s'exécute dans un « environnement virtuel » (dit aussi venv, pour "virtual environment"). Il détermine cela si il existe un fichier codice_9 dans le répertoire immédiatement au dessus de l'exécutable python en cours. Si c'est le cas, le fichier site-packages de l'environnement virtuel est placé tout en haut de la liste codice_3 afin que les imports soient en priorité cherchés dans cet environnement, puis dans le site-packages de l'utilisateur en recours, et le site-packages de l'installation python en deuxième recours.
Toutefois si le fichier codice_9 contient la ligne codice_12, les site packages de l'utilisateur et de l'environnement sont supprimés du codice_3. Un import de module ne peut alors réussir que si il existe bien dans l'environnement virtuel ou bien si il s'agit d'un "core-lib" de python (codice_14, codice_15, ...). Cette configuration est indispensable si on veut s'assurer que l'environnement de travail nécessaire au fonctionnement de son module soit reproductible au mieux par les tierces personnes avec qui vous partagerez les "plans" de votre environnement virtuel.
La manière dont vous décrivez ces environnement est propre à chaque outil, nous décrirons plus loin celui de pip.
Le paquetage.
Pour utiliser votre module, il faut donc l'inclure dans un paquetage qui contient en outre les noms d'autre modules tiers que votre module utilise dans un fichier texte, ce fichier peut être utilisé pour établir un arbre de dépendances, et il est déconseillé de le modifier à la main mais de laisser codice_16 s'en occuper.
Maintenant comment construire ce paquetage ? Encore une fois le faire à la main peut être fastidieux, surtout si votre module contient beaucoup de fichiers, des fichiers non en python, des fichiers que vous ne souhaitez pas partager, etc. Python contient un module spécialement dédié à cette fin, nommé « distutils ». Si vous êtes curieux, vous le trouverez dans Lib/distutils, et sa documentation est à l'adresse install/index.html de la documentation officielle. On voit que la finalité première de ce module est de produire des paquetages dans le sens de linux, c'est à dire des fichier .rpm. En ce qui nous intéresse, dans un premier temps, c'est de créer une archive .zip, .tar.gz, que codice_17 est capable de lire (si vous tapez codice_18, vous verrez qu'en outre de lire un fichier de requirements il sait lire une archive zip, en sus de savoir chercher un module sur pypi, d'un dépôt git où d'un simple chemin vers une arborescence locale). Ce que pip va faire dans tous les cas, plutôt que de recopier tout le contenu du répertoire, déport distant, archive, etc. est d'exécuter un fichier dont le nom est normalisé : codice_19 avec l'argument codice_20, c'est ce fichier qui va donc chapeauter ce qui est copié ou non dans le dossier codice_4 via pip.
Ce fichier peut être utilisé par soi même de multiples manières : construire une archive, un paquetage linux, voire même un installeur Windows (même si cela est déconseillé de nos jours et non plus officiellement supporté), mais également des outils tiers comme pip.
Dans sa forme la plus simple le fichier codice_19 contient un import de la librairie setuptools, et un appel a la fonction codice_23 de celle-ci qui lit le contenu de la ligne de commande et exécute les taches nécessaires à la copie de fichiers, la compilation de modules, de paquetage dans une archive, etc.
 # from distutils.core import setup # vieille façon
 from setuptools import setup # nouvelle façon
 setup()
Cet exemple introduit setuptools, qui est un module tiers à python que vous devez installer au préalable via codice_24 et qui est un sur-ensemble de setuptools; c'est à dire qu'il permet de faire tout ce que distutils peut faire, mais en y ajoutant des fonctionnalités propres. Distutils existe depuis Python 1.5, rétro compatible jusque Python 1.6, Setuptools a vu le jour au début des années 2000, dans la même idée et de manière concurrente à zc.buildout, au final setuptools a été retenu comme outil officiel. Ces extensions ont la particularité d'importer la fonction setup de distutils et de l'appeler avec les mêmes arguments qu'ils ont reçu en entrée, on peut résumer le fonctionnement de ces outils ainsi.
 # fichier setuptools/setup.py ou zc.buildout
 from distutils core import setup as distutils_setup
 def setup(**args):
 # traitement des arguments propre à setuptools, zc.buildout...
 distutils_setup(**args)
De la même manière les fichiers qui exécutent les commandes (setup, build, sdist...) importent le fichiers de distutils et l'appellent tout en y ajoutant leurs propres fonctionnalités. "Tout ce que l'on peut faire avec distutils, on peut le faire avec setuptools" (ou presque). Si l'objectif de distutils est de produire des bundles installables à telle ou telle plateforme, celui de setuptools est assez multiple, mais principalement de produire des eggs spécifiques à python, et couplé avec l'utilitaire easy_install, de simplifier l'installation et la désinstallation (ce que distutils ne permet pas de faire) de paquetages en python, et distribuables sans nécessité de build. Mais pour bien les comprendre il faut comprendre comment distutils fonctionne et comment il est possible de l'étendre.
Distutils.
Aux débuts de python, jusque la version 1.5, lorsqu'on voulait partager son projet, si on voulait le rendre accessible sur Linux on créait un paquetage codice_25, codice_26…, sous Windows on créait un installeur codice_27, codice_28. Cela demandait du temps et un niveau de compétence plus élevé que celui d'un débutant. De même l'installation diffère pour chaque projet et la mise en place de l'environnement se faisait qui avec des scripts "shell", qui avec des instructions à suivre à la lettre… Les plus pressés incluaient simplement leur projet dans un .zip, mais alors il fallait faire attention à ne pas y mettre des fichiers temporaires, en cache, etc. Si on voulait inclure des extensions en C il ne fallait pas oublier de les compiler avant de les inclure. Toutes ces tâches répétitives ont été automatisées par distutils. 
Pour la tâche de paqueter et de compiler distutils propose la commande codice_29, et pour celle de produire une archive zip distutils propose la commande codice_30 ainsi qu'un format d'inclusion et d'exclusion de fichiers via une syntaxe de globing et un fichier MANIFEST. La tâche de l'installation est simplifiée car celle-ci passe par une commande universelle codice_31. Ce fichier setup étant en python il peut alors installer les dépendances, vérifier les prérequis, et tout ce qui demandait de la minutie et un travail manuel auparavant.
Pour utiliser distutils, votre projet doit contenir un fichier setup.py, qui contient le code python nécessaire à l'installation de votre module. On verra plus tard que pour automatiser cette installation il est préférable que ce fichier se trouve à la racine de l'arborescence du projet et s'appelle bien codice_19. Cette installation, doit aboutir à la copie des fichiers nécessaires dans le répertoire site-packages le plus pertinent.
La machinerie de distutils se met en place en appelant la fonction codice_23 de codice_34. Cette fonction lit la ligne de commande utilisée pour invoquer le script puis exécute la commande appelée. codice_35 appelle la commande toto avec l'argument codice_36 valant codice_37. Un fichier codice_38 peut contenir des valeurs d'arguments par défaut pour chaque commande. Si il est ainsi
 # setup.cfg
 [toto]
 arg1=3
 arg2=1
La commande codice_39 s'exécute avec codice_40 at codice_41, la ligne de commande prévaut sur le fichier de configuration.
Ne reconnaissant pas la commande toto un message d'erreur s'affiche avec la liste des commandes acceptées. Leur code source peut se trouver dans codice_42. Si vous lisez ces fichiers, et notamment la méthode codice_43, vous remarquerez que beaucoup de commandes en appellent d'autres. Par exemple codice_20 appelle codice_45, codice_45 peut appeler codice_47, codice_48..., que chaque commande a des arguments différents qui peut altérer la course de l'installation, et des valeurs par défaut. 
Les principales commandes sont codice_45, codice_20, codice_30, codice_29 et codice_53.
La commande codice_45 copie les fichiers python dans un répertoire, par défaut codice_55, compile les modules en C/C++ et les copie également, par simplicité lorsqu'on parle de librairie plus loin dans ce cours, c'est de ce dossier qu'on parlera. La commande codice_20 recopie tout ce qui se trouve dans le répertoire peuplé par codice_45 dans le dossier codice_4, la commande codice_30 produit une archive zip avec tout ce qu'il faut pour que la commande bdist réussisse. Sachant cela il apparait que la fonction install peut fonctionner à partir de la commande build, sdist et bdist, la commande bdist à partir de la commande codice_45 et codice_30, mais les commandes codice_45 et codice_30 ne peuvent pas fonctionner à partir d'une archive faite par codice_29. setup/build fonctionnent à partir d'un répertoire local, sdist/bdist servent à partager le répertoire local, bdist avec le minimum vital (fichiers pyc, pyd, ...), et sdist avec les tests, fichiers source (py, pyx, c, c++, ...).
Notre objectif premier était de produire un répertoire zip facilement installable avec pip, donc doit-on utiliser ici sdist ou bdist? Cela dépend du contenu de notre paquetage, si il ne contient que des fichiers en python, les deux commandes sont assez similaires, mais si ils contients du code en cython, ou des modules C/C++ natifs, alors dans le cas de sdist les clients de votre librairie doivent posséder un compilateur C (qui occupe un espace disque jusque 30 giga-octets) et les librairies python de dev, par défaut non installées. Si vous optez pour bdist, les modules binaires doivent être compatible avec chaque machine, c'est à dire qu'une distribution bdist faite en 64 bits ne fonctionnera pas sur une machine 32 bits, un module fait avec une librairie python 3.7 probablement ne fonctionnera pas dans un environnement 3.6 (même si l'usage de l'ABI stable de python peut mitiger cela), une librairie construite sous mac, windows ou linux ne fonctionnera pas sur les autres machines. Nous verrons cette problématique bien plus tard car elle nécessite une machinerie complexe hors de notre propos, mais si vous êtes curieux, les mots-clés sont soit "cross-compilation", soit "continous integration", et nous concentrons sur sdist dans la suite du livre, et sur la forme de bdist la plus simple : celle faite par et pour soi.
codice_65.
Qu'on utilise la commande codice_20, codice_30 ou codice_29, la commande codice_45 est exécutée dans tous les cas, pour qu'elle sache quoi mettre dans la librairie, on utilise l'argument codice_70 et codice_71 de codice_23. Ceux-ci ont d'abord été mutuellement exclusifs, avant qu'il devienne possible de les utiliser en même temps. codice_70 accepte une liste de chaines de caractères, qui doivent correspondre à la manière dont les fichiers seront importés, par exemple un fichier codice_74 est importé ainsi
 setup(py_modules=['toto'])
Si vous avez un autre fichier dans un sous-répertoire codice_75, celui-ci doit contenir un fichier codice_76, et vous le déclarez ainsi
 setup(py_modules=['toto', 'a.b.toto'])
Cela inclut automatiquement le fichier __init__, pas besoin d'écrire codice_77. Ces noms d'import doivent obligatoirement référencer des fichiers qui existent et se terminent par .py, de préférence se trouvent dans un répertoire contenant un fichier codice_78 (sinon un warning s'affiche). codice_70 n'est pas compatible avec des fichiers non python (readme, ...) ou compressés (pyo, pyc) ou des paquetages PEP420.
L'option codice_80 est plus complexe à écrire, mais permet d'inclure tout type de fichier et d'utiliser une syntaxe de codice_81ing pour inclure rapidement des répertoires entiers de fichiers dans la librairie. Si on veut inclure les mêmes fichiers qu'avec codice_70, mais en plus un README, et des fichier en python compilés et de typage dans le répertoire a > b, on écrit
codice_80 prend une liste de noms de répertoires à chercher pour y trouver des fichiers en python et les inclut automatiquement, Si on veut ajouter d'autres fichiers que des scripts en python, on doit utiliser codice_84 qui prend un dictionnaire de champs nom de package -> liste de globs à appliquer. Le champ au nom vide codice_85 s'applique à tous les packages et à la racine du projet. Le format packages n'inclut que des fichiers situés dans des packages, pour inclure le fichier toto à la racine du projet on doit utiliser py_modules, au final
 # ou alors
 setup(packages=[", 'a.b'], package_data={": ['README'], 'a.b': ['*.pyi', '*.pyc']} # fonctionne aussi, mais génère une erreur car le package vide est ambigu
On remarque que si le répertoire codice_86 contient un fichier codice_87, il sera inclus aussi. Seul les règles de la racine s'appliquent à tous les sous-paquetages, si vous définissez un sous-paquetage codice_88, les règles propre à codice_89 ne s'appliquent pas à codice_88.
Si vous ne voulez pas inclure certains scripts en python, par exemple des scripts contentant des données locales dans votre paquetage, le plus simple est de les mettre dans un répertoire séparé non listé dans l'entrée codice_80, mais vous pouvez aussi utiliser codice_70 juste pour le répertoire où ces fichiers se trouvent, mais cela peut être dangeureux avec setuptools et son outils de découverte automatique.
codice_84 est une fonctionnalité créé par setuptools et importée dans distutils depuis python 2, setuptools fonctionne différemment vis à vis de ce paramètre et peut l'ignorer complètement, nous verrons avec codice_30 que la présence d'un fichier codice_95 peut être mutuellement exclusif avec ce paramètre.
codice_30.
codice_97 inclut tous les fichiers spécifiés précédemment en plus de 
La liste à jour et complète est dans la documentation (lien).
Un fichier codice_98 est également ajouté qui contient des informations utiles pour ensuite créer des packages de type rpm, il contient le nom du projet, sa version, un résumé expliquant ce qu'il fait, un lien vers un site web, un nom d'auteur, des informations de license et une plateforme préférée, toutes ces informations sont passées via codice_23, par exemple
 setup(
 name='toto'
 version='0.1'
 description='...'
 author='...'
 author_email='...'
 url='http://github.com/...';
 license='MIT'