Chapitre 4.3 - CSV, JSON et requetes.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Chapitre 4.3 - Les fichiers CSV, JSON et les requêtes\n",
    "\n",
    "---\n",
    "\n",
    "## 1. La structure du web : comment communique-t-on avec un serveur ?\n",
    "\n",
    "![Anatomie d'une communication HTTP](images/http.request.scheme.png)\n",
    "\n",
    "Lors d'une communication HTTP avec un serveur, la communication est divisible en deux : l'envoi de la requête et la réponse du serveur. Ces deux éléments de la communication répondent à un ensemble de standards très stricts permettant le fonctionnement du web tel que nous le connaissons."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.A. Anatomie d'une requête :\n",
    "\n",
    "![Anatomie d'une requête HTTP](images/http.request.request.png)\n",
    "\n",
    "La requête, c'est-à-dire l'information envoyée au serveur, est composée à minima de trois types d'informations :\n",
    "\n",
    "- l'URL\n",
    "- la méthode\n",
    "- les headers\n",
    "\n",
    "#### URL\n",
    "\n",
    "Voir le [schéma](images/url.png) ([Source](https://cascadingmedia.com/assets/images/insites/2015/02/url-anatomy/url-anatomy-55598c24.png) \n",
    "L'URL est une information que l'on connait tous. C'est l'adresse dont on requiert le contenu. Typiquement, l'adresse est divisible en plusieurs parties. Celle qui peut être importante et qui changera surement suivant les utilisateurs est la partie *query* qui permet d'apporter des informations supplémentaires.\n",
    "\n",
    "Par exemple, dans http://cts.dh.uni-leipzig.de/api/cts?request=GetCapabilities&urn=urn:cts:latinLit:phi1294 , on a deux paramètres fournis :\n",
    "\n",
    "| Nom | Valeur |\n",
    "| --- | ------ |\n",
    "| urn | urn:cts:latinLit:phi1294 |\n",
    "| request | GetCapabilities |\n",
    "\n",
    "#### Méthode\n",
    "\n",
    "La méthode informe le serveur de ce que vous allez vouloir faire. 90% des requêtes que vous faites en naviguant sur le web sont en GET : vous récupérez de l'information. Vous utilisez sur les 9.9% restant la requête POST, notamment quand vous vous connectez sur vos comptes sur les divers sites que vous utilisez.\n",
    "\n",
    "#### Les Headers\n",
    "\n",
    "Le Header comporte des informations sur vos attentes et votre contexte de requêtage. Par exemple, on peut demander via les Headers un format de réponse particulier (d'après son [mimetype](https://fr.wikipedia.org/wiki/Type_MIME) : html, xml ou json par exemple : \n",
    "\n",
    "| Headers Clé | Headers Valeur   |\n",
    "| ----------- | ---------------- |\n",
    "| Accept      | application/json |\n",
    "\n",
    "#### (Optionnel) Le Corps (Body, data, etc.)\n",
    "\n",
    "Dans le cadre de l'envoi d'un formulaire ou d'un fichier, on a un corps dans la requête. Beaucoup de formats différents sont possibles dans ce cadre. De nombreuses API acceptent par exemple l'encodage en JSON de vos informations."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.B. Anatomie d'une réponse\n",
    "\n",
    "![Anatomie d'une réponse HTTP](images/http.request.response.png)\n",
    "\n",
    "La réponse est composée de trois éléments aussi :\n",
    "\n",
    "#### Les Headers \n",
    "\n",
    "Tout comme la requête, les Headers nous renvoient l'information sur la réponse. Voici quelques headers utiles.\n",
    "\n",
    "\n",
    "| Headers Clé | Headers Valeur   | Note |\n",
    "| ----------- | ---------------- | ---- |\n",
    "| Encoding      | application/json | Type Mime de la réponse |\n",
    "\n",
    "#### Le code HTTP\n",
    "\n",
    "Le code HTTP nous informe sur le statut de la réponse. Vous connaissez *à minima* le code 404, qui indique que la ressource demandée n'est pas disponible. Il existe bien d'autres codes (*cf.* [Wikipedia](https://fr.wikipedia.org/wiki/Liste_des_codes_HTTP) :\n",
    "- 200 : succès de la requête ;\n",
    "- 301 et 302 : redirection, respectivement permanente et temporaire ;\n",
    "- 401 : utilisateur non authentifié ;\n",
    "- 403 : accès refusé ;\n",
    "- 404 : page non trouvée ;\n",
    "- 500 et 503 : erreur serveur.\n",
    "- 418 : \"I’m a teapot\" (Blague du 1er avril 1998 restée dans le standard)\n",
    "\n",
    "\n",
    "\n",
    "#### Le Corps\n",
    "\n",
    "Le corps de la réponse contient bien évidemment ce que vous voyez lorsque vous faites une requête : le contenu html, le contenu en plein texte, le contenu json, etc."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Faire des requêtes http en python : le module request\n",
    "\n",
    "\n",
    "### 2.A Le module `requests`\n",
    "\n",
    "Tout comme il existe pour python des modules pour gérer les CSV et les JSON, il en existe pour faire des requêtes WEB. Cela dit, ils ne font pas partie du coeur de Python ! C'est pour ça que nous les avons installés. En effet, quant à l'installation, vous avez tapé `pip install -r requirements.txt`, vous avez demandé à PIP (un gestionnaire de dépendances/librairies de python) d'installer chaque librairie citée dans le fichier `requirements.txt`. L'une d'entre elles était `requests`\n",
    "\n",
    "Le module `requests` possède sa documentation sur son [propre site](http://docs.python-requests.org/en/master/). Au moment de l'écriture, le module est dans sa version 2.18.4.\n",
    "\n",
    "### 2.B Faire une requête GET:\n",
    "\n",
    "Le module est très simple : il propose une fonction `get` qui prend une URL !"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests\n",
    "\n",
    "# Pour l'exemple nous utilisons l'API de Chronicling America, un projet de numérisation de journaux\n",
    "# Américains\n",
    "req = requests.get(\"https://chroniclingamerica.loc.gov/search/pages/results/?format=json&proxtext=ecole+nationale\")\n",
    "print(req)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Les objets `Response` ont plusieurs propriétés intéressantes : \n",
    "\n",
    "- `.status_code` sous la forme d'un entier qui informe du succès de la requête\n",
    "- `.headers` sous la forme d'un dictionnaire qui comporte l'ensemble des headers\n",
    "- `.encoding` qui comprend la méthode d'encodage\n",
    "- `.text` qui contient le contenu de la réponse\n",
    "- `.json()` qui, si `.headers['content-type']` est `application/json`, parse lui-même le json de la réponse. \n",
    "\n",
    "Voyons un peu leur contenu :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(req.status_code)\n",
    "print(req.headers)\n",
    "print(req.encoding)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Puisque l'on a du json, on peut le traiter comme un dictionnaire ou une liste\n",
    "# Une rapide ouverture de la page m'informe que le nom du journal est disponible à la clé \"\"\n",
    "\n",
    "for resultat in req.json()[\"items\"]:\n",
    "    print(\"\\\"{titre}\\\" a publié un article comprenant 'école nationale' le {jour}/{mois}/{annee}\".format(\n",
    "        titre=resultat[\"title_normal\"], \n",
    "        annee=resultat[\"date\"][:4], \n",
    "        mois=resultat[\"date\"][4:6],\n",
    "        jour=resultat[\"date\"][6:]\n",
    "    ))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "La construction d'URL pouvant poser des problèmes (échappement de caractère par exemple), `requests.get()` accepte un paramètre `params`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "req = requests.get(\"http://cts.dh.uni-leipzig.de/api/cts\", params={\n",
    "    \"urn\": \"urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.pr.1\",\n",
    "    \"request\": \"GetPassage\"\n",
    "})\n",
    "print(\"URL : \" + req.url)\n",
    "if req.status_code == 200:\n",
    "    print(req.text)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "De la même manière, la méthode `.get()` accepte des headers sous la forme d'un dictionnaire :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests\n",
    "\n",
    "# L'adresse suivante permet de demander l'analyse morphologique d'un terme :\n",
    "url = \"http://morph.alpheios.net/api/v1/analysis/word?word=lasciva&lang=lat&engine=whitakerLat\"\n",
    "\n",
    "xml = requests.get(url, headers={\"Accept\": \"text/xml\"})\n",
    "print(xml.text)\n",
    "req_json = requests.get(url, headers={\"Accept\": \"application/json\"})\n",
    "print(req_json.text)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.C Les autres types de requêtes :\n",
    "\n",
    "Le module possède de la même manière une méthode `requests.post()` qui prendra en plus un paramètre `data` tout comme il possède les méthodes :\n",
    "\n",
    "- `.update()`\n",
    "- `.delete()`\n",
    "- `.put()`\n",
    "- `.options()`\n",
    "\n",
    "Toutes ces requêtes prennent les mêmes paramètres que `.get()`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.D Générer une erreur\n",
    "\n",
    "Imaginons que vous avez un code 404. Vous voulez peut-être éviter de faire tourner un script si cela arrive. L'objet `Response` possède une méthode utile en ce cas : le `.raise_for_status()` :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests \n",
    "bad_r = requests.get(\"http://cts.dh.uni-leipzig.de/collections/urn:cts:froLit\")\n",
    "bad_r.raise_for_status()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exercice de compréhension \n",
    "\n",
    "Lisez le code ci-dessous. Il est issu du projet EHRI ( https://portal.ehri-project.eu/api/v1#api-usage-python ). Essayez de comprendre ce qu'il fait, commentez-le de manière à vous en souvenir. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests \n",
    "\n",
    "def scope_content(url):\n",
    "    print(\"Fetching: \" + url)\n",
    "    r = requests.get(url)\n",
    "    data = r.json()\n",
    "    simplified = []\n",
    "\n",
    "    for item in data[\"data\"]:\n",
    "        try:\n",
    "            # fetch the ID and first description...\n",
    "            identifier = item[\"id\"]\n",
    "            desc = item[\"attributes\"][\"descriptions\"][0]\n",
    "            name = desc[\"name\"]\n",
    "            scopecontent = desc[\"scopeAndContent\"]\n",
    "            simplified.append((identifier, scopecontent, name))\n",
    "        except (IndexError, KeyError) as e:\n",
    "            # no description or scope and content found... skipping...\n",
    "            pass\n",
    "\n",
    "    # fetch the next page of data...\n",
    "    if data.get(\"links\") and data[\"links\"].get(\"next\"):\n",
    "        simplified += scope_content(data[\"links\"][\"next\"])\n",
    "    return simplified\n",
    "\n",
    "scope_content(\"https://portal.ehri-project.eu/api/v1/search?type=DocumentaryUnit&q=Potato\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exercice de fin de chapitre\n",
    "\n",
    "1. Ouvrir http://gallica.bnf.fr/iiif/ark:/12148/btv1b84259980/manifest.json\n",
    "2. Comprendre le format de http://gallica.bnf.fr/iiif/ark:/12148/btv1b84259980/manifest.json\n",
    "3. En Python, faire une fonction qui prend un identifiant ark BNF et qui:\n",
    "    1. Affiche l'ensemble des métadonnées sur l'objet décrit en JSON\n",
    "    2. Génère un fichier CSV avec les colonnes `Numéro | Nom de Page | Lien image | Largeur | Longueur` en fonction d'un argument `nom_csv`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def iiif_csv(ark, nom_csv):\n",
    "    colonnes = [\"Numéro\", \"Nom de Page\", \"Lien image\", \"Largeur\", \"Longueur\"]\n",
    "    # Complétez avec la documentation\n",
    "    return None\n",
    "\n",
    "# Testez le code ici\n",
    "iiif_csv(\"ark:/12148/btv1b84259980\", \"pages.csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----\n",
    "\n",
    "#### Ce que l'on a appris\n",
    "\n",
    "Pour finir cette section, voici un récapitulatif des concepts appris. Lisez la liste et posez des questions si certaines choses ne sont pas claires.\n",
    "\n",
    "- la structure d'une requête http et de sa réponse\n",
    "- `requests.get`\n",
    "- `requests.post` et les autres\n",
    "- `Response.json()`\n",
    "- `Response.status_code`\n",
    "- `Response.text`\n",
    "- `Response.headers`\n",
    "- `Response.raise_for_status()`"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}