Python pratico

Struttura minima di un progetto Python «ai riparo»

12 min di lettura
Lente d’ingrandimento su IDE scuro che mette a fuoco l’albero minimo di un progetto Python
Windows macOS Linux
Foto: Alex Lunalbi · ai riparo · Proprietario

Struttura minima di un progetto Python nello stile ai riparo: cartella, script, .venv, cosa tenere fuori e come verificarla su Windows, macOS e Linux.

Se usi il computer per lavorare, prima o poi ti capita: scarichi uno script utile, magari proprio da ai riparo, lo salvi sul Desktop, lo lanci e speri che funzioni. Poi ne scarichi un altro. Nel giro di un mese ti ritrovi con una decina di file .py sparsi, moduli mancanti, pacchetti installati a caso nel sistema e la paura di rompere qualcosa ogni volta che digiti un comando.

Per evitare questo caos serve disciplina, ma non serve un’architettura complessa.

In questo articolo ti mostro la struttura minima di un progetto Python. È lo scheletro fisso, essenziale e ripetibile che uso come standard per tutti gli strumenti locali presentati su ai riparo. Che tu stia scaricando un’utility per pulire i metadati delle foto o scrivendo il tuo primo generatore di password, questa è la base di partenza: una cartella, uno script, un ambiente virtuale e regole chiare su cosa tenere dentro e cosa lasciare fuori.

ℹ️ Nota / Prerequisito operativo
Serve Python già installato (consigliata la 3.10 o successiva) e sapere come aprire il terminale.
Se Python manca, installalo prima (guide opzionali rispetto a questa procedura): Windows, macOS, Linux.
Se i comandi base del terminale ti sono nuovi, la lettura opzionale è Terminale: comandi minimi per gli script.

Perché adottare una struttura fissa e «minima»

Quando si parla di organizzare file Python, in rete si trova di tutto. Molti tutorial consigliano cartelle src/, file __init__.py ovunque, Poetry, Docker.

Se stai costruendo un’applicazione web da mandare in produzione, sono ottimi consigli. Ma se usi Python per risolvere un problema locale sul tuo computer (automatizzare un compito, analizzare un file, cifrare un testo), tutta quell’infrastruttura è un peso inutile: aggiunge complessità senza darti beneficio reale in sicurezza o stabilità.

La struttura minima di ai riparo segue una regola semplice: isolamento totale con il minimo sforzo.

Caratteristica Progetto minimo ai riparo Applicazione complessa (es. Django)
Cartella dedicata Dove vivono i file Sempre Sempre
Ambiente virtuale (`.venv`) Isolamento delle dipendenze Uno per cartella Spesso gestito da tool esterni (Poetry, pipenv)
Sottocartella `src/` Separazione tra logica e test No Quasi sempre consigliata
Gestione pacchetti Come si installano le librerie `pip` + `requirements.txt` (solo se serve) `pyproject.toml`, Dockerfile, requirements multipli

Niente over-engineering. Ogni progetto è un compartimento stagno: se lo cancelli, sparisce tutto senza lasciare tracce nel sistema operativo.

L’albero di riferimento: come deve apparire

Se aprissi il progetto con l’Esplora file o da terminale, questa è la gerarchia di riferimento. Niente di più obbligatorio, niente di meno essenziale.

mio-progetto/
│
├── .venv/                  # Ambiente virtuale isolato (generato dal comando venv)
├── script_principale.py    # Codice che esegue il lavoro
│
├── requirements.txt        # (Opzionale) Elenco delle librerie esterne
└── .gitignore              # (Opzionale ma utile) Cosa non condividere / non backupare

Come convenzione, la cartella principale ha un nome tutto minuscolo con parole separate da trattini (kebab-case). Il file Python usa i trattini bassi (snake_case). È una pratica comune: evita attriti con gli import e rende i percorsi leggibili.

💡 Consiglio pratico — Cartelle nascoste
Su macOS e Linux, qualsiasi file o cartella che inizia con un punto (.venv, .gitignore) è nascosto di default nel Finder o nel file manager. Da terminale li vedi con ls -a.
Su Windows, in Esplora file: Visualizza → Mostra → Elementi nascosti.

Ora costruisci questo scheletro partendo da zero. L’ordine dei passaggi conta.

Passaggio 1 — Creare la cartella del progetto

Il primo errore comune è aprire l’editor, incollare il codice e salvarlo direttamente in Documenti o, peggio, sul Desktop.

Un progetto Python, anche se composto da un solo file, ha bisogno di una stanza dedicata. Così i file generati (log, database locali, output) non inquinano il resto del sistema.

Percorso principale: Windows. Subito dopo: macOS e Linux.

Windows

  1. Tasto Windows → digita cmd oppure powershell → Invio.
  2. Crea la cartella ed entraci:
cd %USERPROFILE%\Documents
mkdir strumento-privacy
cd strumento-privacy

In PowerShell puoi usare anche:

cd $env:USERPROFILE\Documents
mkdir strumento-privacy
cd strumento-privacy

Per verificare dove sei: digita cd (senza argomenti) e premi Invio: ti mostra il percorso completo.

macOS

  1. Cmd + Spazio → digita Terminale → Invio.
  2. Crea la cartella ed entraci:
cd ~/Documents
mkdir strumento-privacy
cd strumento-privacy

Verifica con pwd.

Linux

  1. Apri il terminale (dipende dalla distro: spesso Ctrl + Alt + T).
  2. Stessi comandi di macOS:
cd ~/Documents
mkdir strumento-privacy
cd strumento-privacy

Verifica con pwd.

Da questo momento in poi, tutto ciò che fai avviene dentro questa cartella.

Passaggio 2 — Il file script base (stub)

Ora che la scatola è pronta, mettici il motore. Nelle guide di ai riparo questo è il file in cui incolli il codice verificato, o quello che scrivi tu.

Puoi crearlo dall’editor (VS Code, Notepad++, TextEdit — salvando come app_locale.py) oppure con un comando rapido.

Windows

type NUL > app_locale.py

macOS e Linux

touch app_locale.py

Apri il file e inserisci questo codice di test. Usa solo la libreria standard: non serve alcun pacchetto esterno. Serve a confermare che l’interprete risponde correttamente.

import sys
import datetime

def main():
    print("=== Test struttura ai riparo ===")
    print(f"Data e ora: {datetime.datetime.now()}")
    print(f"Versione Python in uso: {sys.version.split()[0]}")
    print("Tutto pronto per lavorare in locale.")

if __name__ == "__main__":
    main()

Salva e chiudi l’editor. Non lanciarlo ancora: prima le mura difensive.

Passaggio 3 — Creare e attivare l’ambiente virtuale (.venv)

Questo è il passaggio che separa chi «rompe» l’installazione di sistema da chi lavora in modo consapevole.

Un ambiente virtuale è una copia isolata dell’interprete Python e delle sue librerie. Crearlo dentro la cartella del progetto significa che qualunque cosa installerai resterà confinata lì.

Assicurati di essere ancora nel terminale, dentro strumento-privacy.

Crea il .venv

Windows

python -m venv .venv

macOS e Linux

python3 -m venv .venv

L’operazione impiega qualche secondo. Se ha successo, di solito non stampa nulla. Comparirà una cartella .venv (nascosta su macOS/Linux).

⚠️ Attenzione — Linux Debian/Ubuntu
Se compare un errore sul modulo venv, installalo: sudo apt install python3-venv, poi ripeti il comando.

Attiva il .venv

Se non lo attivi, il terminale continua a usare il Python globale del sistema.

Windows (Prompt dei comandi)

.venv\Scripts\activate.bat

Windows (PowerShell)

.venv\Scripts\Activate.ps1

⚠️ Attenzione — ExecutionPolicy su Windows
Se PowerShell mostra un errore rosso su ExecutionPolicy e rifiuta lo script, apri PowerShell come utente (non serve Amministratore per lo scope utente) e digita:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Conferma e riprova l’attivazione.

macOS e Linux

source .venv/bin/activate

Come sai che ha funzionato? Guarda il prompt a sinistra del cursore: dovrebbe iniziare con (.venv). Quella è la garanzia: sei nel compartimento stagno.

Lettura opzionale sul «perché» di questi comandi: Ambienti virtuali Python (venv) in 5 minuti.

Passaggio 4 — Il .gitignore minimo essenziale

Anche se il progetto vive solo sul tuo computer e non pensi di caricarlo su GitHub, ti consiglio di creare un file .gitignore.

Perché? Ti abitua fin dal primo giorno a separare codice, dati sensibili e file pesanti. Se un domani farai un backup della cartella o la condividerai, il .gitignore resta una mappa di cosa non ha senso trasferire.

Crea un file chiamato esattamente .gitignore (con il punto all’inizio) nella radice del progetto e inserisci:

# Ambienti virtuali
.venv/
env/

# Cache di Python (file compilati)
__pycache__/
*.py[cod]

# Segreti e variabili d'ambiente locali
.env

# Output personali o di log
*.log
output/
dati_sensibili.csv

Cosa fanno le voci critiche

  • .venv/ — l’ambiente virtuale è pesante e specifico del tuo sistema. Si rigenera in pochi secondi; non ha senso backuparlo o passarlo a qualcuno.
  • __pycache__/ — file temporanei che Python usa per velocizzare l’esecuzione. Inutili da salvare.
  • .env — tipico posto per password locali o chiavi API. Tenerlo in .gitignore riduce il rischio di condividerlo per sbaglio.

Passaggio 5 — Con o senza requirements.txt?

Le dipendenze sono pacchetti scritti da terzi. La filosofia di ai riparo è usare la libreria standard ogni volta che è possibile: è già sul sistema, non richiede download e riduce la superficie di attacco sulla supply chain.

Strada A — Nessuna libreria esterna (preferita)

Se lo script non usa pip install, non fare nulla. Non ti serve requirements.txt. Il progetto è completo così. È la norma per molti script base del sito.

Strada B — Librerie esterne

Se lo script richiede librerie esterne (es. Pillow per le immagini), non lanciare pip a caso: registra le dipendenze.

Crea requirements.txt e blocca la versione, così il comportamento resta riproducibile. Esempio:

requests==2.31.0

Con l’ambiente virtuale attivo (controlla (.venv) nel prompt), installa così:

Windows

python -m pip install -r requirements.txt

macOS e Linux

python3 -m pip install -r requirements.txt

Output atteso tipico: riga Successfully installed ….

💡 Consiglio pratico — Perché python -m pip
Nelle guide di ai riparo non uso quasi mai pip install nudo. Anteporre python -m (o python3 -m) lega l’installazione all’interprete attivo — di solito quello del .venv — e evita conflitti con installazioni globali.
Lettura opzionale: Quando usare pip install e quando no.

Passaggio 6 — Lanciare e verificare

Hai l’ambiente, il codice e (forse) le dipendenze. È il momento di lanciare lo stub.

Sempre con (.venv) visibile:

Windows

python app_locale.py

macOS e Linux

python3 app_locale.py

Se tutto è a posto, vedrai un output simile a questo:

=== Test struttura ai riparo ===
Data e ora: 2026-10-05 20:51:12.123456
Versione Python in uso: 3.12.2
Tutto pronto per lavorare in locale.

Sei pronto. Questo scheletro è la base di lavoro sicura: quando scarichi un tool futuro, sai dove posizionarlo, come isolarlo e come gestirlo senza inquinare il computer.

Cosa NON mettere nella cartella (errori gravi)

Mantenere questa struttura pulita significa anche sapere cosa tenerne fuori. In locale l’errore umano è il rischio più alto.

  1. Credenziali in chiaro nello script. Se serve un token API, non scriverlo in app_locale.py se prevedi di condividere la cartella. Usa un file .env separato (già bloccato dal .gitignore sopra).
  2. Copiare la cartella .venv tra computer diversi. Contiene percorsi assoluti della macchina su cui è nata. Su una chiavetta o su un altro PC si rompe: rigenerala con python -m venv .venv (Windows) o python3 -m venv .venv (macOS/Linux).
  3. Lanciare pip install senza vedere (.venv). Rischi di installare pacchetti globalmente e perdere l’isolamento.
  4. Rinominare la cartella madre mentre il terminale lavora. Se rinomini strumento-privacy con il venv attivo, i percorsi interni saltano. Disattiva (deactivate), rinomina, rientra e riattiva.
  5. Usare il Desktop come base per venti progetti Python. Preferisci una directory dedicata (es. Sviluppo o Script_locali) e crea le sottocartelle lì.

Domande Frequenti (FAQ)

Qual è la struttura minima assoluta di un progetto Python?

Una cartella isolata, uno script .py e la sottocartella dell’ambiente virtuale (.venv). Se usi librerie esterne, aggiungi requirements.txt. Tutto il resto è opzionale o legato a infrastrutture più pesanti.

Devo sempre creare un .venv anche per uno script di 20 righe?

Sì. Creare un .venv richiede un comando e pochi secondi. È una polizza assicurativa gratuita: lo script resta isolato, non interferisce con altri progetti e non modifica il Python globale del sistema.

Serve il requirements.txt se uso solo la libreria standard?

No. Se lo script usa solo moduli integrati (os, sys, csv, datetime, hashlib, …) non installi nulla con pip e non ti serve requirements.txt. Il codice funziona su qualsiasi sistema con Python installato.

Posso tenere tutti gli script scaricati in un’unica cartella con un solo venv?

Puoi, ma lo sconsiglio. Finiresti con un solo grande ambiente, pacchetti misti e file sparsi. Se uno script rovina una dipendenza di un altro, perdi tempo a risolvere conflitti. Una cartella per utilità è più ordinata e sicura.

Devo usare la cartella src/ per i progetti personali?

Per singoli script di automazione o utility scaricate dal blog (come il pulitore di metadati), src/ è una complicazione inutile. Metti il .py nella cartella principale. Se un giorno il progetto diventerà un pacchetto distribuibile, aggiungerai src/ quando servirà davvero.

Ho spostato la cartella del progetto e l’ambiente non funziona più: cosa faccio?

La cartella .venv usa percorsi rigidi. Elimina l’intera .venv, apri il terminale nella nuova posizione e rigenerala: Windows python -m venv .venv, macOS/Linux python3 -m venv .venv. Poi riattivala. È un’operazione distruttiva sul solo ambiente virtuale, non sul tuo script.

Alex Lunalbi

Alex Lunalbi

Security & privacy

Dona su PayPal
Email alex.airiparo@gmail.com
Home ai riparo

Scrivo di sicurezza digitale pratica e codice IA. Su ai riparo ogni procedura è verificata su macchine reali.

Tag
  • python,
  • venv,
  • progetto,
  • sviluppo
Torna alla Home