Initial commit

documentation/05-code-structures.md

@@ -0,0 +1,123 @@
+---
+title: Réutiliser du code
+author: Steve Kossouho
+---
+
+# Réutiliser du code
+
+----
+
+En Python, on peut écrire des choses simples avec un seul script. Mais
+souvent, et même pour des choses simples, on peut se retrouver à écrire du code, organisé de façon un peu plus complexe, ou même du code qui réutilise des fonctionnalités en dehors de votre script.
+
+----
+
+## Jargon : [Modules]{.naming} et [packages]{.naming}
+
+Jusque là, tout ce que nous avons écrit, c'est des [modules]{.naming}. Ce sont des fichiers .py (vides ou non, ils peuvent contenir du code).
+
+Il existe aussi les [packages]{.naming}. Ce sont des répertoires, pouvant contenir d'autres modules, et qui sont utilisables comme des modules (peuvent contenir du code). Pour pouvoir associer du code à ces répertoires et les considérer comme des packages, le langage Python impose que le code associé repose dans un fichier nommé `__init__.py` dans le répertoire. L'intérêt principal d'un package est d'y ranger d'autres packages et modules, pour organiser son code en arborescence cohérente.
+
+----
+
+## Typographie des modules et packages
+
+Les modules et packages ont la même typographie que les variables (car Python les traite comme des variables de type `module`) :
+
+- Tout en minuscules (ex. `mypackage`)
+- <span style="color:red;">Sans espace ni tiret</span> (ex. `my_package`)
+- etc.
+
+
+----
+
+## Bibliothèque standard de Python
+
+Python est à la fois un langage et un exécutable interprétant des scripts écrits dans le langage. 
+L'interpréteur est toujours livré avec ce qu'on appelle la bibliothèque standard. 
+Il s'agit d'une immense bibliothèque de fonctionnalités, que l'on peut réutiliser dans nos programmes.
+
+La bibliothèque propose des outils pour manipuler du texte, du réseau, des bases de données, des fonctions mathématiques etc.
+
+[Liste des modules et packages de la bibliothèque standard](https://docs.python.org/3/library/)
+
+----
+
+Parmi les très nombreux modules de la bibliothèque standard, assez peu vous serviront régulièrement. En voici une liste :
+
+- `random` : génération de nombres aléatoires
+- `math` : fonctions mathématiques et trigonométriques
+- `statistics` : fonctions statistiques, comme l'écart type.
+- `pathlib` : outils pour gérer les chemins de fichier
+- `datetime` : types pour gérer les dates
+
+D'autres peuvent servir ponctuellement, comme `csv` ou `sqlite3` pour nos exemples à venir.
+
+----
+
+Comment accéder à ces nombreuses fonctionnalités ?
+Par défaut, elles ne sont pas toutes accessibles dans votre code, excepté celles documentées dans les sections "built-in", et pour pouvoir les utiliser, il faut en faire la demande explicite dans vos modules via la notion d'`import` :
+
+Variantes :
+
+```{.python .numberLines}
+# Les imports sont écrits au sommet d'un module
+import math  # vous avez maintenant une variable nommée `math`
+from os import path  # vous avez une variable `path`
+import datetime as dt  # datetime est utilisable en tant que dt uniquement
+
+from math import sin, cos  # importer plusieurs fonctions de la même bibliothèque
+
+math.cos(math.pi / 2.0)  # possible grâce à import math
+cos(0)  # possible grâce à from math import cos
+path.join(…)
+```
+
+Chaque script qui utilise directement un _symbole_ doit toujours l'importer.
+
+**Note** : Pour importer le contenu d'un module, l'interpréteur Python doit toujours exécuter le contenu dudit module, afin d'en connaître le contenu. Attention donc à la présence de `print` dans ledit module.
+
+----
+
+Note : Normalement, importer un package donne accès uniquement aux variables directement définies dans celui-ci, mais pas
+aux sous-modules ou packages qui s'y trouvent. Si vous créez un package `package` contenant un sous-module `module1` :
+
+```{.python .numberLines}
+import package
+
+print(package.module1)  # ceci provoque une erreur
+```
+
+Cela ne fonctionne pas car Python ne charge pas directement les modules et packages présents à l'intérieur du package.
+Pour y avoir accès, il faut que le package lui-même importe les éléments qui seront directement accessibles depuis celui-ci :
+
+```{.python .numberLines}
+from . import module1  # ajoute une variable module1 dans le package
+```
+`package/__init__.py`
+
+----
+
+## Faire un petit peu de calcul avec la bibliothèque standard
+
+Avec l'outil que sont les imports, on peut avoir accès à de nombreuses fonctions de calcul. 
+Par exemple, on pourrait générer un nombre aléatoire et calculer un cosinus :
+
+```{.python .numberLines}
+import random
+import math
+
+random_number = random.randint(0, 100)  # nombre entre 0 et 100 inclus
+cosinus_result = math.cos(random_number)  # cosinus du nombre aléatoire
+```
+
+----
+
+## Bonus : Installer des paquets externes ([PyPI](https://pypi.org))
+
+Avec PyCharm, on va installer simplement quelques paquets externes et utiliser leurs fonctionnalités :
+
+1. `requests` : Faire des requêtes HTTP plus simplement
+2. `unidecode` : Translittération et désaccentuation
+3. `attrs` : Accélérer l'écriture de classes
+