Python Academy · Lezione

Struttura del progetto e pyproject.toml

Q: La lezione «Struttura del progetto e pyproject.toml» è gratuita?

Sì — il testo completo di «Struttura del progetto e pyproject.toml» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Python Academy, passa a CoddyKit PRO. Il corso Python Academy include 4 lezioni in totale.

Q: Cosa imparerò in «Struttura del progetto e pyproject.toml»?

Organizzare un pacchetto Eserciti Python Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Q: Ho bisogno di esperienza per iniziare Python Academy?

Non è richiesta alcuna esperienza precedente. Python Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 1 di 4.

Q: Quanto tempo richiede la lezione «Struttura del progetto e pyproject.toml»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Q: Posso scrivere ed eseguire codice in questa lezione Python Academy?

Sì. Ogni lezione Python Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Organizzare un pacchetto

Struttura del progetto e pyproject.toml è una lezione Python Academy gratuita su CoddyKit. Questa è la lezione 1 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Python Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Python Academy include 4 lezioni in totale.

Perché creare un pacchetto del codice

Uno script risiede sul proprio computer; un pacchetto può essere installato da chiunque con pip install. La creazione di un pacchetto trasforma una cartella di codice in un'unità distribuibile, versionata e riutilizzabile.

Il primo passo consiste in una struttura del progetto ordinata e in un file di configurazione.

La struttura src

La struttura consigliata colloca il codice importabile nella directory src/:

src/mypackage/__init__.py
src/mypackage/core.py
pyproject.toml
README.md e tests/

La struttura src impedisce di importare accidentalmente il codice dalla radice del progetto invece che dalla copia installata.

Il file init.py

__init__.py contrassegna una directory come pacchetto importabile ed esegue il proprio contenuto quando il pacchetto viene importato per la prima volta. È anche il punto in cui si espone l'API pubblica importando i nomi principali.

Anche un __init__.py vuoto è sufficiente per creare un pacchetto.

package_dir = 'src/mypackage'
files = ['__init__.py', 'core.py', 'utils.py']
for f in files:
    print(package_dir + '/' + f)
print('Importable as:', 'mypackage')

Che cos'è pyproject.toml

pyproject.toml è l'unico file di configurazione standardizzato (PEP 518/621) per la creazione moderna di pacchetti Python. Sostituisce il vecchio setup.py nella maggior parte dei progetti e viene letto dagli strumenti di build.

Utilizza il formato TOML: sezioni tra parentesi quadre e righe nella forma chiave = valore.

La tabella build-system

La tabella [build-system] indica agli strumenti come creare il pacchetto. Una scelta comune:

requires = ['setuptools', 'wheel']
build-backend = 'setuptools.build_meta'

Altri backend includono Hatchling e Flit; il principio è lo stesso.

La tabella project

La tabella [project] contiene i metadati: name, version, description, authors, readme, requires-python e dependencies. Sono i dati che gli utenti vedono su PyPI.

La si può considerare la carta d'identità del pacchetto.

project = {
    'name': 'mytool',
    'version': '0.1.0',
    'requires-python': '>=3.9',
    'dependencies': ['requests>=2.0'],
}
for k, v in project.items():
    print(k, '=', v)

Regole per i nomi

Il nome del pacchetto deve essere univoco su PyPI e segue le regole di normalizzazione: non distingue maiuscole e minuscole, mentre trattini e underscore sono considerati equivalenti. Verifichi la disponibilità prima di scegliere definitivamente un nome, per evitare conflitti al momento del caricamento.

name = 'My_Cool.Tool'
normalized = name.lower().replace('_', '-').replace('.', '-')
print('PyPI normalized name:', normalized)

Dichiarare le dipendenze

Elenchi le dipendenze di runtime in dependencies, specificando vincoli di versione come 'requests>=2.28,<3'. Gli extra opzionali vanno indicati in [project.optional-dependencies] e possono essere installati con pip install mytool[dev].

Mantenga i vincoli il più possibile permissivi, purché in sicurezza, così il pacchetto può coesistere con gli altri.

Entry point

Per distribuire uno strumento da riga di comando, aggiunga un elemento [project.scripts] come mytool = 'mypackage.cli:main'. Dopo l'installazione, digitando mytool viene eseguita quella funzione. È così che le CLI come black o pytest rendono disponibili i propri comandi.

Includere file non di codice

I file di dati (template, JSON) non vengono inclusi automaticamente. Configuri i dati del pacchetto nel build backend, in modo che i file vengano inseriti nella wheel. Dimenticarsene è una causa comune di bug del tipo «funziona in locale ma si rompe quando viene installato».

Installazioni modificabili per lo sviluppo

Durante lo sviluppo, installi il pacchetto in modalità modificabile con pip install -e .. Le modifiche al codice sorgente hanno effetto immediatamente, senza reinstallare. Questo richiede un pyproject.toml corretto, un altro motivo per configurarlo fin dall'inizio.

Le installazioni modificabili offrono il ciclo di feedback più rapido durante l'iterazione su un pacchetto.

Verifica rapida

Verifichi le Sue conoscenze sulla struttura dei progetti.

Riepilogo

Ha definito la struttura di un pacchetto:

Utilizzare la struttura src, con __init__.py a contrassegnare i pacchetti
pyproject.toml è il file di configurazione standard: [build-system] e [project]
Dichiarare name, version, requires-python e dependencies
Aggiungere entry point [project.scripts] per le CLI e configurare i dati del pacchetto

Domande Frequenti

La lezione «Struttura del progetto e pyproject.toml» è gratuita?