> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Comment créer votre fichier pyproject.toml

> Guide complet du fichier pyproject.toml en Python : apprenez à le créer, lister les dépendances, figer les versions et préparer votre projet pour la production.

## Fichier pyproject.toml pour Python

Le fichier `pyproject.toml` est une manière moderne de spécifier dans un seul fichier l'ensemble des prérequis du système de build et des dépendances de votre projet. Ce guide montre comment créer, configurer et utiliser `pyproject.toml` pour garantir la cohérence entre les environnements de développement et de production.

## Qu'est-ce qu'un fichier pyproject.toml ?

Un fichier `pyproject.toml` liste les dépendances, le système de build et d'autres métadonnées de votre projet Python. Cela permet :

* À vous et à votre équipe de maintenir des environnements identiques
* Aux nouveaux collaborateurs de reproduire l'environnement à l'identique
* De configurer séparément les dépendances de développement et de production

***

<Steps>
  <Step title="Créer le fichier pyproject.toml">
    Commencez par créer un fichier nommé `pyproject.toml` à la racine de votre projet.
  </Step>

  <Step title="Définir les détails de votre projet">
    Dans le fichier `pyproject.toml`, commencez par définir les métadonnées de votre projet. Nous allons définir le nom du projet, la version, la description et d'autres informations pertinentes.\
    Le nom du projet doit être composé de lettres ASCII, de chiffres, de traits de soulignement « \_ », de traits d'union « - » et de points « . ». Il ne doit pas commencer ni se terminer par un trait de soulignement, un trait d'union ou un point. Par exemple :

    ```toml pyproject.toml theme={null}
    [project]
    name = "my-python-project"
    description = "A sample Python project using pyproject.toml"
    version = "1.0.0"
    ```
  </Step>

  <Step title="Lister les dépendances du projet">
    Ensuite, nous allons lister les dépendances requises pour notre projet. Nous pouvons spécifier à la fois les dépendances de développement et de production. Les dépendances de production sont listées sous la section `dependencies`, tandis que les dépendances de développement peuvent être listées sous `optional-dependencies` avec un nom de groupe spécifique (par exemple, `dev`).\
    Vous pouvez spécifier des versions pour vos dépendances à l'aide d'opérateurs de comparaison comme `==`, `>=`, `<`... Dans l'exemple ci-dessous, nous ne spécifions pas de versions. Cela signifie que la dernière sera installée.
    Il est recommandé de spécifier des versions exactes pour garantir la reproductibilité et éviter les ruptures dues à des mises à jour incompatibles en production.

    ```toml pyproject.toml theme={null}
    [project]
    name = "my-python-project"
    description = "A sample Python project using pyproject.toml"
    version = "1.0.0"
    dependencies = [
        "discord-py",
        "aiohttp"
    ]

    [project.optional-dependencies]
    dev = [
        "pytest",
        "black"
    ]
    ```
  </Step>

  <Step title="Configurer le système de build">
    Enfin, nous devons spécifier les prérequis du système de build. Cela est nécessaire pour que des outils comme pip sachent comment construire et installer votre projet. Nous utiliserons `setuptools` comme backend de build, un choix courant pour les projets Python, mais vous pouvez en choisir d'autres comme `poetry`.

    ```toml pyproject.toml theme={null}
    [project]
    name = "my-python-project"
    description = "A sample Python project using pyproject.toml"
    version = "1.0.0"
    dependencies = [
        "discord.py",
        "aiohttp"
    ]

    [project.optional-dependencies]
    dev = [
        "pytest",
        "black"
    ]

    [build-system]
    requires = ["setuptools"]
    build-backend = "setuptools.build_meta"
    ```
  </Step>
</Steps>

***

## Installer les dépendances avec pip

Pour installer les dépendances listées dans votre fichier `pyproject.toml`, vous pouvez utiliser pip ou d'autres outils prenant en charge `pyproject.toml`. Cela vous permet de travailler sur votre projet tout en ayant les dépendances installées.

```bash theme={null}
pip install .
```

Cette commande lira le fichier `pyproject.toml`, installera les dépendances listées sous `dependencies` et configurera votre projet pour le développement. Si vous souhaitez également installer les dépendances de développement, vous pouvez utiliser :

```bash theme={null}
pip install .[dev]
```

Cela installera à la fois les dépendances de production et de développement, vous permettant de travailler sur votre projet avec tous les outils nécessaires.

## Bonnes pratiques et conseils :

* **Restez à jour** : Révisez et mettez à jour `pyproject.toml` régulièrement à mesure que vous ajoutez de nouvelles dépendances
* **Utilisez des versions exactes** : Utilisez toujours `==` au lieu de `>`, `>=` ou aucune version pour éviter les surprises en production
* **Gestion de versions** : Committez `pyproject.toml` dans git pour suivre les changements de dépendances et les mises à jour de version
* **Environnement isolé** : Maintenez un environnement virtuel par projet pour éviter les conflits globaux
* **Testez localement** : Avant de déployer, testez le fichier avec `pip install .` dans un nouvel environnement

***

## Prochaines étapes

Une fois votre fichier `pyproject.toml` configuré :

1. Committez-le dans votre dépôt Git.
2. Hébergez votre projet sur **Square Cloud**.
3. Configurez le deploy automatique via GitHub.
4. Bienvenue dans l'hébergement professionnel d'applications Python !

Un fichier `pyproject.toml` bien structuré est la base de toute application Python réussie, garantissant que votre application fonctionne parfaitement sur Square Cloud.