Modules et packages Python : créer, importer, publier

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.

Ce que vous allez apprendre

• Créer un module : un simple fichier .py contenant des fonctions ou des classes
• Importer un module et utiliser ses fonctions dans un autre script
• Distinguer module et package et organiser vos modules avec __init__.py
• Contrôler les imports d'un package avec __all__
• Empaqueter un projet avec pyproject.toml et python -m build
• Publier sur PyPI avec twine et un jeton API

Qu'est-ce qu'un Module Python ?

Un module Python est un fichier contenant du code Python qui peut définir des fonctions, des classes et des variables. Il permet de regrouper du code liés à une fonctionnalité spécifique, facilitant ainsi la réutilisation et la maintenance du code. Par exemple, si vous avez plusieurs fonctions liées aux calculs mathématiques, vous pouvez les regrouper dans un module appelé math_utils.py.

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.

Comment créer un Module Python

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 :

math_utils.py

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 :

main.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.

stats_utils.py

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 :

__init__.py

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

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

main.py

# 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 :

__init__.py

__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 :

math_utils.py

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 de configuration.

pyproject.toml est le standard moderne

Historiquement, on décrivait un package avec setup.py (montré ci-dessous, toujours fonctionnel). Le standard actuel est le fichier pyproject.toml (PEP 621), construit avec python -m build (pip install build) ou uv build. L'invocation directe python setup.py … est dépréciée. Pour un nouveau projet, préférez pyproject.toml.

Exemple de Structure :

• Répertoiremon_module/

  • Répertoiremon_module/

    • __init__.py
    • math_utils.py
  • setup.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 :

1. Un compte sur pypi.org, créez un compte si vous n'en avez pas déjà un.
2. 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.

1. 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 :

   twine upload --repository-url https://test.pypi.org/legacy/ dist/*

2. Une fois que vous êtes prêt à publier sur le vrai PyPI, utilisez la commande suivante :

   twine upload dist/*

3. Authentifiez-vous avec un jeton API. PyPI n'accepte plus le mot de passe : créez un token dans vos paramètres de compte, puis utilisez __token__ comme nom d'utilisateur et le token (préfixé pypi-) comme mot de passe.

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.

À retenir

• Un module est un simple fichier .py contenant des fonctions, classes ou variables, importable avec import.
• Un package est un dossier contenant des modules et un fichier __init__.py (qui peut être vide).
• from mon_package import module importe un module précis ; __all__ contrôle ce que import * expose.
• Documentez chaque module et fonction avec des docstrings.
• Empaqueter un projet moderne se fait avec pyproject.toml et python -m build (ou uv build), pas python setup.py.
• Publier sur PyPI passe par twine et un jeton API ; testez d'abord sur TestPyPI.

FAQ : questions fréquentes

Les réponses courtes ci-dessous couvrent les questions les plus recherchées sur les modules et packages Python. Chaque exemple est autonome et testé sur Python 3.12.

C'est quoi un module en Python ?

Un module est un simple fichier Python (.py) contenant des fonctions, des classes ou des variables. Il permet de regrouper du code lié à une fonctionnalité et de le réutiliser dans d'autres scripts via l'instruction import.

Quelle différence entre un module et un package en Python ?

Un module est un fichier .py unique. Un package est un dossier qui regroupe plusieurs modules, avec un fichier __init__.py signalant à Python que le dossier est un package. En résumé : le module est un fichier, le package est un dossier de modules.

Comment créer un module en Python ?

Créez un fichier avec l'extension .py et écrivez-y vos fonctions ou classes : c'est déjà un module. Placez-le dans le même dossier que votre script, puis importez-le par son nom de fichier sans l'extension, par exemple import math_utils.

Comment importer un module en Python ?

Utilisez import module pour tout le module (accès via module.fonction), ou from module import fonction pour importer un élément précis. Vous pouvez aussi renommer avec import module as alias. Depuis un package, faites from mon_package import module.

À quoi sert le fichier __init__.py en Python ?

__init__.py signale à Python qu'un dossier doit être traité comme un package. Il peut être vide, ou contenir du code d'initialisation et une liste __all__ définissant les modules exposés par from package import *. Sans lui, le dossier reste un simple répertoire.

Comment créer un package Python installable avec pip ?

Décrivez le projet dans un fichier pyproject.toml (standard moderne, PEP 621), construisez les archives avec python -m build (paquet build) ou uv build, puis publiez sur PyPI avec twine et un jeton API. L'ancien python setup.py est déprécié.

Prochaines étapes

uv : gérer projets et packages Créer, verrouiller et construire un package moderne avec pyproject.toml.

Fonctions Python Écrire les fonctions que vous regrouperez dans vos modules.

POO en Python Organiser vos classes dans des modules réutilisables.

Environnements virtuels Isoler les dépendances de vos projets et packages.

×

📖 Voir la documentation →