pynblint

De nombreux scientifiques professionnels utilisent un cahier Jupyter pour accomplir leurs tâches quotidiennes, de l'exploration préliminaire des données au prototypage modèle. L'interactivité des ordinateurs portables est particulièrement pratique pour la programmation centrée sur les données et leur nature auto-documentaire fournit un excellent support pour la communication des résultats analytiques.

Néanmoins, le cahier Jupyter a souvent été critiqué pour avoir induit de mauvaises habitudes de programmation et soutenu à peine les meilleures pratiques d'ingénierie logicielle. Pour vraiment bénéficier des ordinateurs portables, les utilisateurs doivent être conscients de leurs pièges communs et apprendre à les empêcher.

Dans les travaux antérieurs (voir «Iliter les meilleures pratiques pour la collaboration avec les cahiers de calcul» [1]), nous avons introduit un catalogue de 17 directives validées empiriquement pour l'utilisation collaborative des cahiers dans un contexte professionnel.

Pour favoriser l'adoption de ces meilleures pratiques, nous avons créé PyNBLINT, un outil d'analyse statique pour les cahiers de jupyter écrits dans Python. PyNBLINT révèle des défauts potentiels du cahier et recommande des actions correctives. Il peut être utilisé soit comme une application CLI autonome, soit dans le cadre d'un pipeline CI / CD.

Les règles de liaison de base de PyNBLINT ont été dérivées comme opérationnalisations des meilleures pratiques de notre catalogue. Néanmoins, l'architecture plug-in de PyNBLINT permet à ses utilisateurs d'étendre facilement l'ensemble central de vérifications avec leurs propres règles de liaison.

Exigences

Python 3.7+.

Installation

PyNblint peut être installé avec pip ou un autre gestionnaire de packages PYPI:

pip install pynblint

Après l'installation, nous vous recommandons d'explorer l'interface de ligne de commande de l'outil:

pynblint --help

Usage

PyNblint peut être utilisé pour analyser:

• Un cahier autonome:

  pynblint path/to/the/notebook.ipynb

• Un référentiel de code contenant des cahiers:

  pynblint path/to/the/project/dir/

  • (peut-être également comprimé en tant qu'archive .zip ):

    pynblint path/to/the/compressed/archive.zip

• Un référentiel public GitHub contenant des cahiers (le support pour les référentiels privés est sur notre feuille de route?):

  pynblint --from-github https://github.com/collab-uniba/pynblint

Pour plus d'informations sur les options disponibles, veuillez vous référer à la documentation du projet.

Catalogue des meilleures pratiques

PyNBLINT met actuellement en œuvre 22 règles de liaison:

• 17 règles applicables aux cahiers autonomes;
• 5 Règles applicables aux référentiels entiers de la science des données.

Ces règles sont dérivées de notre catalogue complet de meilleures pratiques pour le développement de cahiers collaboratifs [1]. Vous trouverez ci-dessous l'état de mise en œuvre actuel des règles de liaison associées à chaque meilleure pratique:

• ✅ Complete: pleinement implémenté
• ? Partial: partiellement mis en œuvre avec des améliorations planifiées
• ⏳ En cours: mise en œuvre prévue pour les futures versions
• Pas prévu: aucune mise en œuvre prévue

Meilleures pratiques de [1]	Statut	Détails
1. Utilisez le contrôle de la version	✅ Complete	Entièrement implémenté
2. Gérer les dépendances du projet	✅ Complete	Entièrement implémenté
3. Utilisez des environnements autonomes	⏳ en cours:	Planifié : détection de - Environnements virtuels Python (par exemple, créés avec venv , pyenv ou conda ) - Environnements conteneurisés (par exemple, Docker).
4. Mettez les importations au début	✅ Complete	Entièrement implémenté
5. Assurer la réexécution (re-diriger les cahiers de haut en bas)	✅ Complete	Entièrement implémenté
6. Modulariser votre code	? Partiel	Current : Détection des constructions de modularisation dans les ordinateurs portables. Planifié : recommandations de refactorisation axées sur la modularisation basées sur des modèles détectés
7. Testez votre code	? Partiel	Courant : Détection au niveau du référentiel des données de couverture. Planifié : détection des modules de test / fonctions indépendamment des outils de couverture
8. Nommez vos cahiers de manière cohérente	✅ Complete	Entièrement implémenté
9. Tenez-vous aux normes de codage	? Partiel	Courant : détection des cellules avec syntaxe Python non valide. Planise : Intégration de liners Python tels que Pylint, Flake8 et Ruff
10. Utilisez des chemins relatifs	⏳ en cours:	Planifié : Identification des instances de chemins absolus dans les cahiers et recommandation de chemins relatifs correspondants
11. Documenter votre analyse	✅ Complete	Entièrement implémenté
12. Tirez parti des en-têtes Markdown pour structurer votre cahier	✅ Complete	Entièrement implémenté
13. Gardez votre cahier propre	✅ Complete	Entièrement implémenté
14. Gardez votre cahier concis	✅ Complete	Entièrement implémenté
15. Distinguer les artefacts de production et de développement	Pas planifié	Implémentation jugée irréalisable (voir la note ci-dessous)
16. Rendez vos cahiers disponibles	⏳ en cours:	Planifié : Pynblint s'assurera que les cahiers marqués comme publiés dans sa configuration sont disponibles en ligne
17. Rendez vos données disponibles	✅ Complete	Entièrement implémenté

Remarque : Les meilleures pratiques # 15 (distinctives des artefacts de production / développement) ne seront pas mises en œuvre car il n'y a pas de critères objectifs pour déterminer cette distinction par analyse statique des cahiers ou des référentiels.

Licence

Ce projet est concédé sous licence de la licence du MIT.

Références

[1] Luigi Quaranta, Fabio Calefato et Filippo Lanubile. 2022. Provoquer les meilleures pratiques de collaboration avec des cahiers de calcul. Proc. ACM HUM.-Comput. Interagir. 6 , CSCW1, article 87 (avril 2022), 41 pages. https://doi.org/10.1145/3512934