Contactez-nous

Structure d'un projet Python (setup.py, requirements.txt)

Découvrez les bonnes pratiques pour structurer un projet Python. Apprenez à organiser vos modules et packages, à gérer les dépendances avec 'requirements.txt', et à préparer la distribution de votre code avec 'setup.py' (ou des alternatives modernes comme

Pourquoi une structure de projet standardisée ?

Lorsque vous développez un projet Python (une bibliothèque, une application, un script, etc.), il est important d'adopter une structure de projet claire et standardisée.

Une bonne structure de projet permet de :

  • Organiser votre code : Regrouper les modules et les packages de manière logique.
  • Faciliter la maintenance : Rendre le code plus facile à comprendre, à modifier et à étendre.
  • Faciliter la réutilisation : Permettre à d'autres développeurs (ou à vous-même) de réutiliser facilement votre code dans d'autres projets.
  • Gérer les dépendances : Spécifier les bibliothèques externes dont votre projet dépend.
  • Faciliter la distribution : Permettre à d'autres utilisateurs d'installer et d'utiliser votre code facilement.
  • Faciliter les tests.
  • Faciliter la collaboration : Si vous travaillez en équipe, une structure standardisée facilite la collaboration et la compréhension du code par tous les membres de l'équipe.

Il existe plusieurs conventions et outils en Python pour structurer un projet, gérer les dépendances, et préparer la distribution du code.

Structure de répertoire typique

Voici une structure de répertoire typique pour un projet Python (il peut y avoir des variations en fonction de la nature et de la complexité du projet) :

mon_projet/
    README.md           # Fichier décrivant le projet
    LICENSE             # Fichier contenant la licence du projet
    setup.py            # (Optionnel) Script pour construire et distribuer le projet
    requirements.txt    # (Optionnel) Liste des dépendances du projet
    pyproject.toml      # (Optionnel, de plus en plus utilisé) Fichier de configuration du projet
    mon_package/        # Le code source du package principal
        __init__.py
        module1.py
        module2.py
        sous_package/
            __init__.py
            module3.py
    tests/              # (Optionnel) Tests unitaires
        __init__.py
        test_module1.py
        test_module2.py
    docs/               # (Optionnel) Documentation
    examples/           # (Optionnel) Exemples d'utilisation
  • `README.md` : Un fichier texte (généralement au format Markdown) qui décrit le projet, son objectif, comment l'installer, comment l'utiliser, etc.
  • `LICENSE` : Un fichier texte qui contient la licence du projet (par exemple, MIT, GPL, Apache, etc.). Choisir une licence est important si vous voulez partager votre code.
  • `setup.py` : Un script Python (utilisant la bibliothèque `setuptools`) qui décrit le projet et ses dépendances, et qui permet de construire, d'installer et de distribuer le projet. C'est la méthode "traditionnelle" pour packager un projet Python, mais elle est de moins en moins utilisée, au profit de `pyproject.toml`.
  • `requirements.txt` : Un fichier texte qui liste les dépendances externes du projet (les bibliothèques tierces dont votre projet a besoin). Ce fichier est utilisé par `pip` pour installer les dépendances.
  • `pyproject.toml`: Fichier de configuration, qui peut contenir beaucoup d'informations sur le projet (dont les dépendances). Ce fichier tend à remplacer les `setup.py` et `requirements.txt`.
  • `mon_package/` : Un répertoire qui contient le code source de votre projet. Le nom de ce répertoire est généralement le nom de votre package Python. Ce répertoire contient les modules et sous-packages de votre projet.
  • `tests/` : Un répertoire qui contient les tests unitaires de votre projet (optionnel, mais fortement recommandé).
  • `docs/` : Un répertoire qui contient la documentation de votre projet (optionnel).
  • `examples/` : Un répertoire qui contient des exemples d'utilisation de votre code (optionnel).

requirements.txt : gérer les dépendances

Le fichier `requirements.txt` est un moyen simple de lister les dépendances externes de votre projet (les bibliothèques Python que votre projet utilise).

Chaque ligne du fichier `requirements.txt` spécifie une dépendance, généralement sous la forme `nom_du_package==version`. Par exemple :

requests==2.28.2
beautifulsoup4==4.12.2
numpy==1.24.3

Vous pouvez installer toutes les dépendances listées dans `requirements.txt` en utilisant la commande `pip` :

pip install -r requirements.txt

Cela garantit que tous les développeurs travaillant sur le projet (ou les utilisateurs qui installent votre projet) utilisent les mêmes versions des bibliothèques, ce qui évite les problèmes de compatibilité.

Il est recommandé de "geler" les versions de vos dépendances (spécifier des versions exactes) pour garantir la reproductibilité de votre environnement de développement.

Vous pouvez générer un fichier `requirements.txt` à partir de votre environnement actuel en utilisant la commande `pip freeze` :

pip freeze > requirements.txt

Cependant, `pip freeze` listera *toutes* les bibliothèques installées dans votre environnement, y compris celles qui ne sont pas des dépendances directes de votre projet. Il est souvent préférable de gérer le fichier `requirements.txt` manuellement, ou d'utiliser un outil de gestion de dépendances plus avancé (comme `pipenv` ou `poetry`, voir plus loin).

setup.py : décrire et distribuer votre projet (méthode classique, de moins en moins utilisée)

Le fichier `setup.py` est un script Python qui utilise la bibliothèque `setuptools` pour décrire votre projet et ses métadonnées (nom, version, auteur, description, dépendances, etc.).

Il permet de :

  • Construire des distributions de votre projet (des archives qui peuvent être installées avec `pip`).
  • Installer votre projet localement (en mode "développement").
  • Définir des scripts exécutables.
  • Et d'autres tâches liées à la distribution et à l'installation de votre projet.

Exemple de `setup.py` simple :

from setuptools import setup, find_packages

setup(
    name='mon_package',
    version='0.1.0',
    author='Votre Nom',
    author_email='votre.email@example.com',
    description='Une description de votre package',
    long_description=open('README.md').read(),
    long_description_content_type='text/markdown',
    url='https://github.com/votre_utilisateur/mon_package',
    packages=find_packages(),  # Trouve automatiquement tous les packages dans le répertoire courant
    install_requires=[
        'requests',
        'beautifulsoup4',
    ],
    classifiers=[
        'Development Status :: 3 - Alpha',
        'Intended Audience :: Developers',
        'License :: OSI Approved :: MIT License',
        'Programming Language :: Python :: 3',
        'Programming Language :: Python :: 3.7',
        'Programming Language :: Python :: 3.8',
        'Programming Language :: Python :: 3.9',
        'Programming Language :: Python :: 3.10',
        'Programming Language :: Python :: 3.11',
    ],
)

Ce fichier contient des informations sur le projet, comme son nom, sa version, son auteur, une description, l'URL du projet, la liste des dépendances, et une liste de classificateurs (qui permettent de catégoriser le projet sur PyPI).

Pour construire une distribution de votre projet, vous pouvez utiliser la commande :

python setup.py sdist bdist_wheel

Cela créera une archive source (`.tar.gz`) et une archive Wheel (`.whl`) dans un sous-répertoire `dist/`. Ces archives peuvent ensuite être installées avec `pip`.

Cependant, l'utilisation directe de `setup.py` est de moins en moins recommandée. Les projets modernes utilisent de plus en plus `pyproject.toml` (voir section suivante).

pyproject.toml : le futur de la configuration de projet (PEP 518, PEP 621)

Le fichier `pyproject.toml` est un fichier de configuration au format TOML qui est en train de devenir le standard pour configurer les projets Python. Il a été introduit par PEP 518 et standardisé par PEP 621.

`pyproject.toml` permet de spécifier :

  • Les outils de build à utiliser pour construire le projet (par exemple, `setuptools`, `flit`, `poetry`, `hatch`, etc.).
  • Les métadonnées du projet (nom, version, auteur, description, dépendances, etc.).
  • La configuration d'autres outils (comme `pytest`, `flake8`, `black`, etc.).

L'avantage de `pyproject.toml` est qu'il permet d'utiliser des outils de build modernes et plus flexibles que `setuptools`, et qu'il centralise la configuration de nombreux outils dans un seul fichier.

Exemple de `pyproject.toml` :

# pyproject.toml
[build-system]
requires = ["setuptools>=42", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "mon_package"
version = "0.1.0"
authors = [
    {name = "Votre Nom", email = "votre.email@example.com"},
]
description = "Une description de votre package"
readme = "README.md"
dependencies = [
    "requests",
    "beautifulsoup4",
]

[project.urls]  # Optional
Homepage = "https://github.com/votre_utilisateur/mon_package"

[tool.pytest.ini_options] #Exemple: Configuration de pytest
addopts = "-v"

Dans cet exemple :

  • La section `[build-system]` indique à `pip` quels outils utiliser pour construire le projet (ici, `setuptools` et `wheel`).
  • La section `[project]` contient les métadonnées du projet (similaire à ce que vous mettriez dans `setup.py`).
  • La section `[tool.pytest.ini_options]` montre un exemple de configuration pour un outil externe, ici `pytest`.

Pour construire une distribution de votre projet avec `pyproject.toml`, vous pouvez utiliser la commande :

python -m build

Cela nécessite que le module `build` soit installé (`pip install build`).

L'utilisation de `pyproject.toml` est de plus en plus recommandée pour les nouveaux projets Python.

Outils de gestion de projet et de dépendances : pipenv, poetry

Au-delà de `pip` et `setuptools`/`pyproject.toml`, il existe des outils plus avancés pour gérer les environnements virtuels, les dépendances, et le cycle de vie des projets Python.

Deux outils populaires sont :

  • `pipenv` : Combine `pip` et `virtualenv` pour simplifier la gestion des dépendances et des environnements virtuels. Il utilise un fichier `Pipfile` et un fichier `Pipfile.lock` pour gérer les dépendances.
  • `poetry` : Un outil plus récent qui gère les dépendances, les environnements virtuels, le packaging et la publication de projets Python. Il utilise un fichier `pyproject.toml` pour gérer les dépendances et la configuration du projet.

Ces outils offrent une expérience de développement plus intégrée et plus moderne que l'utilisation directe de `pip`, `venv`, et `setuptools`/`pyproject.toml`.

Ils permettent de :

  • Créer et gérer des environnements virtuels facilement.
  • Installer, mettre à jour et supprimer des dépendances de manière fiable.
  • Gérer les versions des dépendances de manière précise (avec des fichiers de verrouillage, "lock files").
  • Construire et publier des packages.

Si vous développez des projets Python de manière régulière, il est recommandé de vous familiariser avec l'un de ces outils.