Transformer un projet Python personnel en bibliothèque libérable

Je suis un universitaire plutôt qu'un programmeur, et j'ai de nombreuses années d'expérience dans l'écriture de programmes Python pour mon propre usage, pour soutenir ma recherche. Mon dernier projet est susceptible d'être utile à beaucoup d'autres ainsi qu'à moi, et je pense à le publier en tant que bibliothèque Python open source.

Cependant, il semble qu'il y ait pas mal d'obstacles à franchir pour passer d'un projet personnel fonctionnel à une bibliothèque qui peut être installée et utilisée sans douleur par d'autres. Cette question concerne les premières étapes à suivre pour commencer à travailler vers une version publique.

Actuellement, j'ai un seul dépôt git qui contient mon code qui utilise la bibliothèque ainsi que la bibliothèque elle-même, et j'utilise git comme bouton d'annulation d'urgence en cas de rupture. Tout cela fonctionne bien pour un seul utilisateur mais n'est évidemment pas approprié si je veux le libérer. Là où je veux finir, c'est que ma bibliothèque est dans un référentiel séparé et peut être installée par d'autres utilisateurs pip, et possède une API stable.

Apprendre à utiliser setuptools, etc. n'est probablement pas si difficile une fois que je suis sur le point de vouloir le publier - mon problème est de savoir comment je dois travailler pour arriver à ce point.

Donc ma question est, quelles sont les premières étapes à suivre pour commencer à préparer un projet de bibliothèque Python pour la consommation publique? Comment dois-je réorganiser ma structure de répertoires, référentiel git, etc. afin de commencer à travailler vers une version publique de la bibliothèque?

Plus généralement, il serait très utile de disposer de ressources reconnues utiles lors de la première tentative. Des conseils sur les meilleures pratiques et les erreurs à éviter, etc., seraient également très utiles.

Quelques précisions: les réponses actuelles répondent à une question du type "comment puis-je faire de ma bibliothèque Python une bonne que les autres puissent utiliser?" C'est utile, mais c'est différent de la question que j'avais l'intention de poser.

Je suis actuellement au début d'un long voyage vers la sortie de mon projet. Le cœur de mon implémentation fonctionne (et fonctionne très bien), mais je me sens dépassé par la quantité de travail qui m'attend et je cherche des conseils sur la façon de naviguer dans le processus. Par exemple:

• Mon code de bibliothèque est actuellement couplé à mon propre code propre au domaine qui l'utilise. Il vit dans un sous-dossier et partage le même référentiel git. Finalement, il devra être transformé en une bibliothèque autonome et placé dans son propre référentiel, mais je continue de tergiverser parce que je ne sais pas comment le faire. (Ni comment installer une bibliothèque en «mode développement» pour que je puisse encore la modifier, ni comment garder les deux git repos synchronisés.)

• Mes docstrings sont laconiques, car je sais que je devrai éventuellement utiliser Sphinx ou un autre outil. Mais ces outils ne semblent pas simples à apprendre, donc cela devient un sous-projet majeur et je continue de le repousser.

• À un moment donné, j'ai besoin d'apprendre à utiliser setuptools ou un autre outil pour l'empaqueter et suivre les dépendances, qui sont assez complexes. Je ne sais pas si je dois le faire maintenant ou non, et la documentation est un labyrinthe absolu pour un nouvel utilisateur, donc je continue de décider de le faire plus tard.

• Je n'ai jamais eu à faire de tests systématiques, mais je le ferai certainement pour ce projet, donc je dois (i) en apprendre suffisamment sur les tests pour savoir quelle méthodologie est la bonne pour mon projet; (ii) apprendre quels outils sont disponibles pour ma méthodologie choisie; (iii) apprendre à utiliser l'outil que j'ai choisi; (iv) implémenter des suites de tests, etc. pour mon projet. Ceci est un projet en soi.

• Il y a peut-être aussi d'autres choses que je dois faire. Par exemple, jonrsharpe a publié un lien utile qui mentionne git-flow, tox, TravisCI, virtualenv et CookieCutter, dont je n'avais jamais entendu parler auparavant. (Le poste date de 2013, donc je dois aussi faire un peu de travail pour savoir combien est encore en cours.)

Lorsque vous mettez tout cela ensemble, c'est un énorme travail, mais je suis sûr que je peux tout faire si je continue de le brancher, et je ne suis pas pressé. Mon problème est de savoir comment le décomposer en étapes gérables qui peuvent être effectuées une à la fois.

En d'autres termes, je demande quelles sont les étapes concrètes les plus importantes que je peux prendre maintenant, afin d'atteindre un produit libérable à terme. Si j'ai un week-end gratuit, sur quoi dois-je me concentrer? Laquelle (le cas échéant) peut être effectuée indépendamment des autres, afin que je puisse au moins faire une étape sans avoir à tout faire? Quelle est la manière la plus efficace d'apprendre ces choses pour que j'aie encore le temps de me concentrer sur le projet lui-même? (Gardant à l'esprit que tout cela est essentiellement un projet de loisir, pas mon travail.) Y a-t-il quelque chose que je n'ai pas vraiment besoin de faire , me permettant ainsi d'économiser énormément de temps et d'efforts?

Toutes les réponses sont grandement appréciées, mais je serais particulièrement heureux de recevoir des réponses qui se concentrent sur ces aspects de la gestion de projet, avec une référence spécifique au développement Python moderne.

L'ajout d'un fichier setup.py, bien que nécessaire, n'est pas l'étape la plus importante si vous souhaitez que votre bibliothèque soit utilisée. Le plus important est d'ajouter de la documentation et de publier votre bibliothèque. Étant donné que le deuxième point dépend fortement de la bibliothèque, permettez-moi plutôt de concentrer l'aspect documentation.

1. Vous savez tout sur votre bibliothèque. Et c'est problématique. Vous savez déjà comment installer et comment l'utiliser, tant de choses peuvent vous sembler intuitives ou tout à fait évidentes. Malheureusement, les mêmes choses ne sont ni évidentes, ni intuitives pour les utilisateurs. Essayez de regarder votre bibliothèque comme si vous n'en saviez rien, et surtout, demandez à d'autres personnes de l'utiliser et essayez de repérer toutes les difficultés qu'elles ont rencontrées.

2. Expliquez, en langage simple, à quoi sert votre bibliothèque. Trop de bibliothèques supposent que tout le monde les connaît. Lorsque ce n'est pas le cas, il peut être difficile de comprendre à quoi sert la bibliothèque.

3. Écrivez une documentation technique détaillée, mais n'oubliez pas non plus de courts morceaux de code qui montrent comment effectuer certaines tâches avec votre bibliothèque. La plupart des développeurs sont pressés et s'ils ont besoin de passer des heures à essayer de comprendre comment faire une chose de base, ils peuvent avoir tendance à passer à d'autres bibliothèques.

4. Incluez vos coordonnées. Si votre bibliothèque est un succès (et ma propre expérience a montré que c'est le cas même pour les plus inconnus), les gens rencontreraient des difficultés avec: des bugs ou simplement des difficultés à comprendre ou à utiliser certaines parties de celle-ci. Il est souvent utile de recevoir leurs commentaires pour améliorer votre bibliothèque: pour chaque personne qui a signalé un problème, il y en a peut-être des centaines qui, lorsqu'ils le rencontrent, préfèrent simplement passer à une autre bibliothèque.

En plus de cela:

1. Indiquez clairement si votre bibliothèque fonctionne avec Python 2 ou 3 ou les deux.

2. Si la bibliothèque ne fonctionne pas sous Windows, dites-le.

3. Assurez-vous d'utiliser les conventions officielles (utilisez pep8 pour vérifier). Sinon, expliquez-le clairement ou corrigez-le.

4. Prenez soin de manipuler les cas de bord. Lorsque votre bibliothèque est appelée avec un mauvais type ou avec une valeur qui n'est pas prise en charge, elle devrait dire, en anglais simple, ce qui ne va pas exactement. Ce qu'il ne devrait pas faire, c'est lever une exception cryptique de dix niveaux dans la pile et laisser l'utilisateur comprendre ce qui ne va pas.

Après avoir utilisé un bon nombre de bibliothèques moins que matures au fil des ans, un conseil clé est une fois que vous avez choisi votre outil de déploiement, procédez comme suit: Votre bibliothèque fait-elle quelque chose de vraiment utile pour créer une communauté?

Identifiez les dépendances de votre bibliothèque.

Tentez un déploiement dans un environnement propre, soit un conteneur de dossier ou une machine virtuelle. Je considère que cette étape est cruciale car, souvent, il y a quelque chose d'unique dans un environnement personnel qui cause des problèmes.

Considérez qui va entretenir la bibliothèque à l'avenir, il n'y a rien de plus frustrant que de tomber sur une bibliothèque qui a été le projet favori de quelqu'un pendant trois ou quatre ans et qui ne reçoit pas les mises à jour nécessaires pour la maintenir à jour.

Demandez-vous si vous ou votre équipe souhaitez vous engager à maintenir la bibliothèque testée et documentée (les tests unitaires et les pipelines CI commencent à faire partie de l'équation ici).

Peut-être pourriez-vous trouver un projet OSS mature dans votre domaine et apporter votre code à ce projet? Il pourrait y avoir quelques avantages, tels que:

• Vous pouvez maximiser votre contribution. En effet, de nombreux projets OSS "hobby" sont potentiellement précieux mais peu utilisés par la communauté (cf. réponse @ReaddyEddy). C'est juste beaucoup d'efforts pour mettre le projet à zéro au départ, puis pour le maintenir, le publier, fournir des exemples et une documentation appropriés, etc.
• Beaucoup de problèmes techniques que vous avez mentionnés seraient déjà résolus dans le projet mature.
• Si votre bibliothèque ajoute de la valeur au projet OSS, ses contributeurs pourraient vous aider à mettre votre code aux normes du projet. Vous pouvez ainsi économiser des efforts et acquérir de l'expérience. Vous obtiendrez également des réponses spécifiques sur Sphinx, TravisCI, CookieCutter et d'autres aspects techniques.

S'il y a un projet OSS pertinent que vous aimez et que vous utilisez peut-être, pourquoi ne pas ouvrir un problème ou une demande d'extraction ou contacter autrement les responsables? (Une bonne façon de commencer pourrait être de résoudre un problème existant.)

Nous sommes en 2019, je vous suggère fortement de commencer par les outils les plus modernes. Vous n'avez pas besoin d'un setup.py, c'est quelque chose que les gens de la communauté Python veulent se débarrasser, et je pense que finalement ils le feront.

Essayez la poésie , vous ne le regretterez pas.

C'est une question compliquée que vous posez, et je suis entièrement d'accord avec la réponse d'Arseni . Une bonne documentation est un aspect très important. Si je ne réussis pas à faire fonctionner votre bibliothèque en quelques étapes simples, je la laisse tomber juste là (à moins que je ne veuille vraiment l'essayer).

Certaines choses que vous considérez certainement

• Pensez à la façon dont vous allez mettre à jour votre bibliothèque. Vous voulez avoir une compatibilité ascendante à un certain niveau et des corrections de bugs le long de l'itinéraire également. En savoir plus sur le versioning sémantique
• Vous utilisez git de manière relativement linéaire (pour annuler). Connaissez-vous la ramification dans git . Ce n'est vraiment pas si difficile et rend la vie facile. Une fois que vous avez saisi les branches. Adaptez un modèle de branchement pour votre référentiel. Sélectionnez les parties de ce modèle de branchement que vous jugez pertinentes. Comparez également cela avec les branches des référentiels que vous utilisez.
• Licence: vous devez fournir une licence pour votre bibliothèque. Je ne suis pas un expert juridique sur cette question, je ne peux donc partager qu'un lien vers cette comparaison entre les licences communes . Ne prenez pas ce choix à la légère.
• Bugtracker. Vous voulez que cet utilisateur puisse vous fournir des rapports de bogues. Cela vous aide à améliorer la qualité du code. Pour chaque bogue que vous résolvez, ajoutez un test à votre travail de cadre de test, ce qui garantit qu'il ne freinera pas à l'avenir (test de régression). Un système de suivi des bogues peut être utilisé pour les demandes de fonctionnalités.
• Contributions des utilisateurs. Voulez-vous des contributions des utilisateurs? Je ne sais pas comment cela fonctionne généralement sur les produits open-source, mais je peux imaginer que vous pouvez permettre aux utilisateurs de créer des branches de fonctionnalités. Via github, vous semblez être en mesure de contrôler cela via des demandes de tirage

Je n'ai aucune expérience pertinente avec Python, donc je ne peux pas vous donner d'indices dans cette direction. Cependant, il est possible d'automatiser tous les tests déclenchés par chaque commit sur votre référentiel distant (c'est-à-dire en utilisant Jenkins ). Je suggère cependant de reporter cela, car il y a beaucoup de travail à mettre en place sans expérience préalable.

Ce sont de grandes questions.

À propos des étapes incrémentielles concrètes importantes vers une bibliothèque libérable:

• Séparez les fichiers qui deviendront la bibliothèque du reste du projet.
  • La bibliothèque devrait aller dans son propre référentiel git mais vous pourriez trouver cela une étape intermédiaire utile pour la placer dans un répertoire de niveau supérieur distinct dans votre référentiel actuel. Lorsque vous en faites un référentiel séparé, stockez-le à côté du reste de votre projet, qui peut ensuite s'y référer via ../libraryjusqu'à ce que vous passiez aux étapes de conditionnement pip et de mode de développement.
  • Tous les accès du reste du projet à cette bibliothèque doivent passer par son API publique. Vous pourriez trouver des interdépendances à démêler.
• Ecrivez progressivement des docstrings pour documenter l'API de la bibliothèque.
  • Finalement, les docstrings alimenteront un outil de documentation, mais le travail important est d'écrire le texte qui explique l'API de manière concise et suffisante à d'autres personnes. Il est plus facile de le remplir un peu à la fois que d'un seul coup, et il sortira beaucoup mieux en écrivant des ébauches brutes et en y revenant plus tard lorsque de meilleures explications et exemples viendront à l'esprit.
  • Si vous trouvez qu'une partie de l'API est difficile à documenter, demandez si cette partie de l'API peut être améliorée. Cela pourrait-il être plus simple? Plus régulier? Est-ce trop général? Trop spécialisé? Pourrait-il utiliser des noms plus familiers?
  • Les docstrings peuvent documenter les types d'arguments à l'aide de commentaires structurés que les outils peuvent vérifier. Je n'ai pas encore trouvé de vraie documentation à ce sujet, mais l'IDE PyCharm aidera à construire ces docstrings et vérifiera immédiatement les types d'arguments lors de l'édition des appels de méthode.
  • En parlant de cela, PyCharm est un merveilleux outil pour gagner du temps pour les développeurs et améliorer la qualité du code. Il exécutera des "inspections" pour vérifier le code pendant que vous le modifiez, par exemple en vérifiant les types quand il le peut, en vérifiant les importations manquantes et inutilisées, les méthodes en double, les erreurs de style PEP 8, etc.
• Commencez à écrire des tests unitaires à l'aide de pytest. Bien avant de publier une version, les tests unitaires porteront leurs fruits dans votre propre développement en trouvant des bogues dans les cas d'angle et en vous assurant que les changements de code n'ont pas cassé les choses. Encore une fois, vous pouvez construire cela au fil du temps. C'est assez facile à démarrer.
• Parcourez les bibliothèques open source existantes (qui sont à peu près de la même taille) sur GitHub pour voir comment elles organisent les fichiers et les versions. Regardez comment ils effectuent le suivi des bogues / problèmes et tirent les demandes. Contribuez à un ou plusieurs d'entre eux pour acquérir de l'expérience avec ces processus d'organisation de projet à plusieurs personnes si vous n'y avez pas d'expérience. GitHub dispose de bons outils pour ces processus. Il fait de belles choses avec README.mddes fichiers de documentation au niveau supérieur et dans n'importe quel répertoire, et avec un fichier de licence.
• Envisagez de faire appel à un collaborateur pour obtenir des commentaires sur la bibliothèque, son API et sa documentation.
  • Lorsque vous publierez, cela vous aidera à avoir un ou plusieurs collaborateurs pour corriger les bogues lorsque vous êtes en vacances, pour répondre aux questions des utilisateurs, et en attendant pour commencer à faire des requêtes Pull avec des révisions de code, pour diviser les tâches de publication de la bibliothèque, et apporter une expérience supplémentaire avec la gestion de projet et la conception de bibliothèque.
• Jusqu'à présent, vous avez fait un historique de commit git linéaire. Finalement, il sera utile d'utiliser des "branches de problèmes" pour des correctifs et des modifications spécifiques, des "branches de versions" pour l'exécution contrôlée d'une version et des "branches de développement" pour tout travail en cours pour plusieurs personnes qui n'est pas prêt à fusionner. dans la branche principale. Alors, réservez un jour ou deux en cours de route pour en savoir plus et commencez à vous entraîner avant de vous fier à ces compétences géniales. git est très flexible et utile mais l'interface utilisateur peut devenir lourde .
  • Un endroit pour lire sur les branches git et leurs utilisations est dans le livre Pro Git . Parmi les nombreuses façons d'utiliser les branches, commencez simplement par «émettre des branches».
  • L'application GitHub Desktop est un excellent outil pour gérer les succursales. Il est également idéal pour effectuer des validations car il permet d'écrire facilement le message de validation tout en examinant toutes les modifications.