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

# Come creare il tuo file pyproject.toml

> Guida completa al file pyproject.toml in Python: impara come crearlo, elencare le dipendenze, fissare le versioni e preparare il tuo progetto per la produzione.

## File pyproject.toml per Python

Il file `pyproject.toml` è un modo moderno per specificare in un unico file tutti i requisiti del sistema di build e le dipendenze del tuo progetto. Questa guida mostra come creare, configurare e usare `pyproject.toml` per garantire coerenza tra gli ambienti di sviluppo e di produzione.

## Che cos'è un file pyproject.toml?

Un `pyproject.toml` elenca le dipendenze, il sistema di build e altri metadati del tuo progetto Python. Questo permette:

* A te e al tuo team di mantenere ambienti identici
* Ai nuovi collaboratori di riprodurre esattamente l'ambiente
* Di configurare separatamente le dipendenze di sviluppo e di produzione

***

<Steps>
  <Step title="Crea il file pyproject.toml">
    Per prima cosa, crea un file chiamato `pyproject.toml` nella radice del tuo progetto.
  </Step>

  <Step title="Definisci i dettagli del tuo progetto">
    Nel file `pyproject.toml`, inizia definendo i metadati del tuo progetto. Definiremo il nome del progetto, la versione, la descrizione e altre informazioni rilevanti.\
    Il nome del progetto deve essere composto da lettere ASCII, cifre, underscore “\_”, trattini “-” e punti “.”. Non deve iniziare né terminare con un underscore, un trattino o un punto. Per esempio:

    ```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="Elenca le dipendenze del progetto">
    Successivamente, elencheremo le dipendenze necessarie al nostro progetto. Possiamo specificare sia le dipendenze di sviluppo che quelle di produzione. Le dipendenze di produzione sono elencate nella sezione `dependencies`, mentre le dipendenze di sviluppo possono essere elencate sotto `optional-dependencies` con un nome di gruppo specifico (es. `dev`).\
    Puoi specificare le versioni delle tue dipendenze usando operatori di confronto come `==`, `>=`, `<`... Nell'esempio seguente non specifichiamo le versioni. Questo significa che verrà installata l'ultima disponibile.
    Si consiglia di specificare versioni esatte per garantire la riproducibilità e prevenire malfunzionamenti dovuti ad aggiornamenti incompatibili in produzione.

    ```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="Configura il sistema di build">
    Infine, dobbiamo specificare i requisiti del sistema di build. Questo è necessario affinché strumenti come pip sappiano come compilare e installare il tuo progetto. Useremo `setuptools` come backend di build, una scelta comune per i progetti Python, ma puoi sceglierne altri come `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>

***

## Installa le dipendenze con pip

Per installare le dipendenze elencate nel tuo file `pyproject.toml`, puoi usare pip o altri strumenti che supportano `pyproject.toml`. Questo ti consente di lavorare al tuo progetto con le dipendenze già installate.

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

Questo comando leggerà il file `pyproject.toml`, installerà le dipendenze elencate sotto `dependencies` e configurerà il tuo progetto per lo sviluppo. Se vuoi installare anche le dipendenze di sviluppo, puoi usare:

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

Questo installerà sia le dipendenze di produzione che quelle di sviluppo, permettendoti di lavorare al tuo progetto con tutti gli strumenti necessari.

## Buone pratiche e consigli:

* **Mantieni aggiornato**: Rivedi e aggiorna regolarmente `pyproject.toml` man mano che aggiungi nuove dipendenze
* **Usa versioni esatte**: Usa sempre `==` invece di `>`, `>=` o nessuna versione per evitare sorprese in produzione
* **Versionamento**: Effettua il commit di `pyproject.toml` su git per tracciare le modifiche alle dipendenze e gli aggiornamenti di versione
* **Ambiente isolato**: Mantieni un ambiente virtuale per progetto per evitare conflitti globali
* **Prova in locale**: Prima del deploy, testa il file con `pip install .` in un nuovo ambiente

***

## Prossimi passi

Con il tuo file `pyproject.toml` configurato:

1. Effettua il commit sul tuo repository Git.
2. Ospita il tuo progetto su **Square Cloud**.
3. Configura il deploy automatico tramite GitHub.
4. Benvenuto nell'hosting professionale di applicazioni Python!

Un file `pyproject.toml` ben strutturato è la base per qualsiasi applicazione Python di successo, garantendo che la tua applicazione funzioni perfettamente su Square Cloud.