Comment démarrer avec la librairie Requests en Python

Introduction

Dans de nombreuses apps, il est normal de se connecter à divers services tiers en utilisant des API. Lorsque vous utilisez ces API, vous pouvez accéder à des données telles que des informations météorologiques, des résultats sportifs, des listes de films, des tweets, des résultats de moteurs de recherche et des images. Vous pouvez également utiliser les API pour ajouter des fonctionnalités à votre application. Il peut s’agir par exemple de paiements, de programmation, de courriers électroniques, de traductions, de cartes et de transferts de fichiers. Si vous deviez les créer vous-même, cela prendrait énormément de temps, mais avec les API, il suffit de quelques minutes pour se connecter à l’une d’elles et accéder à ses fonctionnalités et à ses données.

Dans cet article, nous allons découvrir la librairie Python Requests, qui vous permet d’envoyer des requêtes HTTP en Python.

Et puisque l’utilisation d’une API consiste à envoyer des requêtes HTTP et à recevoir des réponses, Requests vous permet d’utiliser des API en Python. Nous allons démontrer ici l’utilisation d’une API de traduction afin que vous puissiez voir un exemple de son fonctionnement.

Aperçu rapide des requêtes HTTP

Les requêtes HTTP sont le mode de fonctionnement du web. Chaque fois que vous naviguez sur une page web, votre navigateur envoie de multiples requêtes au serveur de la page web. Le serveur répond alors avec toutes les données nécessaires pour afficher la page, et votre navigateur affiche effectivement la page pour que vous puissiez la voir.

Le processus générique est le suivant : un client (comme un navigateur ou un script Python utilisant des requêtes) envoie des données à une URL, puis le serveur situé à l’URL lit les données, décide quoi en faire et renvoie une réponse au client. Enfin, le client peut décider de l’usage qu’il veut faire des données contenues dans la réponse.

La méthode de requête est une partie des données que le client envoie dans une requête. GET, POST et PUT sont certaines méthodes de requêtes courantes. Les requêtes GET ne concernent normalement que la lecture de données sans apporter de modification à quelque chose, tandis que les requêtes POST et PUT concernent généralement la modification de données sur le serveur. Ainsi, par exemple, l’API Stripe vous permet d’utiliser des requêtes POST pour créer un nouveau tarif afin qu’un utilisateur puisse acheter quelque chose dans votre application.

Lorsque vous envoyez une requête à partir d’un script Python ou dans une application web, c’est vous, le développeur, qui décidez de ce qui est envoyé dans chaque requête et de ce qu’il faut faire de la réponse. Explorons donc cela en envoyant d’abord une demande à Scotch.io, puis en utilisant une API de traduction.

Installer des requêtes Python

Avant de pouvoir faire quoi que ce soit, nous devons installer la librairie. Alors allons-y et installons les requêtes en utilisant pip. C’est une bonne idée de créer en premier lieu un environnement virtuel si vous n’en possédez pas encore.

pip install requests

Notre première requête

Pour commencer, utilisons des requêtes que nous enverrons au site Scotch.io. Créez un fichier appelé script.py et ajoutez-y le code suivant. Dans cet article, nous n’aurons pas beaucoup de code avec lequel travailler, donc quand quelque chose change, vous pouvez simplement mettre à jour le code existant au lieu d’ajouter de nouvelles lignes.

import requests

res = requests.get('https://scotch.io')

print(res)

Ce code ne fait donc qu’envoyer une requête GET à Scotch.io. C’est le même type de requête que celles envoyées par votre navigateur pour afficher cette page. La seule différence est que les requêtes ne peuvent pas réellement rendre le HTML, donc, à la place vous obtiendrez juste le HTML brut et les autres informations de réponse.

Dans ce cas, nous utilisons la fonction .get(), mais Requests vous autorise à utiliser d’autres fonctions telles que .post() et .put() pour envoyer ces requêtes également.

Vous pouvez le lancer en exécutant le fichier script.py.

python script.py

Et voilà ce que vous obtenez en retour :

Codes de statuts

La première chose que nous pouvons faire est de vérifier le code de statut. Les codes HTTP vont de 1XX à 5XX. Les codes de statut courants que vous avez probablement déjà vus sont 200, 404 et 500.

Voici un bref aperçu de la signification de chaque code de statut :

• 1XX - Information
• 2XX - Succès
• 3XX - Redirection
• 4XX - Erreur Client (vous avez fait une erreur)
• 5XX - Erreur Serveur (il a fait une erreur)

En général, ce que vous recherchez lorsque vous effectuez vos propres requêtes sont des codes de statut situés autour de 200.

Requests reconnait que les codes de statut 4XX et 5XX sont des erreurs, donc si ces codes de statut sont renvoyés, l’objet de réponse de la requête est évalué à False.

Vous pouvez vérifier si une requête a répondu avec succès en vérifiant la véracité de la réponse. Par exemple :

if res:
    print('Response OK')
else:
    print('Response Failed')

Le message “Response Failed” n’apparaîtra que si un code de statut 400 ou 500 est renvoyé. Essayez de changer l’URL par une absurdité pour voir la réponse échouer avec un 404.

Vous pouvez consulter directement le code de statut en ajoutant :

print(res.status_code)

Le code de statut sera alors directement indiqué afin que vous puissiez vérifier vous-même le numéro.

En-têtes

Les en-têtes sont une autre chose que vous pouvez obtenir de la réponse. Vous pouvez les consulter en utilisant le dictionnaire des en-têtes sur l’objet de réponse.

print(res.headers)

Les en-têtes sont envoyés avec la demande et renvoyés dans la réponse. Les en-têtes sont utilisés pour que le client et le serveur sachent comment interpréter les données qui sont envoyées et reçues dans la réponse/réponse.

Nous voyons les différents en-têtes qui sont renvoyés. La plupart du temps, vous n’aurez pas besoin d’utiliser directement les informations d’en-tête, mais elles sont là si vous en avez besoin.

Le type de contenu est généralement celui dont vous pouvez avoir besoin, car il révèle le format des données (par exemple HTML, JSON, PDF, texte, etc). Mais le type de contenu est normalement traité par Requests, de sorte que vous pouvez accéder aux données qui vous sont renvoyées.

Texte de réponse

Et, enfin, si nous examinons res.text (cela fonctionne pour les données textuelles (pour une page HTML par exemple, comme celle que nous visualisons), nous pouvons voir tout le HTML nécessaire pour construire la page d’accueil de Scotch. Il ne sera pas affiché, mais on voit qu’il semble appartenir à Scotch. Si vous l’enregistriez dans un fichier et l’ouvriez, vous verriez quelque chose qui ressemblerait au site de Scotch. Dans une situation réelle, plusieurs requêtes sont faites pour qu’une seule page web charge des éléments tels que des images, des scripts et des feuilles de style. Ainsi, si vous n’enregistrez que le HTML dans un fichier, celui-ci ne ressemblera pas du tout à la page Scotch.io de votre navigateur, car une seule requête a été effectuée pour obtenir les données HTML.

print(res.text)

Utilisation de l’API de traduction

Passons maintenant à quelque chose de plus intéressant. Nous utiliserons l’API Yandex Translate pour effectuer une demande de traduction d’un texte dans une autre langue.

Pour utiliser l’API, vous devez d’abord vous inscrire. Après vous être inscrit, allez dans l’API de traduction et créez une clé API. Une fois que vous avez la clé API, ajoutez-la à votre fichier comme une constante. Voici le lien vous permettant de réaliser toutes ces choses : https://tech.yandex.com/translate/

API_KEY = 'your yandex api key'

Nous avons besoin d’une clé API pour que Yandex puisse nous authentifier chaque fois que nous voulons utiliser leur API. La clé API est une forme d’authentification légère, car elle est ajoutée à la fin de l’URL de la requête lors de l’envoi.

Pour savoir quelle URL nous devons envoyer pour utiliser l’API, nous pouvons consulter la documentation pour Yandex.

Si nous la consultons, nous découvrirons toutes les informations nécessaires à l’utilisation de l’API de traduction pour traduire le texte.

Lorsque vous voyez une URL avec des esperluettes (&), des points d’interrogation ( ?) et des signes égaux (=), vous pouvez être sûr que l’URL est destinée à des requêtes GET. Ces symboles précisent les paramètres qui accompagnent l’URL.

Normalement, les éléments entre crochets ([[ ]]) sont facultatifs. Dans ce cas, le format, les options et le rappel sont facultatifs, tandis que la clé, le texte et la langue sont requis pour la requête.

Ajoutons donc un peu de code à envoyer à cette URL. Vous pouvez remplacer la première requête que nous avons créée par celle-ci :

url = 'https://translate.yandex.net/api/v1.5/tr.json/translate'
res = requests.get(url)

Il y a deux façons d’ajouter les paramètres. Nous pouvons soit l’ajouter directement à la fin de l’URL, soit faire en sorte que Requests le fasse pour nous. Dans ce dernier cas, nous pouvons créer un dictionnaire pour nos paramètres. Les trois éléments dont nous avons besoin sont la clé, le texte et la langue. Créons un dictionnaire en utilisant la clé API, 'Hello' pour le texte et 'en-es' pour la langue, ce qui signifie que nous voulons traduire de l’anglais vers l’espagnol.

Si vous avez besoin de connaître d’autres codes de langue, vous pouvez regarder ici. Vous recherchez la colonne 639-1.

Nous créons un dictionnaire de paramètres en utilisant la fonction dict() et en y introduisant les clés et les valeurs que nous voulons dans notre dictionnaire.

params = dict(key=API_KEY, text='Hello', lang='en-es')

Maintenant, nous prenons le dictionnaire des paramètres et nous le passons à la fonction .get().

res = requests.get(url, params=params)

Lorsque nous passerons les paramètres de cette façon, Requests poursuivra et ajoutera les paramètres à l’URL pour nous.

Ajoutons maintenant une instruction print pour le texte de la réponse et voyons ce qui est renvoyé dans la réponse.

print(res.text)

Nous voyons trois choses. Nous voyons le code de statut, qui est exactement le même que celui de la réponse elle-même, nous voyons la langue que nous avons spécifiée, et nous voyons le texte traduit à l’intérieur de la liste. Vous devriez donc voir 'Hola' pour le texte traduit.

Essayez de nouveau avec en-fr comme code de langue, et vous devriez maintenant voir 'Bonjour' dans la réponse.

params = dict(key=API_KEY, text='Hello', lang='en-fr')

Examinons les en-têtes de cette réponse en particulier.

print(res.headers)

Il est évident que les en-têtes doivent être différents, car nous communiquons avec un autre serveur, mais dans ce cas, le type de contenu est application/json au lieu de text/html. Ce qui signifie que les données peuvent être interprétées comme JSON.

Lorsque application/json est le type de contenu de la réponse, nous pouvons demander à Requests de convertir la réponse en un dictionnaire et une liste afin de faciliter l’accès aux données.

Pour que les données soient analysées en tant que JSON, nous utilisons la méthode .json() sur l’objet de réponse.

Si vous l’imprimez, vous verrez que les données sont identiques, mais que le format est légèrement différent.

json = res.json()
print(json)

Elle est différente parce que ce n’est plus du texte brut que l’on obtient à partir de res.text. Cette fois, il s’agit d’une version imprimée d’un dictionnaire.

Disons que nous voulons accéder au texte. Étant donné il s’agit désormais d’un dictionnaire, nous pouvons utiliser la clé texte.

print(json['text'])

Et maintenant, nous voyons seulement les données pour cette seule clé. Dans ce cas, il s’agit d’une liste d’un seul élément, donc si nous voulions obtenir ce texte directement dans la liste, nous pourrions y accéder par l’index.

print(json['text'][0])

Et maintenant, la seule chose que nous voyons, c’est le mot traduit.

Donc, bien sûr, si nous modifions nos paramètres, nous obtiendrons des résultats différents. Modifions le texte à traduire de Hello à Goodbye, changeons la langue cible pour l’espagnol et envoyons à nouveau la requête.

params = dict(key=API_KEY, text='Goodbye', lang='en-es')

Essayez de traduire un texte plus long dans différentes langues et observez les réponses que vous donne l’API.

Les cas d’erreur de l’API de traduction

Enfin, nous examinerons un cas d’erreur. Tout ne fonctionne pas toujours, nous devons donc savoir quand cela se produit.

Essayez de changer votre clé API en supprimant un caractère. Dans ce cas, votre clé API ne sera plus valide. Essayez ensuite d’envoyer une demande.

Si vous regardez le code de statut, voici ce que vous obtenez :

print(res.status_code)

Ainsi, lorsque vous utiliserez l’API, vous voudrez vérifier si les choses se passent bien ou non afin de pouvoir traiter les cas d’erreur en fonction des besoins de votre application.

Conclusion

Voici ce que nous avons appris :

• Comment fonctionnent les requêtes HTTP
• Les différents codes de statuts possibles dans une réponse
• Comment envoyer des demandes et recevoir des réponses en utilisant la librairie Python Requests
• Comment utiliser une API de traduction pour traduire un texte
• Comment convertir les réponses d’apps et de contenus JSON en dictionnaires

Si vous souhaitez en faire plus, consultez cette liste pour voir les différentes API disponibles et essayer de les utiliser avec Python Requests.