Vai al contenuto principale

​
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
1

Crea il file pyproject.toml

Per prima cosa, crea un file chiamato pyproject.toml nella radice del tuo progetto.
2

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:
pyproject.toml
[project]
name = "my-python-project"
description = "A sample Python project using pyproject.toml"
version = "1.0.0"
3

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.
pyproject.toml
[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"
]
4

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.
pyproject.toml
[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"

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