python:bases:module [WEBGE Wikis]

Cette page est en lecture seule. Vous pouvez afficher le texte source, mais ne pourrez pas le modifier. Contactez votre administrateur si vous pensez qu'il s'agit d'une erreur.
[[python:bases:accueilmodule|{{ :iconemaison.jpg?nolink&25|Sommaire Les modules et packages}}]]

===== Python - Modules et packages - Généralités =====

[Mise à jour le :2/8/2021]

  * **Sources** 
    * **Documentation** sur Python.org : <html><a href="https://docs.python.org/fr/3.6/reference/index.html" target="_blank">référence du langage</a>, <a href="https://docs.python.org/fr/3/tutorial/modules.html" target="_blank">modules</a>, <a href="https://docs.python.org/fr/3/tutorial/modules.html#packages" target="_blank">packages</a>, <a href="https://docs.python.org/fr/3.5/library/functions.html" target="_blank">fonctions natives</a></html> (built-in)

  * **Mots-clés** : module, importation, package.

<callout type="warning" icon="true">Les mots ci-dessous sont dits "réservés". Ils ne peuvent pas être utilisés comme nom de variable. Les mots __soulignés__ sont une nouveauté de Python 3. Les mots en **gras** sont utilisés dans cette page.</callout>

|  and        |  continue   |  finally     |  is            |  raise     |
|  **as**         |  def        |  for         |  lambda        |  return    |
|  assert     |  del        |  **from**    |  __None__      |  __True__  |
|  __async__  |  elif       |  global      |  __nonlocal__  |  try       |
|  __await__  |  else       |  if          |  not           |  while     |
|  break      |  except     |  **import**  |  or            |  with      |
|  class      |  __False__  |  in          |  pass          |  yield     |

  * <html><a href="https://docs.python.org/fr/3.5/library/functions.html" target="_blank">Fonctions natives</a></html>** (built-in)**((Fonctions toujours disponibles.)) utilisées dans les exemples : **dir**(), **help**().


----

==== 1. Les modules ====

<callout type="primary" icon="true">Un module est une **liste de fonctions et de variables** contenues dans un **fichier**. Pour travailler avec les fonctionnalités du module, il suffit de l'**importer**.</callout>

=== 1.1 Utilisation ====

**1.1.1 Méthode 1 : import**

<callout type="warning" icon="true">L'importation d'un module se fait à l'aide du mot-clé **import**.</callout>

//Exemples // : importation des modules **math** et **random**
<code python *.py>
import math # avec cette déclaration, il faut préfixer les méthodes avec le nom du module (ici math) 
a= math.sqrt(16) # la fonction utilisée est préfixée par le nom du module
print(a) # renvoie 4.0 dans la console
</code>

<code python *.py>
import random
print(random.randint(1,10)) # exemple de résultat : 3
</code>

**1.1.2 Méthode 2 : from ... import**

<callout type="tip" icon="true">On peut éviter de préfixer les fonctions avec le nom du module ou limiter le nombre d'éléments importés en utilisant **//from ... import//** à condition de ne pas importer des modules possédant des méthodes ayant le même nom.</callout>

// Exemple 1 // 
<code python *.py>
from math import * # on importe le module math, toutes les méthodes et variables sont accessibles 
                   # sans se référer à math 
a = sqrt(16) 
print(a) # renvoie 4.0 dans la console
</code>

//Exemple 2 //
<code python>
from math import fabs, e, pi # seules les fonctions valeur absolue, e et pi sont importés

from random import * # on importe la bibliothèque complète
print(randint(1,10)) # exemple de résultat : 1

from datetime import datetime # On importe une seule fonction : datetime
datetime.now() # exemple de résultat : datetime.datetime(2019, 1, 3, 20, 6, 18, 490635)
</code>

<callout type="tip" icon="true">**dir**(//nom_module//) affiche la liste des fonctions. \\ **help("**//nom_module//**")** donne une description de ces fonctions</callout>

//Exemple//
{{ :python:tstidle2.png?nolink |}}

**1.1.3 Espace de noms**

Lorsqu'on écrit //import math//, cela crée un **espace de noms** dénommé //math//, contenant les variables et les fonctions du module //math//. Lorsqu'on écrit //math.sqrt(25)//, on précise à l'interpréteur que l'on souhaite exécuter la fonction //sqrt// située dans l'espace de nom //math//. Il est ainsi possible d'utiliser une autre fonction sqrt située dans un autre module ou dans créer une dans l'espace de nom principal.

<callout type="tip" icon="true">Il est possible de modifier l'intitulé d'un espace de nom avec **as**.</callout>

//Exemple//
<code python>
import math as calcul
a=calcul.sqrt(25) 
print(a) # renvoie 5.0 dans la console
</code>

**1.1.4 Quelques modules**
    * **Math** contient les fonctions mathématiques de base : sqrt (racine carrée), cos, sin, exp, etc. ainsi que quelques constantes comme Pi ou e.
    * <html><a href="https://matplotlib.org/index.html" target="_blank">Matplotlib</a></html> permet de tracer des graphes
    * <html><a href="https://pypi.org/project/numpy/" target="_blank">Numpy</a></html> permet de manipuler des matrices ou tableaux multidimensionnels ainsi que des fonctions mathématiques opérant sur ces tableaux.
    * <html><a href="https://pandas.pydata.org/" target="_blank">Pandas </a></html> est une bibliothèque écrite pour le langage de programmation Python permettant la manipulation et l'analyse des données. Elle propose en particulier des structures de données et des opérations de manipulation de tableaux numériques et de séries temporelles. <html><a href="https://fr.wikipedia.org/wiki/Pandas" target="_blank">Wikipédia</a></html>
    * <html><a href="https://pypi.org/project/Pillow/" target="_blank">Pillow</a></html> contient des outils pour afficher des images numériques, appliquer des filtres, retoucher, enregistrer etc.
    * **Time** permet de gérer le temps dans l'exécution d'un programme, en particulier la fonction //sleep(n)// stoppe l'exécution pendant n secondes.
    * [[python:bases:turtle|Turtle]] commande une tortue pour tracer des segments.
    * **Random** génère des valeurs aléatoires.
    * <html><a href="https://scikit-learn.org/stable/" target="_blank">Scikit-learn</a></html>  est une bibliothèque destinée à l'apprentissage automatique. <html><a href="https://fr.wikipedia.org/wiki/Scikit-learn" target="_blank">Wikipédia</a></html> 
    * <html><a href="https://wxpython.org/" target="_blank">WxPython</a></html> est une implémentation libre en Python de l'interface de programmation wxWidgets. Cette bibliothèque Python est utilisée pour la création d'interfaces graphiques, et est l'alternative de Tkinter la plus utilisée. <html><a href="https://fr.wikipedia.org/wiki/WxPython" target="_blank">Wikipédia</a></html>.
   <html><a href="" target="_blank"></a></html> 


<callout icon="fa fa-hand-stop-o" color="red" title="ATTENTION">Si l'importation du module ne fonctionne pas, c'est certainement qu'il n'est pas installé. L'installation d'un module passe par un gestionnaire de paquets comme **[[python:outils:pip|pip]]** ou **[[python:outils:anaconda|conda]]**. \\ Voir le site sur lequel il se trouve pour la procédure.

Un module installé sous **VSCode** dans un terminal PowerShell avec la commande :
<code powershell *.ps>python -m  pip install nomModule ou 
pip install nomModule</code> est disponible **après son redémarrage**.</callout>


===1.2 Création ===
  * **Source** : les modules sur <html><a href="https://docs.python.org/fr/3/tutorial/modules.html" target="_blank">docs.python.org</a></html>

//Exemple//

  * **Création** du fichier //fibo.py// contenant les fonctions ci-dessous.

<code python fibo.py>
# Fibonacci numbers module

def fib(n):    # write Fibonacci series up to n
    a, b = 0, 1
    while a < n:
        print(a, end=' ')
        a, b = b, a+b
    print()

def fib2(n):   # return Fibonacci series up to n
    result = []
    a, b = 0, 1
    while a < n:
        result.append(a)
        a, b = b, a+b
    return result
</code>

  * **Première forme** de l'appel de la fonction //fib// à partir du fichier //test1.py//

<code python test1.py>
import fibo # Importation de la totalité des fonctions

fibo.fib(50) # résultat : 0 1 1 2 3 5 8 13 21 34
</code>

  * **Deuxième forme** de l'appel de la fonction //fib// à partir du fichier //test2.py//

<code python test2.py>
from fibo import fib # importation de la seule fonction fib

fib(50) # résultat : 0 1 1 2 3 5 8 13 21 34
</code>

==== 2. Les packages ====
  * **Source** : les paquets sur <html><a href="https://docs.python.org/fr/3/tutorial/modules.html#packages" target="_blank">docs.python.org</a></html>

Lorsqu'on dispose d'un grand nombre de modules, il peut être intéressant de les organiser dans des répertoires. Un répertoire rassemblant des **modules** est appelé package. 

<callout type="primary" icon="true">Un **package** sert à regrouper plusieurs modules. En pratique les packages sont des **répertoires**. Le nom du package est le nom du répertoire.</callout>

{{ :python:bases:exmodule.png?nolink|}}
//Exemple// : le fichier module1.py contenant les fonctions carre et cube est placé dans le répertoire **package1**.
<code python module1.py>
def carre(a)
    return(a*a)

def cube(a)
    return(a*a*a)
</code>


Les fonctions carre et cube peuvent être utilisées en important package1.module1

<code python test.py>
from package1.module1 import carre

x=5
print(f"Le carré de {x} vaut {carre(x)}") # Le carré de 5 vaut 25
</code> 

----

==== 3. Fichier .py, script ou module? ====
En Python, lorsqu’on crée un fichier qui rassemble des instructions, on appelle ce fichier un **script** et on le sauvegarde avec une extension **.py**, par exemple //test.py//.

Si le fichier **.py** contient uniquement des définitions de fonction on l'appelle un **module**.

<callout type="warning" icon="true">Un même **fichier .py** peut jouer le rôle de **script** ou de **module** suivant son utilisation.</callout>

  * **La variable global <nowiki>__name__</nowiki>**
<callout type="primary" icon="true">A l’intérieur d’un module, le nom du module (en tant que chaîne de caractères) peut être obtenu grâce à la **variable globale <nowiki>__name__</nowiki>**.</callout>

Quand on utilise un fichier en tant que script, la variable globale <nowiki>__name__</nowiki> prend pour valeur '**<nowiki>__main__</nowiki>**'. Ceci permet d’avoir dans le fichier **un bloc d’instructions** qui sera exécuté uniquement lorsque le fichier est lancé en tant que script.

  * **Exemple 1 - Exécution du module //module1// en tant que script**

<code python module1.py>

def carre(a)
    return(a*a)

def cube(a)
    return(a*a*a)

if __name__ == "__main__":                    # Si module1 est appelé en tant que script :
    x = 3                                     # ces deux lignes sont exécutées
    print(f"Le carré de {x} vaut {carre(x)}") # Résultat : Le carré de 3 vaut 9
</code>

  * **Exemple 2 - Exécution du module //module1// en tant que module**

<code python test.py>
# Le module est appelé dans le fichier test.py
from package1.module1 import carre

x=5                                       # Le code sous if __name__ == "__main__" n'est pas exécuté
print(f"Le carré de {x} vaut {carre(x)}") # Résultat : Le carré de 5 vaut 25
</code> 

{{ :arduino:vscodeico.png?nolink&30|}}
> **Télécharger** le répertoire du projet **VSCode** <html><a href="https://webge.fr/doc/wikis/code/Python/PY_WIKI_PACKAGE_EXEMPLE.zip">ici</a></html>



==== Résumé ====
  * On écrit les programmes Python dans des fichiers portant l'extension **.py**
  * On peut créer des fichiers contenant des **modules** pour séparer le code.
  * On peut créer des répertoires contenant des **packages** pour hiérarchiser un programme.


{{ :python:bases:realpython.png?nolink|}}
==== Pour aller plus loin ... ====
  * <html><a href="https://realpython.com/python-import/" target="_blank">Python import: Advanced Techniques and Tips</a></html>
  * <html><a href="https://realpython.com/pypi-publish-python-package/" target="_blank">How to Publish an Open-Source Python Package to PyPI</a></html>
  * <html><a href="https://realpython.com/python-packages/" target="_blank">Python Packages: Five Real Python Favorites</a></html>