10 étapes pour réussir un projet Python

Le matériel, dont nous publions la traduction aujourd'hui, est consacré aux outils qui permettent d'équiper les projets Python avec des outils de formatage de code, de test, d'intégration continue et d'analyse de dépendance. Cela permet d'accélérer le processus de développement, d'améliorer la qualité, l'uniformité et la sécurité du code. Il est supposé que le lecteur de ce matériel a déjà une certaine expérience dans le développement de Python et un projet Python avec lequel, pendant la lecture, il expérimentera. Si vous n'avez pas un tel projet, vous pouvez apprendre ici comment préparer un environnement de développement et créer un package Python. Les exemples qui seront donnés ici sont préparés en utilisant macOS et Python 3.7.

Étape 1. Installation de Black

Le code du projet doit suivre les conventions de style de code. Black est un package Python qui formate automatiquement le code, apportant son apparence à la norme PEP 8 . Black est un projet relativement nouveau, mais il a déjà gagné plus d'un million de téléchargements. Son utilisation est rapidement devenue un signe de bon goût dans le développement de Python. Voici le manuel Black.

En tant qu'éditeur de code, j'utilise Atom, j'ai donc ajouté le package Python-Black à Atom. Vous pouvez découvrir comment l'installer ici . Après avoir installé ce package, Atom reformatera le code après avoir enregistré le fichier.

Pendant que nous parlons de Black - équipons cet outil de l'environnement de développement de ceux qui travaillent avec nous sur le projet. Par conséquent, tous ceux qui travaillent sur le projet utiliseront les mêmes règles de formatage de code, sinon leurs demandes d'extraction ne seront pas acceptées.

Ajoutez le black==18.9b0 à la première ligne libre trouvée du fichier requirements_dev.txt et exécutez la commande install -r requirements_dev.txt .

Le noir, par défaut, définit la longueur de la ligne de code à 88 caractères. Certains guides de style, tels que Sphinx , nécessitent une longueur de chaîne de 79 caractères. Dans les paramètres du package Black-Atom , vous pouvez définir la longueur de ligne souhaitée.

Maintenant que nous avons acquis un outil qui permettra de gagner du temps sur le formatage du code, nous allons réfléchir à la façon d'accélérer et de simplifier l'envoi de code à PyPI.

Étape 2. Création du fichier .pypirc

Lorsque la ficelle est utilisée pour envoyer des assemblys d'application à TestPyPI et PyPI, vous devez saisir manuellement les informations de connexion. Si vous n'êtes pas familier avec la ficelle, jetez un œil à ce matériau. Nous allons maintenant automatiser ce processus.

Twine peut fonctionner avec le fichier .pypirc , qui devrait se trouver dans notre répertoire personnel. Cet outil, déchargeant des données, prend une URL, un nom d'utilisateur et un mot de passe d'un fichier donné.

Alors, créez un fichier .pypirc dans votre répertoire personnel:

 touch ~/.pypirc 

Ajoutez-y le texte suivant:

 [distutils] index-servers =   pypi   testpypi [testpypi] repository: https://test.pypi.org/legacy username = your_username password = your_pypitest_password [pypi] username = your_username password = your_pypi_password 

Il est clair que vous devez saisir ici votre véritable nom d'utilisateur et mot de passe. Vérifiez également que ce fichier est enregistré dans le répertoire de base et non dans le répertoire de travail actuel. Si vous souhaitez protéger ce fichier des autres utilisateurs, vous pouvez, à l'aide des outils de ligne de commande, configurer ses autorisations:

 chmod 600 ~/.pypirc 

Maintenant, votre package peut être chargé dans TestPyPI à l'aide de la commande suivante:

 twine upload -r testpypi dist/* 

Dans PyPI standard, vous pouvez charger des packages comme celui-ci:

 twine upload dist/* 

Après avoir obtenu le fichier .pypirc , vous n'avez plus à saisir manuellement votre nom d'utilisateur et votre mot de passe.

Ajoutons maintenant des outils de test à notre environnement de développement qui nous permettront de vérifier le bon fonctionnement du package que nous créons.

Étape 3. Installez et configurez pytest

Pytest est la bibliothèque la plus populaire et la plus facile à utiliser pour tester le code écrit en Python. Dans cet exemple, nous allons ajouter des tests simples au projet. Maintenant , si vous êtes intéressé par les détails de pytest, un bon guide d'introduction à cet outil.

Ajoutez des détails pytest à requirements_dev.txt :

 pytest==4.3.0 

Installons le package:

 pip install requirements_dev.txt 

Exécutez maintenant la commande suivante, qui permettra à pytest de trouver notre package:

 pip install -e . 

Si vous avez désactivé votre environnement de développement virtuel, vous devrez à nouveau exécuter les deux commandes pip pour exécuter les tests.

Étape 4. Création de tests

Ajoutez le dossier de test répertoire racine de votre projet. Placez-y le fichier test_your_package_name.py . Mon fichier s'appelle test_notebookc.py . Si le nom du fichier commence par test_ , pytest peut détecter automatiquement un tel fichier.

J'ai ajouté le test suivant au fichier test_notebookc.py , qui vise à vérifier si la fonction affiche le nom correct. Modifiez ce code afin que les noms de fichiers et de fonctions utilisés correspondent aux vôtres, décrivez-y vos propres tests.

 """Tests for `notebookc` package.""" import pytest from notebookc import notebookc def test_convert(capsys):   """Correct my_name argument prints"""   notebookc.convert("Jill")   captured = capsys.readouterr()   assert "Jall" in captured.out 

Que se passe-t-il ici?

Nous importons d'abord notre module ici. Ensuite, nous créons une fonction dont le nom est construit selon le modèle test_my_function_name . Cette convention de dénomination de fonction permet à d'autres personnes lisant le code de votre projet de comprendre rapidement ce qui est testé exactement dans les tests. De plus, cela est nécessaire pour un package qui aide à contrôler la couverture du code avec des tests, dont nous discuterons ci-dessous.

Après cela, nous appelons la fonction ( convert ), en lui passant le nom Jill comme argument. Ensuite - capturez ce que la fonction affiche. Ici, il convient de dire que la fonction en question est extrêmement simple. Elle prend le paramètre my_name et effectue les opérations suivantes:

 print(f"I'll convert a notebook for you some day, {my_name}.") 

Pytest vérifie si Jall est Jall dans ce que la fonction génère. Cette ligne ne devrait pas être là, car nous passons des fonctions Jill . Voici la documentation pytest où vous pouvez trouver des informations sur l'interception de la sortie.

Exécutez le test en tapant pytest à l'invite de commande. Ce test devrait échouer. Les informations d'erreur s'affichent en rouge.


Une erreur a été détectée lors du test.

Il est recommandé de vérifier l'exactitude des tests, en les décrivant afin que, dans certaines conditions, ils se terminent par une erreur. Vous ne devez pas écrire de tests qui ne donnent que des messages verts, sinon il se peut que les tests ne vérifient pas du tout ce qu'ils sont écrits pour vérifier.

Après avoir Jall que le test a échoué, remplacez l'instruction Jall par Jill et exécutez à nouveau le test. Maintenant, il devrait se terminer avec succès.


Réussite du test.

Maintenant tout va bien. Le test vous permet de vous assurer que si quelqu'un passe une ligne à notre fonction, cette ligne tombera dans le texte que cette fonction affiche.

Vous pouvez également écrire un test qui vérifie la fonction sur la façon dont elle gère les données qui lui sont transmises. À savoir, s'il reçoit des données dont le type est différent de la chaîne, il doit provoquer une erreur TypeError. Voici quelques bonnes choses sur les exceptions et la gestion des erreurs en Python.

Lorsque nous avons créé le test précédent, nous avons écrit du code qui conduit à la réussite du test. C'est ce qu'on appelle le développement piloté par les tests (TDD). TDD est une approche de programmation éprouvée qui vous aide à écrire du code qui contient moins d'erreurs que sans TDD. Voici du matériel TDD utile.

Maintenant, en tant qu'exercice, essayez d'écrire un test qui vérifie la fonction convert() afin que lors du passage de quelque chose de différent de la chaîne, il génère une erreur et implémente les mécanismes appropriés pour cette fonction. Notez que les entiers, les listes et les dictionnaires sont convertis en chaînes.

Une fois que le package a réussi les tests, nous sommes prêts à profiter du système d'intégration continue.

Étape 5. Inscription au service Travis CI et sa configuration

Travis CI est un "service Web distribué pour la création et le test de logiciels". Il a été récemment acheté par Idera . Il existe d'autres systèmes d'intégration continue, mais Travis CI est un outil populaire, open source et bien documenté, nous allons donc l'utiliser.

Travis CI vous permet d'intégrer dans votre projet uniquement le code qui passe les tests et répond aux normes. Ici, vous pouvez en savoir plus sur Travis CI et ici sur l' intégration continue.

Créez un compte sur https://travis-ci.org/ . Ensuite, cliquez sur le lien Review and add your authorized organizations sur la page de profil. Vous serez invité à entrer un mot de passe pour accéder à GitHub. Cliquez sur Grant dans la section Organization access à l' Organization access .


Configurer un compte Travis CI

J'ai dû synchroniser le compte pour que les informations sur notebooktoall et le référentiel notebookc apparaissent dans le compte. En général, pour que Travis CI fonctionne avec du code, cela prend environ une minute. Après cela, vous devez activer le référentiel à l'aide du commutateur illustré dans la figure suivante.


Activation du référentiel

Cliquez maintenant sur le bouton Settings . Ici, vous devez indiquer si Travis peut créer en fonction des demandes d'extraction ou des branches envoyées au référentiel.


Configuration de la construction du projet

Il est maintenant temps de configurer le projet sur lequel nous travaillons, ce qui permettra à Travis de créer le projet pour chaque demande de tirage.

Étape 6. Création du fichier .travis.yml

Dans le dossier racine du projet, créez un fichier .travis.yml avec le contenu suivant:

 dist: xenial language: python python: 3.7.2 install: - pip install -r requirements_dev.txt - pip install -e . script: - pytest 

La ligne dist: xenial nécessaire pour indiquer à Travis d'utiliser Ubuntu Xenial 16.04 pour organiser l'environnement virtuel. Pour tester le code Python 3.7, Ubuntu Xenial est nécessaire, des détails à ce sujet peuvent être trouvés ici .

La section d' install vous permet d'installer des packages utilisés dans le développement de projet. Commande pip install -e . effectue l'installation de notre package dans l'environnement virtuel de Travis. Après cela, Travis, en commençant pytest, pourra retrouver notre package.

Étape 7. Test dans Travis CI

Validez les modifications, soumettez-les à GitHub, faites le RP. Travis devrait commencer à travailler en quelques secondes.


Travis au travail

C'est ce que Travis fait dans la gestion du projet.


Actions effectuées par Travis pendant le traitement du projet

Si le PR n'a pas réussi - Travis le signalera. Veuillez noter que si la demande d'extraction échoue, vous pouvez envoyer les modifications à la même branche et Travis commencera automatiquement à fonctionner.

Accédez à la page de votre référentiel sur le site Web de Travis et regardez autour de vous. Ici vous pouvez trouver beaucoup de choses intéressantes sur les assemblages. À l'avenir, vous deviendrez probablement un invité fréquent de cette page lorsque vous tenterez de comprendre la cause de l'échec de l'assemblage.

Si nous supposons que tout s'est bien passé, si la page contient des étiquettes vertes, la vérification et l'assemblage du projet ont réussi.


Assemblage du projet terminé avec succès

S'il n'y a pas d'étiquettes vertes ou rouges sur la page, ouvrez le menu More options et sélectionnez Requests . Si vous voyez des messages d'erreur rouges ici, analysez-les. Si le message d'erreur Build config file is required s'affiche, cela signifie que Travis ne peut pas trouver votre fichier .travis.yml dans le référentiel. Corrigez-le et l'erreur disparaîtra.

Travis envoie des e-mails aux utilisateurs dans les cas où l'assemblage du projet échoue et dans les cas où il est possible de le corriger.

N'oubliez pas que vous pouvez envoyer des validations pour ouvrir PR et Travis redémarrera automatiquement le processus de construction du projet.

Analysons maintenant notre projet pour couvrir le code avec des tests.

Étape 8. Évaluation de la couverture du code avec des tests

Le rapport sur la couverture du code avec des tests vous permet de savoir quelle partie du code du projet, même petite, a été testée. Pour créer de tels rapports, nous utiliserons le package pytest-cov .

Ajoutez la ligne suivante au fichier requirements_dev.txt :

 pytest-cov==2.6.1 

Exécutez la commande suivante:

 pytest --cov=my_project_name 

Dans mon cas, après l' pytest --cov=notebookc , le rapport suivant a été affiché.


Rapport sur la couverture du code

Il s'est avéré que tout le code du projet est fourni avec des tests. De tels indicateurs sont très faciles à réaliser si l'ensemble du projet se compose de plusieurs lignes de code.

Parlons maintenant d'un outil qui vous permet de garder un historique public de l'état du projet en termes de couverture de son code avec des tests.

Étape 9. Utilisation de combinaisons

Le projet Coveralls vous permet de conserver des informations historiques sur la couverture du code avec des tests.


Combinaisons

Afin de profiter des capacités de ce projet, vous devez vous inscrire sur le site https://coveralls.io/ en utilisant les données de votre compte GitHub. Ensuite, vous devez connecter le référentiel.

Dans le fichier requirements_dev.txt , ajoutez la coveralls==1.6.0 lignes coveralls==1.6.0 . Soit dit en passant, ce fichier à ce stade du travail sur le projet devrait ressembler à ceci:

 pip==19.0.3 wheel==0.33.0 twine==1.13.0 pytest==4.3.0 pytest-cov==2.6.1 coveralls==1.6.0 

.travis.yml fichier .travis.yml , en l'amenant sous cette forme (dans votre cas, le nom de votre projet sera ici):

 dist: xenial language: python python: 3.7.2 install: — pip install -r requirements_dev.txt — pip install -e . script: — pytest --cov=my_package_name after_success: — coveralls 

Maintenant, lorsque Travis construira le projet, il installera les packages nécessaires, exécutera les tests et créera un rapport sur la couverture du code avec les tests. Ce rapport sera ensuite envoyé au service Coveralls.

Validez, soumettez le code à GitHub et regardez ce qui se passe. Cela peut prendre quelques minutes pour que le rapport de test de couverture de code entre dans les combinaisons.


Traitement de projet, rapport de couverture de test

Maintenant, parmi les contrôles PR, il y a aussi un contrôle effectué par Coveralls.

Sur la page Combinaisons, vous pouvez vérifier que le projet est couvert à 100% par des tests.


Informations sur la couverture du test

Équipons maintenant notre projet d'un autre outil utile.

Étape 10. Travailler avec PyUp

Le service PyUp.io permet au développeur de savoir si les dépendances utilisées par lui sont obsolètes et si elles présentent des vulnérabilités. Ce service exécute automatiquement les demandes d'extraction visant à mettre à jour le package sur GitHub. Afin de profiter des capacités de ce projet, vous devez vous inscrire en utilisant un compte GitHub, sur son site Web - https://pyup.io/ . Lors de l'ajout d'un référentiel, il est recommandé de définir les Update Schedules à Update Schedules sur every week . Avec cette approche, si votre projet comporte de nombreuses dépendances, vous ne rencontrerez pas trop de demandes d'extraction.


Configurer les mises à jour

Voici à quoi ressemblent les informations sur les packages, dont certaines sont obsolètes, sur le site Web PyUp.io.


Détails du paquet

En utilisant ce service, vous serez toujours informé de la date de sortie des dernières versions des packages que vous utilisez. La connaissance, comme on dit, représente la moitié de la victoire. Et la seconde moitié est, évidemment, des pull-requests automatiques pour la mise à jour des dépendances.

Résumé

Dans cet article, vous avez appris à utiliser des outils tels que Black, pytest, Travis CI, Coveralls et PyUp lors du développement de projets Python. Ils permettent de contrôler les dépendances du projet, de formater et de tester le code, et de vérifier et de construire des projets. Nous espérons que ces outils vous seront utiles.

Chers lecteurs! Quels outils utilisez-vous lors du développement de projets Python?