Créer des Modules et des Packages Python

Mise à jour : 21/10/2024

Les modules Python permettent de structurer votre code, le rendre réutilisable et maintenable. Un module est simplement un fichier Python contenant des fonctions, des variables, des classes, etc., que vous pouvez importer et utiliser dans d’autres scripts ou projets Python. Ce guide détaillé vous expliquera comment créer vos propres modules, comment les organiser, et comment les utiliser dans différents projets.

Pourquoi Utiliser des Modules ?

Avant de plonger dans les détails techniques, voyons pourquoi les modules sont utiles :

Réutilisation : Un module peut être utilisé dans plusieurs projets, évitant de réécrire du code.
Organisation : Ils aident à organiser le code en le découpant en petits morceaux logiques.
Maintenance : Une bonne modularisation facilite la mise à jour ou la correction d’un programme sans affecter l’ensemble du projet.

Création d’un Module de Base

Un module Python est simplement un fichier Python avec l’extension .py. Par exemple, si vous avez un fichier appelé math_utils.py, il devient un module que vous pouvez importer et utiliser dans d’autres scripts Python.

Exemple :

Créez un fichier nommé math_utils.py et ajoutez-y quelques fonctions simples :

def addition(a, b):
    return a + b

def soustraction(a, b):
    return a - b

def multiplication(a, b):
    return a * b

def division(a, b):
    if b == 0:
        raise ValueError("Division par zéro non permise")
    return a / b

Ce fichier contient quatre fonctions : addition, soustraction, multiplication, et division. Maintenant, ce module peut être importé dans un autre fichier Python.

Importation et Utilisation d’un Module

Une fois que votre module est créé, vous pouvez l’utiliser dans un autre script Python en utilisant l’instruction import.

Exemple :

Créez un nouveau fichier nommé main.py pour utiliser les fonctions définies dans le module math_utils.py :

# Importer le module math_utils
import math_utils

# Utiliser les fonctions du module
resultat1 = math_utils.addition(10, 5)
resultat2 = math_utils.division(10, 2)

print(f"Résultat de l'addition : {resultat1}")
print(f"Résultat de la division : {resultat2}")

Sortie attendue :

Résultat de l'addition : 15
Résultat de la division : 5.0

Dans cet exemple, le fichier main.py importe le module math_utils et utilise ses fonctions.

Organisation des Modules avec les Packages

Un package en Python est un moyen d’organiser plusieurs modules dans des sous-répertoires pour créer une structure plus complexe. Un package est simplement un répertoire contenant un ou plusieurs modules et un fichier spécial __init__.py. Ce fichier peut être vide, mais il indique à Python que ce répertoire doit être traité comme un package.

Exemple :

Supposons que vous vouliez organiser vos modules pour un projet de calcul mathématique complexe. Vous pouvez structurer votre package ainsi :

Répertoiremon_package/
- __init__.py
- math_utils.py
- stats_utils.py

__init__.py : Ce fichier indique que mon_package est un package Python.
math_utils.py : Contient des fonctions de base de calcul (comme nous l’avons vu précédemment).
stats_utils.py : Contiendra des fonctions pour des calculs statistiques.

def moyenne(liste):
    return sum(liste) / len(liste)

def mediane(liste):
    liste_triee = sorted(liste)
    n = len(liste_triee)
    if n % 2 == 1:
        return liste_triee[n // 2]
    else:
        return (liste_triee[n // 2 - 1] + liste_triee[n // 2]) / 2

Vous pouvez le laisser vide, ou y ajouter du code pour personnaliser le comportement de votre package :

print("Le package 'mon_package' a été chargé")

Maintenant, pour utiliser ce package, vous pouvez simplement faire :

# Importer le package
from mon_package import math_utils, stats_utils

# Utiliser les fonctions du package
resultat_add = math_utils.addition(10, 20)
resultat_moy = stats_utils.moyenne([1, 2, 3, 4, 5])

print(f"Résultat de l'addition : {resultat_add}")
print(f"Moyenne des nombres : {resultat_moy}")

Sortie attendue :

Le package 'mon_package' a été chargé
Résultat de l'addition : 30
Moyenne des nombres : 3.0

Gestion des Importations dans les Packages

Lorsque vous avez un grand nombre de modules dans un package, vous pouvez structurer les importations pour qu’elles soient plus simples à utiliser.

Dans votre fichier __init__.py, vous pouvez définir un tableau __all__ pour spécifier les modules ou sous-modules que vous souhaitez rendre disponibles lorsque le package est importé avec from mon_package import *.

Exemple :

__all__ = ["math_utils", "stats_utils"]

Cela permet de spécifier quels modules sont accessibles à partir du package. Sans cela, les utilisateurs devront importer chaque module explicitement.

Documentation des Modules

Il est indispensable de documenter correctement vos modules et fonctions pour qu’ils soient faciles à comprendre par d’autres développeurs (ou vous-même dans le futur).

Utilisez des docstrings pour décrire chaque module, classe et fonction.

Exemple :

def addition(a, b):
    """
    Ajoute deux nombres.

    :param a: Le premier nombre.
    :param b: Le second nombre.
    :return: La somme de a et b.
    """
    return a + b

Création de Modules Installables

Si vous souhaitez distribuer votre module pour qu’il soit installé via pip, vous devez créer une structure spécifique et un fichier setup.py.

Exemple de Structure :

Répertoiremon_module/
- Répertoiremon_module/
  - __init__.py
  - math_utils.py
- setup.py

from setuptools import setup, find_packages

setup(
    name='mon_module',
    version='1.0',
    packages=find_packages(),
    description='Un package de mathématiques simples',
    author='Stéphane Robert',
    author_email='stephane@example.com',
    install_requires=[],
)

Une fois que cela est configuré, vous pouvez créer une distribution et l’installer avec pip.

Pour compléter votre guide, voici une section détaillée sur la publication des packages sur PyPI (Python Package Index), qui vous permettra de partager vos modules avec la communauté Python. Vous pouvez facilement publier vos packages sur PyPI afin que d’autres développeurs puissent les installer avec pip.

Publication des Packages sur PyPI

Une fois que vous avez créé un package Python, vous pouvez le partager en le publiant sur PyPI (Python Package Index). Cela permet à d’autres développeurs de l’installer en utilisant simplement pip.

Prérequis

Avant de publier sur PyPI, assurez-vous d’avoir :

Un compte sur pypi.org ↗ — créez un compte si vous n’en avez pas déjà un.
Python et setuptools installés sur votre machine :

pip install setuptools wheel twine

Structure du Package

Assurez-vous que votre package a la structure suivante :

Répertoiremon_module/
- Répertoiremon_module/
  - __init__.py
  - math_utils.py
- setup.py
- README.md

Voici un exemple de fichier setup.py que vous pouvez adapter selon votre projet :

from setuptools import setup, find_packages

setup(
    name='mon_module',
    version='1.0.0',
    packages=find_packages(),
    description='Un package de mathématiques simples',
    long_description=open('README.md').read(),
    long_description_content_type='text/markdown',
    author='Stéphane Robert',
    author_email='stephane@example.com',
    url='https://github.com/stephane-robert/mon_module',
    classifiers=[
        'Programming Language :: Python :: 3',
        'License :: OSI Approved :: MIT License',
        'Operating System :: OS Independent',
    ],
    python_requires='>=3.6',
    install_requires=[],
)

Création de l’Archive

Avant de publier le package, vous devez créer une archive du package. Pour cela, vous pouvez utiliser setuptools et wheel pour générer les fichiers nécessaires.

Exécutez la commande suivante à la racine de votre projet, où se trouve le fichier setup.py :

python setup.py sdist bdist_wheel

Cela créera un répertoire dist/ contenant les fichiers de distribution .tar.gz et .whl (fichiers wheel).

Publication avec Twine

Ensuite, vous pouvez utiliser l’outil twine pour publier votre package sur PyPI.

Vérifiez d’abord que vos fichiers sont corrects en les testant sur TestPyPI, une instance de PyPI qui permet de tester le processus de publication :
Terminal window
```
twine upload --repository-url https://test.pypi.org/legacy/ dist/*
```
Une fois que vous êtes prêt à publier sur le vrai PyPI, utilisez la commande suivante :
Terminal window
```
twine upload dist/*
```
Entrez votre nom d’utilisateur et mot de passe PyPI lorsque cela vous est demandé.

Installation du Package

Après la publication, votre package sera disponible sur PyPI, et vous (ou tout autre utilisateur) pourrez l’installer en utilisant :

pip install mon_module

Mise à Jour de Votre Package

Si vous devez publier une nouvelle version de votre package, mettez simplement à jour la version dans setup.py (par exemple, de version='1.0.0' à version='1.1.0'), recréez les fichiers de distribution, et répétez la commande twine upload :

python setup.py sdist bdist_wheel
twine upload dist/*

Bonnes Pratiques

Voici quelques bonnes pratiques à suivre lors de la création de vos modules :

Nommez vos modules clairement : Choisissez des noms explicites pour vos modules et fonctions afin qu’ils soient faciles à comprendre.
Utilisez des docstrings : Toujours documenter vos fonctions et modules.
Évitez les importations circulaires : Les modules qui s’importent mutuellement peuvent provoquer des erreurs.
Modularisez votre code : Ne mettez pas trop de fonctions ou de classes dans un même module, divisez-les logiquement.
Testez votre code : Utilisez des tests unitaires pour vous assurer que chaque module fonctionne correctement de manière isolée.

Pour la Publication sur Pypi

Choisissez un nom unique pour votre package sur PyPI pour éviter les conflits avec d’autres packages existants.
Documentez bien votre projet : Ajoutez un fichier README.md complet pour que les utilisateurs comprennent comment utiliser votre package.
Utilisez des versions cohérentes : Suivez les conventions de versionnement sémantique (SemVer) pour indiquer clairement les mises à jour majeures et mineures de votre package.
Testez toujours sur TestPyPI avant de publier sur le vrai PyPI pour éviter les erreurs.

Conclusion

Créer des modules et des packages Python vous permet de structurer votre code de manière réutilisable et maintenable. Que ce soit pour vos propres projets ou pour distribuer vos modules à d’autres développeurs, comprendre les bases de la création de modules est essentiel pour tout développeur Python. N’hésitez pas à explorer davantage les packages, la documentation et les bonnes pratiques pour améliorer votre maîtrise des modules Python.

Bonne création de modules !