Mentorat docstring sur les paquets, modules et imports

Qu’est-ce qu’un module et un paquet en Python ?

Qu’est-ce qu’un module et un paquet en Python ?

 Modules :

  • Un fichier Python contenant des définitions et des instructions (fonctions, classes, variables).
  • N’importe quel fichier .py est un module (ex. : math, os).

Qu’est-ce qu’un module et un paquet en Python ?

Paquets

  • Un répertoire contenant plusieurs modules et un fichier spécial __init__.py pour être considéré comme un paquet.

  • Permet une organisation hiérarchique du code.

Qu’est-ce qu’un module et un paquet en Python ?

MonProjet/
│
├── mon_module.py  # Un module
├── mon_paquet/    # Un paquet
│   ├── __init__.py
│   ├── module_1.py
│   └── module_2.py

Le fichier __init__.py: Porte d’entrée des paquets

Rôle

  • Un répertoire contenant plusieurs modules et un fichier spécial __init__.py pour être considéré comme un paquet.

  • Permet une organisation hiérarchique du code.

Le fichier __init__.py: Porte d’entrée des paquets

Usage

  • Peut importer des sous-modules ou des fonctions communes au paquet.

  • Gère les imports explicites : lorsque vous importez un paquet, Python exécute d’abord le contenu de __init__.py.

Le fichier __init__.py: Porte d’entrée des paquets

# __init__.py

from .module_1 import fonction_a
from . import module2

Le fichier __main__.py - Point d’entrée des applications

Rôle

  • Permet d’exécuter un paquet en tant que script.

  • Si vous lancez un paquet via la ligne de commande avec python -m mon_paquet, Python cherchera un fichier __main__.py dans le paquet.

Le fichier __main__.py - Point d’entrée des applications

Fonction

  • Sert de script principal pour démarrer une application.

Le fichier __main__.py - Point d’entrée des applications

$ python -m mon_paquet

Importation de modules en Python

import module
from module import nom
from module import * (à éviter 90 % du temps)

# Exemples
import math
from math import sqrt
from math import *  # Non recommandé

Syntaxes communes des imports en Python

Python recherche les modules dans des répertoires comme le répertoire courant, les paquets installés dans le venv, ou les chemins spécifiés dans PYTHONPATH.

Importation de modules en Python

import module
from module import nom
from module import * (à éviter 90 % du temps)

# Exemples
import math
from math import sqrt
from math import *  # Non recommandé

Syntaxes communes des imports en Python

Bonnes pratiques pour organiser vos projets Python

projet/
│
├── README.md
├── project/
│   ├── __init__.py
│   ├── __main__.py
│   ├── paquet1/
│   │   ├── __init__.py
│   │   └── module11.py
│   ├── paquet2/
│   │   ├── __init__.py
│   │   └── module22.py

Bonnes pratiques pour organiser vos projets Python

$ python projet

$ python projet/__main__.py

$ python project/paquet1/module11.py

Bonnes pratiques pour organiser vos projets Python

$ python projet

$ python projet/__main__.py

$ python project/paquet1/module11.py

Bonnes pratiques pour organiser vos projets Python

$ python projet

$ python projet/__main__.py

$ python project/paquet1/module11.py

Bonnes pratiques pour organiser vos projets Python

$ python -m projet

$ python -m projet.paquet1.module11

Bonnes pratiques pour organiser vos projets Python

$ python -m projet

$ python -m projet.paquet1.module11

Différences entre imports relatifs et absolus

sound/                          Premier niveau
      __init__.py               Initialise le paquet son
      formats/                  Sous-paquet pour les conversions
              __init__.py
              wavread.py
              wavwrite.py
              aiffread.py
              aiffwrite.py
              auread.py
              auwrite.py
              ...
      effects/                  Sous-paquet pour les effets
              __init__.py
              echo.py
              surround.py
              reverse.py
              ...
      filters/                  Sous-paquet pour les filtres
              __init__.py
              equalizer.py
              vocoder.py
              karaoke.py
              ...

Différences entre imports relatifs et absolus

import sound.effects.echo
sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)

from sound.effects import echo
echo.echofilter(input, output, delay=0.7, atten=4)

from sound.effects.echo import echofilter
echofilter(input, output, delay=0.7, atten=4)

Imports absolu

Différences entre imports relatifs et absolus

from . import echo
from .. import formats
from ..filters import equalizer

Imports relatifs

Différences entre imports relatifs et absolus

Privilégier les imports absolus si vous êtes encore hésitant

Privilégier les imports absolus si vous êtes encore hésitant.

Privilégier les imports relatifs pour la structure internes des paquets (comme en Django) lorsque vous être à l'aise.

Q & R

Importer * depuis un paquet

__all__ = [
    "echo",      # fait référence à 'echo.py'
    "surround",  # fait référence à 'surround.py'
    "reverse",   # !!! fait référence à la fonction 'reverse' !!!
]

def reverse(msg: str):  # <-- masque le module 'reverse.py' 
    return msg[::-1]

Importer * depuis un paquet

__all__ = [
    "echo",      # refers to the 'echo.py' file
    "surround",  # refers to the 'surround.py' file
    "reverse",   # !!! refers to the 'reverse' function now !!!
]

def reverse(msg: str):  # <-- this name shadows the 'reverse.py' submodule
    return msg[::-1]

Importer * depuis un paquet

__all__ = [
    "echo",      # fait référence à 'echo.py'
    "surround",  # fait référence à 'surround.py'
    "reverse",   # !!! fait référence à la fonction 'reverse' !!!
]

# masque le module 'reverse.py' 
def reverse(msg: str):  
    return msg[::-1]