Nous avons écrits des bibliothèques génériques qui nous simplifie la vie en réutilisant les mêmes composants génériques entre plusieurs services. Ces bibliothèques sont disponibles lors de la création de virtualenv car ils sont disponibles sur un dépôt privé (livré par devpi) que nous hébergeons. Ainsi, lorsque nous créons un virtualenv, les paquets python disponibles sont l'union des paquets disponibles sur pypi.python.org ainsi que ceux que nous avons produits. Lorsque nous avons publié MarkdownMail, une de ces bibliothèques, directement sur pypi.python.org dans l'espoir qu'elle puisse servir à d'autres, nous en avons tiré quelques enseignements :
C'est facile ! :-)
Étant donné que la structure de la bibliothèque était déjà faite préalablement, il y avait peu de travail à ce niveau-là. Les améliorations réalisées pour la publication sont listées par la suite.
Pour publier sur pypi.python.org, il suffit de créer un compte sur le service et le valider (soit un clic dans un e-mail). Ensuite, les paramètres passé au setup.py permettent de réserver un nom disponible puis d'envoyer une nouvelle version vers pypi.python.org (cf. https://docs.python.org/3.4/distutils/packageindex.html).
Classifiers
Les classifiers du setup.py aident les utilisateurs à avoir une idée de l'application ou de la bibliothèque. Ils servent aussi pour trouver plus facilement ce que l'on cherche parmi les paquets disponibles.
Nous nous en servions déjà en interne pour définir certains éléments, en particulier pour expliciter la compatibilité de nos bibliothèques avec python 2 et/ou python 3. Il a suffit d'en rajouter certains pour être plus complet.
README
Ajouter un fichier README à la racine est un moyen habituel de documenter la bibliothèque. En faisant lire son contenu comme description longue dans le fichier setup.py, il sera affiché sur la page du paquet et sera donc directement lisible par les utilisateurs. Si le texte est au format reStructuredText (reST), alors il est affiché en html automatiquement. Dans le cas contraire, il sera simplement affiché comme du texte brut, dans une police à chasse variable. Dans ce cas, le rendu n'est pas très lisible, en particulier pour les exemples de code source.
reST ressemble à du Markdown mais n'en est pas. Pour ceux qui publient le code sur GitHub, GitHub fait un rendu HTML des README au format reST, et pas uniquement au format Markdown.
Tox
En rendant la bibliothèque publique, il est bon de valider les tests avec plusieurs versions de python. En interne, les versions sur lesquelles le code doit fonctionner sont connues (2.7 ou 3.4 actuellement chez nous). Tox est l'outil classique pour le faire et son intégration avec setup.py est documentée.
Devpi + pypi.python.org
Une fois que la bibliothèque est déjà présente en interne via devpi, il n'est plus possible d'en récupérer une plus récente sur pypi.python.org. Cela est dû à des raisons de sécurité : dans le cas contraire, un attaquant connaissant le nom d'un paquet utilisé en interne pourrait envoyer un paquet plus récent sur pypi.python.org. Ensuite, lors de la création d'un nouveau virtualenv, ce paquet serait installé au lieu du paquet interne, provoquant par la suite l'exécution du code de l'attaquant et non le code développé par le créateur de la bibliothèque.
Pour rendre ce cas possible, il suffit de modifier la configuration de devpi. Nous avons ajouté MarkdownMail à une liste blanche pour limiter l'effet de la modification.
Pyroma
Pyroma permet de connaitre les éléments manquants à un paquet. Il permet de tester les différents éléments de la bibliothèque pour améliorer la qualité du paquet. Par exemple, il signale l'absence des champs « keywords » ou « licence ». Pyroma ne remplace pas des outils vérifiant PEP8.
Environnement de dév. pour pypi.python.org
pypi.python.org permet d'envoyer la bibliothèque vers un dépôt de tests pour valider une bibliothèque avant de la rendre accessible au reste du monde. Pour cela, il suffit de préciser le dépôt dans lequel insérer une nouvelle version d'un paquet (grâce au paramètre -r).
De nouvelles évolutions sont envisagées pour améliorer l'usage de MarkdownMail pour les développeurs externes à Yaal, comme le fait de simplifier la possibilité de signaler des bogues ou faire des patchs. Cependant ces évolutions sont indépendantes de pypi. Le fait de publier cette bibliothèque nous a permis de l'améliorer et, plus généralement, de progresser sur les paquets python.