Tutorial_4_Imports_functions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Bibliothèques, imports, fonctions\n",
    "\n",
    "![image](resources/imports.png)\n",
    "\n",
    "(Récupéré sur [xkcd](www.xkcd.com), le site de _Randall Munroe_. Vous noterez l'emploi 'archaïque' de la fonction print !)\n",
    "\n",
    "### Importer des modules (bibliothèques de fonctions)\n",
    "\n",
    "#### Généralités\n",
    "\n",
    "Python contient une immense liste de _bibliothèques_, qui sont en fait des paquets contenant de nombreuses fonctions utiles. Vous l'aurez remarqué, Python ne permet pas de faire grand-chose par lui-même, et ce _minimalisme_ est un choix délibéré. Dans ce chapitre, nous allons voir comment _importer_ ces bibliothèques (également appelés _modules_) pour utiliser leurs fonctions. Nous allons nous pencher sur un cas bien connu,  \n",
    "\n",
    "Il existe donc des librairies effectuant des tâches assez _élémentaires_\n",
    "\n",
    "* la gestion d'_expressions régulières_ ([re](https://docs.python.org/fr/3/library/re.html))\n",
    "* l'interaction avec l'ordinateur ([os](https://docs.python.org/fr/3/library/os.html))\n",
    "* la recherche de fichiers _via_ des expressions régulières, encore ([glob](https://docs.python.org/3/library/glob.html))\n",
    "* les fonctions mathématiques ([NumPy](https://numpy.org/))\n",
    "* la gestion des fichiers Image simples ([PIL](https://he-arc.github.io/livre-python/pillow/index.html))\n",
    "\n",
    "Mais également des librairies plus costaudes qui ont des fonctionnalités plus avancées !\n",
    "\n",
    "* le traitement d'images et la _machine vision_ ([OpenCV](https://opencv.org/) ou [Scikit-Image](https://scikit-image.org/))\n",
    "* la gestion des fichiers image _bio-formats_ ([PIMS](http://soft-matter.github.io/pims/v0.6.1/))\n",
    "* le traitement de signal, la résolution numérique d'équations ([SciPy](https://scipy.org/))\n",
    "* l'import et export de données dans un format _tableur_ avancé, ([Pandas](https://pandas.pydata.org/))\n",
    "* l'affichage de graphiques ([MatPlotLib](https://matplotlib.org) ou [Bokeh](https://bokeh.org))\n",
    "* l'apprentissage statistique et non supervisé ([TensorFlow](https://www.tensorflow.org/learn?hl=fr) ou [Pytorch](https://pytorch.org/))\n",
    "\n",
    "#### Syntaxe\n",
    "\n",
    "Importer un module `X` est on ne peut plus simple. Si celui-ci est déjà installé dans Python, on peut alors l'invoquer avec la commande `import X`. \n",
    "\n",
    "Supposons que je veuille importer le module `numpy` et que je veuille ensuite utiliser la fonction cosinus `cos()` de NumPy. Pour appeler une fonction existant dans le module `numpy`, on va donc écrire `numpy.fonction()`, et cette syntaxe est similaire à celle des méthodes pour les objets en Python ([cf. Leçon n°2](./Tutorial_2_ListsTuplesDicts.ipynb)). Mais, comme ici `numpy` est une bibliothèque, et non un `str` ou une `liste`, on parlera quand même de fonction. Mon code devrait alors ressembler à :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy\n",
    "numpy.cos(pi/3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Aaaargh ! $\\pi$ n'existe pas non plus en Python, ce qui est assez agaçant ! Mais, soyez rassuré, une fois de plus, NumPy va vous aider, car il possède en plus la constante $\\pi$, qu'on va trouver en écrivant :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "numpy.cos(numpy.pi/3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Fort bien ! Vous aurez remarqué que je n'ai pas eu besoin de ré-importer le module `numpy` : une fois que celui-ci est chargé dans notre _classeur_ (c'est à dire l'ensemble de nos cellules de Python), il l'est pour de bon ! \n",
    "\n",
    "Maintenant, vous vous posez probablement quelques questions : \n",
    "\n",
    "1. Est-on condamné à écrire _tout le temps_ `numpy.truc()` à chaque fois qu'on veut utiliser la fonction `truc()` ?\n",
    "2. Est-ce que je peux simplement importer certaines parties d'un module ?\n",
    "3. Comment est-ce que je sais ce que contient le module `numpy` ?\n",
    "\n",
    "#### Donner un _alias_ à vos paquets avec `as` : \n",
    "\n",
    "Il est tout à fait possible de renommer un module à l'import, afin d'éviter d'avoir des noms à rallonge. Voyez plutôt : "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np # A very classic shorthand for numpy\n",
    "np.cos(np.pi/3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Importer des parties de modules avec `from`\n",
    "\n",
    "Les imports de fonctions peuvent prendre du temps et de la place en mémoire, ce qui ralentira l'exécution de vos programmes. Si vous êtes un fana de l'optimisation de code (_on n'en est pas encore là, normalement !_), vous ne souhaiterez importer que le strict nécessaire. Pour `piocher` des fonctions ou des variables (comme $\\pi$) dans un module `X`, on peut utiliser le mot-clé `from` combiné à un `import`. Par exemple, pour notre cosinus préféré : "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from numpy import cos, pi\n",
    "print(cos(pi/3))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Vous pouvez donc lister après import toutes les fonctions qui vous intéressent à importer. Si vous n'êtes pas très subtil, vous pouvez décider d'importer toutes les fonctions d'un module `X` en utilisant la syntaxe suivante : "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from numpy import *\n",
    "2*(arctan(1/10) + arctan(10))/pi"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Cela peut toutefois poser des problèmes, si, par exemple, deux modules ont les mêmes fonctions. Voyez par exemple : "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from numpy import * # Contains sin(), cos(), pi\n",
    "from math import * # Also contains sin(), cos(), pi\n",
    "\n",
    "cos(pi/2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Dans un tel cas, c'est le dernier import qui va _primer_ sur le premier, mais cela n'est pas toujours vrai, comme nous allons le voir plus tard dans ce tutoriel. \n",
    "\n",
    "On peut enfin combiner tous nos mots-clés ensemble pour encore plus de flexibilité ... mais attention à ne pas rendre votre code trop confus :-) :\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from numpy import cos as bonjour\n",
    "from numpy import pi as madame\n",
    "bonjour(madame/3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Dé-référencement : oublier un module en cours de route\n",
    "\n",
    "Examinons maintenant le code suivant, qui ne devrait _a priori_ pas fonctionner vu qu'on n'a pas effectué d'imports."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(numpy.cos(numpy.pi/3))\n",
    "print(np.cos(np.pi/3))\n",
    "print(cos(pi/3))\n",
    "print(bonjour(madame/3))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "Le résultat de ces lignes de code peuvent vous paraître bizarres, mais rappelez-vous que nous avons déjà écrit plus haut `import numpy` et `import numpy as np`, ce dont notre Python _interactif_ se souvient encore lorsqu'on effectue le troisième import avec `from`. Pour oublier un import, il va falloir redémarrer notre _noyau_ (Kernel) Python en utilisant le bouton suivant de votre interface :\n",
    "\n",
    "![img](./resources/restart_kernel.png)\n",
    "\n",
    "Vous pouvez également demander à Python de dé-référencer votre module en utilisant le mot-clé `del` suivi de votre module `X`. Le code suivant n'a donc aucune chance de fonctionner jusqu'au bout. La première fois que vous l'exécuterez, Python va dé-référencer `numpy` et ne pourra plus appeler la fonction `cos`. Les fois suivantes, il ne reconnaîtra même plus le module `numpy` et sera donc incapable de le dé-référencer :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "del numpy\n",
    "print(numpy.cos(10))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "_Note_ : Le mot-clé Python [`del`](https://www.w3schools.com/python/python_ref_keywords.asp) fonctionne également sur toutes les variables et tous les objets, son usage est donc très très général. \n",
    "\n",
    "#### Connaître les fonctions d'un module\n",
    "\n",
    "Que contient au juste le module numpy ? Il n'est en effet pas évident de savoir quelles sont les fonctions qu'il contient. Vous vous douterez qu'en plus, NumPy en contient beaucoup. Les bons modules possèdent bien souvent de la documentation, que l'on peut trouver de différentes manières. \n",
    "\n",
    "1. Via l'API du site internet du module \n",
    "\n",
    "Bien souvent, vous pouvez aller sur le site de votre module (par exemple [ici](https://numpy.org) pour NumPy) et en cliquant un peu, vous tomberez sur l'API, l'interface de programmation du module (_Application Programming Interface_). Le nom est un peu barbare, mais il représente en gros une liste documentée de toutes les fonctions, classes, objets présents dans le module. [L'API de NumPy](https://numpy.org/doc/stable/reference/index.html), comme bien d'autres, possède une barre de recherche qui vous permettra de savoir si, par exemple, la fonction $W$ de Lambert est présente dans le module.\n",
    "\n",
    "2. Par la documentation du code et les fonctions Python `help` et `dir`\n",
    "\n",
    "Les modules possèdent généralement une documentation détaillée, hormis pour les plus expérimentaux d'entre eux. On peut demander de l'aide à propos d'un paquet de nombreuses manières différentes. Voyons l'exemple avec un autre module, `Pandas`. Avec la fonction native `help` de Python, on peut lui demander par exemple s'il existe une fonction `pandas.bamboo` ou `pandas.concat`, et dans la foulée, savoir comment elle fonctionne. Si la fonction n'existe pas, le code va renvoyer une erreur, mais si la fonction existe, elle va renvoyer la documentation associée. \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas\n",
    "help(pandas.bamboo)\n",
    "dir(pandas)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Contrairement à l'API du site internet d'un module, qui fonctionne comme un moteur de recherche, ici vous devrez déjà avoir une bonne idée du nom de la fonction que vous recherchez pour appeler à l'aide. Si vous n'êtes pas sûr, et que votre connexion internet ne fonctionne pas, vous pourrez toujours essayer l'aide du module lui-même [ `help(pandas)` ] et vous laisser guider, ou utiliser la fonction `dir(pandas)` qui va lister tous les objets (y compris les fonctions) contenus dans le module."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "help(pandas)\n",
    "dir(pandas)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Le fichier d'aide en question est ici _colossal_, donc je ne recommande clairment pas de l'utiliser. En plus de lister les fonctions, la commande `dir`  liste également des _classes_ définies dans le module (vous pouvez voir cela comme des nouveaux types de variables) ainsi que les propriétés par défaut du module, entourés de deux tirets bas '\\_\\_' qui ont des noms assez explicites : `pandas.__name__` va par exemple renvoyer le nom complet du module Pandas.\n",
    "\n",
    "3. Directement sur votre éditeur de code _via IntelliSense®_ \n",
    "\n",
    "Nombre d'entre vous n'êtes probablement pas fanatiques de Microsoft, mais leur éditeur de code [Visual Studio Code](https://code.visualstudio.com/), disponible pour toutes les plateformes, possède de nombreuses fonctionnalités qui vous simplifieront la vie en Python. En particulier, il permet d'afficher dans une fenêtre d'aide contextuelle toutes les fonctions et sous-modules associées à un module, toutes les méthodes associées à un objet, et affiche dans une fenêtre contextuelle la documentation associée (formatée). Par exemple, si je recherche une fonction pour choisir des nombres au harsard avec NumPy, je peux laisser l'éditeur me prendre par la main. Voyez plutôt :\n",
    "\n",
    "![img](./resources/intellisense_import.gif)\n",
    "\n",
    "J'économise donc _beaucoup_ de temps à ne pas ouvrir mon navigateur internet et lire la documentation de fonctionnalités qui ne m'intéressent pas ! Sachez également que ces aides contextuelles fonctionnent pour n'importe quel objet Python, ce qui permet de rapidement savoir, par exemple, quelles sont les méthodes disponibles pour l'objet avec lequel vous travaillez, ou même quels sont les modules que vous pouvez importer dans Python.\n",
    "\n",
    "Pour l'instant, vous ne parcourez pas ces tutoriels Python avec Visual Studio Code, mais cela peut s'arranger si vous êtes motivés pour [installer Python et VSCode sur votre machine](https://code.visualstudio.com/docs/python/python-tutorial) ! (en anglais) \n",
    "\n",
    "##### ICI --> VSCODE\n",
    "\n",
    "_Note_ : Spyder permet également d'afficher de telles fenêtres contextuelles, mais elles ont l'air légèrement moins performantes que celles de Micro$oft. \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "----------------------------------------------\n",
    "\n",
    "### Faites vos propres fonctions !\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "#### Pourquoi faire des fonctions ?\n",
    "\n",
    "Supposons que vous avez régulièrement à exécuter un bout de code qui correspond à une \"tâche\" bien précise. Par exemple, j'aimerais pouvoir rapidement estimer la viscosité d'une suspension à partir de sa concentration en particules $\\phi$, la viscosité du fluide suspendant $\\eta_0$ et une valeur de la fraction d'empilement maximal $\\phi_{\\rm m}$ (correspondant à un coefficient de friction $\\mu$ microscopique entre particules, (cf. [les papiers de Romain Mari _et al_](https://doi.org/10.1122/1.4890747).). Il existe plusieurs modèles à ce sujet, par exemple le modèle d'Einstein (vrai pour faibles $\\phi$) et deux modèles empiriques à plus haut $\\phi$, celui de Maron & Pierce et celui de Krieger & Dougherty :\n",
    "\n",
    "$$\n",
    "\\left \\{ \\begin{array}{rll} \\eta &= \\eta_0 \\left (1 + \\frac{5}{2} \\phi \\right ) & \\text{Einstein} \\\\ \n",
    "                            \\eta &= \\eta_0 \\left (1 - \\frac{\\phi}{\\phi_{\\rm m}} \\right )^{-2} & \\text{Maron-Pierce} \\\\\n",
    "                            \\eta &= \\eta_0 \\left (1 - \\frac{\\phi}{\\phi_{\\rm m}} \\right)^{-2.5 \\phi_{\\rm m}} &\\text{Krieger-Dougherty} \\end{array} \\right .\n",
    "$$\n",
    "\n",
    "Vous vous rendez peut-être compte qu'il sera assez pénible de mettre en place un tel bout de code dans une boucle, et que le résultat sera peu lisible. Une solution est donc de définir une fonction qui va renvoyer $\\eta$ quand on lui envoie les bons paramètres. Commençons assez simplement. Une fonction se définit avec le mot-clé `def`, et la syntaxe suivante qui ressemble à celle des boucles et des instructions conditionnelles. Il faut en outre définir ce que la fonction va renvoyer à l'utilisateur, ce qui s'effectue en fin de fonction avec l'instruction `return`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def my_function(argument_1, argument_2): # A dummy function\n",
    "    result = argument_1 + argument_2 \n",
    "    return result\n",
    "\n",
    "def krieger_dougherty(phi, phi_m, eta_0): # Krieger-Dougherty model\n",
    "    return eta_0*(1-phi/phi_m)**(-2.5*phi_m)\n",
    "\n",
    "krieger_dougherty(0.2,0.64,0.001) # phi = 20 %, phi_max ~ random close packing, eta_0 ~ that of water"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Types de valeurs en entrée\n",
    "\n",
    "Il n'y a pas vraiment de type de variables pré-supposé en entrée. On pourrait essayer de donner en entrée une liste, mais rappelez-vous, les objets `list` ne fonctionnent pas bien avec les opérations de base (c'était le [Tutoriel 2](./Tutorial_2_ListsTuplesDicts.ipynb))). On va plutôt utiliser un tableau NumPy pour calculer plusieurs valeurs de $\\eta$ à la volée. On peut donc écrire :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "phis = np.array([0.01,0.02,0.05,0.1,0.2,0.5])\n",
    "phi_ms = np.array([0.64,0.63,0.61,0.63,0.64,0.58])\n",
    "\n",
    "print(krieger_dougherty(phis, 0.64, 0.001))\n",
    "print(krieger_dougherty(phis, phi_ms, 0.001))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Merveilleux, non ?\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Valeurs par défaut\n",
    "\n",
    "Les fonctions sont très __flexibles__ et permettent de définir des valeurs par défaut pour vos variables. Par exemple, je peux décider que si je ne précise pas $\\phi_{\\rm m}$ ou la viscosité du solvant $\\eta_0$, ils doivent prendre respectivement les valeurs $0.64$ et $1$ (dans ce cas, on obtient la viscosité _relative_ de la suspension). Pour cela, on indique juste `argument = value` dans la ligne où le `def` est présent. On peut toujours 'écraser' ces valeurs lors de l'appel à la fonction :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def krieger_dougherty_mieux(phi, phi_m=0.64, eta_0=1.0):\n",
    "    return eta_0*(1-phi/phi_m)**(-2.5*phi_m)\n",
    "\n",
    "print(krieger_dougherty_mieux(0.3))      # Only one argument _needed_\n",
    "print(krieger_dougherty_mieux(0.3,0.5))  # You can still specify multiple arguments (by default, in the original order)\n",
    "print(krieger_dougherty_mieux(0.3, eta_0=0.02))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Dans le dernier cas, on a appelé la fonction avec un argument 'sans nom' qui va donc correspondre à $\\phi$, alors que nous avons explicitement nommé notre deuxième entrée, qui va donc être 'considérée' correctement comme $\\eta_0$. \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Fonctions dans les fonctions\n",
    "\n",
    "Nous avons défini la fonction `krieger_dougherty`, qui est certes sympathique, mais nous aimerions plutôt une fonction `viscosity` qui est capable de donner $\\eta$ également en fonction d'un modèle. Eh bien, rien de plus simple. Python étant très modulaire, on peut demander à `viscosity` d'appeler lui-même une autre fonction, par exemple de la manière suivante : "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "def krieger_dougherty_case(phi, phi_m=0.64, eta_0=1):\n",
    "    return eta_0*(1-phi/phi_m)**(-2.5*phi_m)\n",
    "\n",
    "def maron_pierce_case(phi, phi_m=0.64, eta_0=1):\n",
    "    return eta_0*(1-phi/phi_m)**(-2)\n",
    "\n",
    "def viscosity(phi, phi_m=0.70, eta_0=5, model='krieger-dougherty'):\n",
    "    if model == 'krieger-dougherty' or model == 'krieger':\n",
    "        return krieger_dougherty_case(phi, phi_m, eta_0)\n",
    "    elif model == 'maron-pierce' or model == 'maron':\n",
    "        return maron_pierce_case(phi, phi_m, eta_0)\n",
    "    else:\n",
    "        print('Unknown model')\n",
    "        return np.nan\n",
    "\n",
    "print(viscosity(0.3))\n",
    "print(viscosity(0.3, model='maron-pierce'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ici, les valeurs par défaut de $\\phi_{\\rm m}$ et de $\\eta_0$ de `viscosity` vont _écraser_ celles par défaut des deux fonctions `maron_pierce` et `krieger_dougherty` potentiellement appelées. \n",
    "\n",
    "__Exercices__ : \n",
    "\n",
    "* Mettez en place la sous-fonction `Einstein` dans la fonction `viscosity`.\n",
    "* Essayez de définir une fonction _à l'intérieur_ de la définition d'une autre fonction. Cela fonctionne-t-il ? Quelle est la différence avec le fait de ne pas imbriquer les fonctions (indice : essayez d'appeler les sous-fonctions directement depuis l'extérieur de la fonction principale)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "#### Portée des variables en Python\n",
    "\n",
    "Dans de nombreux langages de programmation (C++, MATLAB, Fortran), définir une fonction crée un espace _à part_ où seules les variables précisées en entrée et celles déclarées à l'intérieur de la fonction 'existent'*. En d'autres termes, si je déclare une fonction, celle-ci n'est pas capable d'appeler une variable qui existe 'en dehors' de la fonction. Essayons d'examiner le problème en Python :\n",
    "\n",
    "<sub>(*Les petits malins savent qu'il est parfois possible de s'en sortir en déclarant des variables globales en utilisant le mot-clé `global` dans la déclaration de leur variable.)<sub>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def maron_pierce_new(phi, eta_0=1):\n",
    "    visco = eta_0*(1-phi/phi_m)**(-2)\n",
    "    return visco \n",
    "\n",
    "phi_m = 0.64\n",
    "print(maron_pierce_new(0.30))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Python s'est 'débrouillé' : faute d'avoir trouvé un $\\phi_m$ à l'intérieur de la fonction, il est allé chercher un $\\phi_m$ en dehors, même si celui-ci a été défini _après_ la fonction `maron_pierce_new`. C'est une propriété très puissante de Python, mais également une source de confusion, notamment quand des variables ayant le même nom existent à la fois en dehors et en dedans de la fonction. __Dans ce cas, la valeur déclarée dans la fonction est prioritaire sur celle existant en dehors de la fonction__. Voyez par exemple:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "greeting = 'Hey '\n",
    "\n",
    "def say_hi(name):\n",
    "    greeting = 'Hello '\n",
    "    exclamation = ' !'\n",
    "    return greeting + name + exclamation\n",
    "\n",
    "print(say_hi('Bob'))\n",
    "print(greeting)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Les variables définies à l'intérieur de la fonction restent toutefois bien locales. Essayez par exemple d'appeler `Exclamation` en dehors de la fonction `say_hi`: cela ne fonctionne pas. Ouf, sinon ce serait _vraiment_ le bazar."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---------------------------------------------------------\n",
    "\n",
    "### Devenez votre propre module\n",
    "\n",
    "#### Intérêt\n",
    "\n",
    "Il est possible qu'avec le temps, vous ayez besoin de définir de nombreuses fonctions qui effectuent des opérations assez standards (par exemple, un 'nettoyage' de données brutes, un calcul de fonction de corrélation de paires $g(r)$ pour des milieux divisés avec des particules, ou une détection de contour d'un objet). Cela crée à nouveau des codes très confus avec beaucoup de fonctions déclarées avant de voir des lignes de code. Si les utilisateurs du code n'ont pas besoin de 'toucher' à ces fonctions (c'est à dire de modifier leur fonctionnement en éditant leur code), vous pouvez très bien décider de créer vous même un fichier Python (`.py`) annexe qui contient toutes ces fonctions standards. L'image animée ci-dessous vous montre comment faire cela dans votre environnement actuel.\n",
    "\n",
    "![img](./resources/save_external_file.gif)\n",
    "\n",
    "#### Syntaxe\n",
    "\n",
    "Nous avons créé un fichier Python 'simple' (qui se termine en `.py`) nommé `external_functions` et qui ne contient que des fonctions. L'exécuter sous Python ne ferait rien _a priori_, mais nous pouvons importer ses fonctions très simplement en utilisant la commande `import` ! __Reproduisez ces opérations dans votre environnement, puis essayez d'exécuter le code suivant__ "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import external_functions as fun\n",
    "\n",
    "print(fun.my_external_function('toto'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Python a réussi à trouver votre nouveau module extérieur et à utiliser les fonctions qui y sont incluses ! \n",
    "\n",
    "#### Lister les propriétés d'un module \n",
    "\n",
    "Vous pouvez, si vous êtes un peu tête-en-l'air, demander d'afficher toutes les fonctions associées au module `external_functions` en utilisant la fonction Python native [`dir()`](https://docs.python.org/fr/3.10/library/functions.html#dir) :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import external_functions as fun\n",
    "\n",
    "dir(fun)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ici, nous voyons qu'il existe de nombreuses 'fonctions' entourées par deux tirets bas (_underscores_), par exemple \\_\\_name\\_\\_, mais après cette liste d'étranges objets, on retrouve bien notre `my_external_function`. Les objets entourés de '\\_\\_' sont en fait des propriétés _spéciales_ que Python crée par défaut pour tous les modules. Par exemple, `__name__` contient le nom du module en question (sous forme de chaîne de caractères)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fun.__name__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Vous pouvez enfin appeler des modules dans des sous-dossiers du fichier actuel. Si votre fichier `external_functions` est dans un sous-dossier `my_folder` de votre dossier actuel (c'est à dire le dossier dans lequel se trouve le fichier que vous êtes en train de lire). __Créez un sous-dossier et donnez-lui un nom (j'ai choisi `my_folder`), déplacez le fichier `external_functions.py` dans ce sous-dossier, et essayez d'importer votre module en tapant le code suivant__ :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import my_folder.external_functions as fun"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Appeler un module dans un sous-dossier revient à écrire son chemin d'accès _relatif_ par rapport au fichier que vous êtes en train de lire actuellement ; la seule différence est que vous devrez utiliser des points `.` au lieu des `\\` ou `/` pour séparer les dossiers. Et pour 'remonter' d'un dossier dans votre chemin d'accès relatif, vous pouvez utiliser deux points `..` ! Dans notre cas précis, cela n'est pas très utile car nous sommes déjà dans le dossier 'racine' de notre environnement, mais sachez que la commande existe. \n",
    "\n",
    "__Exercice__ : Créez un module nommé `extra_functions`. Créez-y une fonction `my_function`. Faites en sorte que cette fonction renvoie quelque chose (par exemple `'Roger'`) et importez-la en utilisant la commande suivante dans votre code principal :\n",
    "\n",
    "```\n",
    "from extra_functions import my_function \n",
    "```\n",
    "\n",
    "Ensuite, créez une fonction `my_function` _dans votre code principal_ et faites en sorte que celle-ci renvoie _autre chose_ (par exemple, `'Jean-Mi'`). Enfin, appelez votre fonction `my_function` et examinez laquelle des deux fonctions _homonymes_ est réellement appelée. Que pensez-vous du résultat ? L'avons-nous déjà rencontré précédemment ou avons-nous déjà rencontré quelque chose de similaire précédemment ?"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.9.7"
  },
  "vscode": {
   "interpreter": {
    "hash": "cb9c252e610b593a3421828f92740a33c32c552b9658c846af1824aa6c7c0cc9"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}