Chapitre 8.1 - Du script a l'application - Modules et Packages.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Chapitre 8.1 - Du script à l'application - Modules et Packages\n",
    "==="
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notre application et nos compétences ont sérieusement grossi : nous sommes désormais capables de traiter du JSON, du CSV, de récupérer des informations depuis le web, mais aussi de créer notre propre application web, bien qu'elle reste simple pour le moment.\n",
    "\n",
    "Cette application web contient désormais 39 lignes de Python pour 2 pages et un type de ressource SQL. Vous vous rendrez vite compte que la manipulation de fichiers comme celui-ci rend les choses complexes. De fait, on préfère en général diviser les fichiers pythons comme nous divisons les templates : en les incluant ou en faisant appel à eux quand nous en avons besoin.\n",
    "\n",
    "## Les modules et packages\n",
    "\n",
    "Ce découpage en python s'appelle la modularisation : il s'agit de créer des modules qui à terme forment des packages (groupe de modules) et ainsi pouvoir se retrouver dans des applications un peu plus large que 39 lignes.\n",
    "\n",
    "Nous avons déjà utilisé des modules. Ainsi quand l'on tapait\n",
    "\n",
    "```python\n",
    "from flask import Flask\n",
    "```\n",
    "\n",
    "Nous importions depuis le module principal du package `flask` la classe `Flask` qui nous permettait de créer notre application. Un module est en fait un fichier python. Ainsi, si je crée un fichier `modeles.py` pour y ranger l'ensemble de mes modèles de données SQL (et pouvoir m'y retrouver facilement), je pourrais à terme faire `from modeles import Place` !\n",
    "\n",
    "Les modules peuvent comprendre tout ce que python peut faire, à savoir : \n",
    "\n",
    "- des variables\n",
    "- des fonctions\n",
    "- des classes\n",
    "\n",
    "### Créer un package, c'est simple !\n",
    "\n",
    "La création de package est en fait extrêmement simple : \n",
    "\n",
    "0. On crée un fichier `run.py` qui nous permettra d'utiliser ce qui est dans gazetteer\n",
    "1. On crée un dossier : `gazetteer/` par exemple.\n",
    "2. On ajoute dans ce dossier un fichier `__init__.py`\n",
    "3. On écrit dans ce fichier `__init__.py`.\n",
    "4. On écrit dans ce fichier `ma_variable = 0`\n",
    "\n",
    "Les fichiers `__init__.py` sont nécessaire pour que ce dossier soit compris comme package. Le résultat serait donc\n",
    "\n",
    "```\n",
    "gazetteer/\n",
    "   |- __init__.py\n",
    "run.py\n",
    "```\n",
    "\n",
    "Avec `__init__.py` qui comprend le code suivant :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Raccourci pour afficher le contenu de l'exemple\n",
    "%pycat cours-packages/exemple-01/gazetteer/__init__.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Cela permettra à `run.py` d'utiliser la variable en faisant :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Raccourci pour afficher le contenu de l'exemple\n",
    "%pycat cours-packages/exemple-01/run.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Et le résultat de son appel sera :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%run cours-packages/exemple-01/run.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Pour lancer l'exemple\n",
    "\n",
    "On ouvrira un terminal, s'assurera d'être dans un environnement virtuel et on tapera depuis le dossier source\n",
    "\n",
    "```sh\n",
    "cd cours-pages/exemple-01\n",
    "python run.py\n",
    "```\n",
    "\n",
    "#### Résumé d'un module simple avec dossier\n",
    "\n",
    "- Un module simple avec dossier comprenant un `__init__.py` est appelé ou importé en utilisant le nom du dossier. \n",
    "- On peut y stocker des variables, classes et fonctions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Un package, des modules"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Il est possible pour un package de comporter plusieurs modules, ainsi pour notre Gazetteer il est possible de diviser par exemple les modèles des routes. Pour le moment, créons cet ensemble :\n",
    "\n",
    "0. On crée un fichier `run.py` qui nous permettra d'utiliser ce qui est dans gazetteer\n",
    "1. On crée un dossier : `gazetteer/` par exemple.\n",
    "2. On ajoute dans ce dossier un fichier `__init__.py`\n",
    "3. On crée un fichier `application.py`\n",
    "4. On écrit dans ce fichier `mon_module = \"application\"`\n",
    "5. On crée un fichier `modeles.py`\n",
    "6. On écrit dans ce fichier `mon_module = \"modeles\"`\n",
    "\n",
    "```\n",
    "gazetteer/\n",
    "   |- __init__.py\n",
    "   |- application.py\n",
    "   |- modeles.py\n",
    "run.py\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Raccourci pour afficher le contenu de l'exemple\n",
    "%pycat cours-packages/exemple-02/gazetteer/application.py"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Raccourci pour afficher le contenu de l'exemple\n",
    "%pycat cours-packages/exemple-02/gazetteer/modeles.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Cela permettra à `run.py` d'utiliser la variable en important les modules du packages. On importe des modules et sous-modules en rétablissant le chemin via des `.` :\n",
    "\n",
    "```python\n",
    "from gazetteer.application import mon_module\n",
    "```\n",
    "\n",
    "Ainsi, on écrira dans notre `run` :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Raccourci pour afficher le contenu de l'exemple\n",
    "%pycat cours-packages/exemple-02/run.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Et le résultat de son appel sera :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Cette commande permet de lancer le script directement depuis ce module\n",
    "! cd cours-packages/exemple-02 && python run.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Pour lancer l'exemple en terminal\n",
    "\n",
    "On ouvrira un terminal, s'assurera d'être dans un environnement virtuel et on tapera depuis le dossier source\n",
    "\n",
    "```sh\n",
    "cd cours-pages/exemple-02\n",
    "python run.py\n",
    "```\n",
    "\n",
    "#### Problème ?\n",
    "\n",
    "Nous rencontrons un premier problème : `mon_module` étant importé depuis deux modules (`gazetter.application` et `gazetteer.modeles`), les deux rentrent en conflit et la dernière prend le dessus. Nous avons plusieurs solutions à ce problème. \n",
    "\n",
    "1. `from gazetteer import application` et `print(application.mon_module)` qui permet de garder le nom du sous-module\n",
    "2. `import gazetteer.application` et `print(gazetteer.application.mon_module)` : long à écrire, mais impossible d'avoir des conflits et compréhensible\n",
    "3. `from gazetteer.application import mon_module as autre_nom` : on renomme, on perd l'information d'origine, mais on reste sur un nom court.\n",
    "\n",
    "Pour continuer l'exemple, on écrit un fichier `run2.py` qui reprend cette syntaxe :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Raccourci pour afficher le contenu de l'exemple\n",
    "%pycat cours-packages/exemple-02/run2.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Et le résultat de son appel sera :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Cette commande permet de lancer le script directement depuis ce module\n",
    "! cd cours-packages/exemple-02 && python run2.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Pour lancer l'exemple en terminal\n",
    "\n",
    "On ouvrira un terminal, s'assurera d'être dans un environnement virtuel et on tapera depuis le dossier source\n",
    "\n",
    "```sh\n",
    "cd cours-packages/exemple-02\n",
    "python run2.py\n",
    "```\n",
    "\n",
    "#### Résumé d'un package avec plusieurs modules\n",
    "\n",
    "- Un package se construit avec un dossier comprenant un `__init__.py`\n",
    "- Les fichiers qui le constituent sont importables comme modules (`from package import module`)\n",
    "- Les imports de ressources dans des modules peuvent être construits de trois manière :\n",
    "    - `import package.module`\n",
    "        - Appelée via `package.module.ressource`\n",
    "    - `from package import module`\n",
    "        - Appelée via `module.ressource`\n",
    "    - `from package.module import resource`\n",
    "        - Appelée via `ressource`\n",
    "- En cas de conflit, on peut:\n",
    "    - changer de méthode d'import\n",
    "    - renommer la ressource importée via `import ___ as ___` ou `from ___ import ___ as ____`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### De module à module : l'import relatif\n",
    "\n",
    "Nous avons pour l'instant fait des imports uniquement depuis l'extérieur du package vers ce package. Il est cependant possible de faire ces imports de manière relative et il est d'ailleurs conseillé de le faire dans le cadre d'une application web.\n",
    "\n",
    "Ces imports fonctionnent alors exactement comme les imports précédents, mais en utilisant la syntaxe des chemins relatifs `..` et `.` où :\n",
    "\n",
    "- `.` représente le dossier courant\n",
    "- `..` représente le dossier parent.\n",
    "- `...` représente le dossier grand-parent\n",
    "- etc.\n",
    "\n",
    "Ainsi, dans le cadre de nos modèles par exemple, il serait souhaitable de pouvoir diviser nos ressources entre les données utilisateurs et les données scientifiques pour se retrouver plus facilement dans les fichiers. Cela donnerait : \n",
    "\n",
    "```\n",
    "gazetteer/\n",
    "   |- __init__.py\n",
    "   |- application.py\n",
    "   |- modeles/\n",
    "       |- __init__.py\n",
    "       |- donnees.py\n",
    "       |- utilisateurs.py\n",
    "run.py\n",
    "```\n",
    "\n",
    "Si l'on a besoin d'une information d'application depuis `modeles.donnees`, on importera l'information via :\n",
    "\n",
    "```python\n",
    "from ..application import nom_dapplication\n",
    "```\n",
    "\n",
    "Si au contraire, on recherche une information liée à l'utilisateur, on écrira \n",
    "\n",
    "```python\n",
    "from .utilisateurs import mon_utilisateur\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Raccourci pour afficher le contenu de l'exemple\n",
    "%pycat cours-packages/exemple-03/gazetteer/application.py"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Raccourci pour afficher le contenu de l'exemple\n",
    "%pycat cours-packages/exemple-03/gazetteer/modeles/utilisateurs.py"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Raccourci pour afficher le contenu de l'exemple\n",
    "%pycat cours-packages/exemple-03/gazetteer/modeles/donnees.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Et on importe simplement la fonction dans `gazetteer.modeles.donnees` depuis `run.py` :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Raccourci pour afficher le contenu de l'exemple\n",
    "%pycat cours-packages/exemple-03/run.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Et le résultat de son appel sera :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Cette commande permet de lancer le script directement depuis ce module\n",
    "! cd cours-packages/exemple-03 && python run.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Pour lancer l'exemple en terminal\n",
    "\n",
    "On ouvrira un terminal, s'assurera d'être dans un environnement virtuel et on tapera depuis le dossier source\n",
    "\n",
    "```sh\n",
    "cd cours-packages/exemple-03\n",
    "python run.py\n",
    "```\n",
    "\n",
    "#### Résumé d'un package avec plusieurs modules\n",
    "\n",
    "- Un package peut avoir des sous-modules\n",
    "- Les imports relatifs se font à l'aide des `.` :\n",
    "    - `.` représente le dossier courant\n",
    "    - `..` représente le dossier parent.\n",
    "    - `...` représente le dossier grand-parent.\n",
    "    - etc.\n",
    "- Depuis l'extérieur du package, on utilise l'import absolu"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Notre application en packages\n",
    "\n",
    "Vous imaginez bien que si l'on peut diviser, il est recommandable de le faire. Et pour le faire, il vaut mieux pouvoir découper au mieux ce que vous pouvez faire. On recommande en général de découper :\n",
    "\n",
    "1. Les modèles de données (et si possible les différents modèles de données : modèles scientifiques et modèles utilisateurs)\n",
    "2. Les routes\n",
    "3. La création de l'application\n",
    "\n",
    "Regardez un peu le dossier `cours-packages/exemple-04`\n",
    "\n",
    "\n",
    "#### Pour lancer l'exemple en terminal\n",
    "\n",
    "On ouvrira un terminal, s'assurera d'être dans un environnement virtuel et on tapera depuis le dossier source\n",
    "\n",
    "```sh\n",
    "cd cours-packages/exemple-04\n",
    "python run.py\n",
    "```\n",
    "\n",
    "#### Un petit bug ?\n",
    "\n",
    "On nous annonce un problème avec les templates. Pour résoudre le problème, on spécifie le dossier ! En effet, `Flask()` prend deux paramètres nommés `templates` et `static` ! :\n",
    "\n",
    "```python\n",
    "app = Flask(\"Nom\", template_folder=\"templates\", static_folder=\"static\") # Valeur par défaut ici\n",
    "```\n",
    "\n",
    "Mais en python, les dossiers relatifs sont pris depuis le fichier qui est exécuté. Or, on exécute `run.py` et non `app.py`. Il faudrait donc écrire `./gazetteer/templates/` et `./gazetteer/static`. Mais si on change encore !\n",
    "\n",
    "La technique vise à obtenir, via python, le chemin actuel de l'application. Il suffit pour cela d'exécuter le code suivant :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%pycat cours-flask/exemple12/path.py\n",
    "%run cours-flask/exemple12/path.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Découpons le code !\n",
    "\n",
    "\n",
    "- `import os` : on importe un package `os` permettant de faire des opérations liées au système\n",
    "- `os.path.dirname()` : on récupère le nom de dossier du résultat de \n",
    "    - `os.path.abspath(__file__)` qui récupère le chemin absolu du dossier du fichier qui comprend ce code\n",
    "        - **Attention:** `__file__` n'existe pas dans Jupyter Notebook\n",
    "- `os.path.join()` permet de réaliser la jointure du chaîne avec les caractères de chemin de l'OS exécutant:\n",
    "    - Sur Windows, il choisira `\\`\n",
    "    - Sur Linux et Mac, il choisira `/`\n",
    "    \n",
    "    \n",
    "#### Pour lancer l'exemple en terminal\n",
    "\n",
    "On ouvrira un terminal, s'assurera d'être dans un environnement virtuel et on tapera depuis le dossier source\n",
    "\n",
    "```sh\n",
    "cd cours-flask/exemple12\n",
    "python run.py\n",
    "```\n",
    "\n",
    "#### Attention !\n",
    "\n",
    "On fera attention à importer les routes en fin de création d'application, sinon on aura une belle boucle d'import : \n",
    "\n",
    "1. `gazetteer.app` importe `gazetteer.routes` ligne 3\n",
    "2. `gazetteer.routes` importe `gazetteer.app` ligne 2\n",
    "3. `gazetteer.app` importe `gazetteer.routes` ligne 3\n",
    "4. `gazetteer.routes` importe `gazetteer.app` ligne 2\n",
    "5. `gazetteer.app` importe `gazetteer.routes` ligne 3\n",
    "6. `gazetteer.routes` importe `gazetteer.app` ligne 2\n",
    "7. *etc.*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Schéma récapitulatif\n",
    "\n",
    "## Attention\n",
    "\n",
    "Il n'est pas possible de remonter relativement jusqu'au premier module !\n",
    "\n",
    "## Exemple\n",
    "\n",
    "Vous pouvez trouver ce schéma dans cours-packages/exemple-05. Rentrez dans ce dossier puis tapez `python app`.\n",
    "\n",
    "![Python Modules](images/PythonModules.png)"
   ]
  }
 ],
 "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": 1
}