Cosa fa questo strumento
Il formattatore Python riscrive il codice Python nel diffusissimo stile Black: indentazione coerente, spazi attorno agli operatori, virgolette doppie, due righe vuote tra le definizioni di primo livello e righe lunghe spezzate in punti sensati.
Dietro le quinte esegue il formatter di Ruff, il linter e formatter Python velocissimo scritto in Rust, compilato in WebAssembly. L’output di Ruff corrisponde a Black quasi riga per riga, quindi il codice formattato qui non verrà riformattato dall’hook di pre-commit del tuo progetto.
Come si usa
- Incolla codice Python oppure apri un file
.py. - Il codice formattato compare a destra mentre scrivi.
- Regola le opzioni se il tuo progetto usa uno stile diverso:
- Indentazione: 4 spazi è il valore di PEP 8 e quello predefinito; sono disponibili 2 spazi e tabulazioni.
- Larghezza riga: 88 è il valore predefinito di Black, 79 è il limite di PEP 8, e 100 o 120 vanno bene per schermi più larghi.
- Virgolette: doppie, singole, oppure mantieni le virgolette già usate da ogni stringa.
- Rispetta le virgole finali: mantiene espanse le collezioni che terminano con una virgola.
- Copia o scarica il risultato.
Quando il codice non può essere analizzato, il messaggio di errore mostra dove si è fermato il parser, ad esempio Expected `,`, found `=` alla riga 4, e puoi saltare a quella riga.
Esempio
L’esempio è un piccolo modulo scritto in modo trascurato: import su una sola riga senza spazi, una dataclass con uno spazio prima dei due punti, un metodo indentato con due spazi e un’istruzione if su una riga. Dopo la formattazione ogni blocco usa un’indentazione di quattro spazi, il corpo dell’if passa su una riga a sé, gli operatori ricevono gli spazi, gli apici singoli diventano virgolette doppie e vengono aggiunte righe vuote tra la classe e le funzioni. La lista che terminava con una virgola finale viene espansa con un dizionario per riga.
Cosa non fa il formattatore
La formattazione cambia solo l’impaginazione. Non ordina gli import, non rimuove variabili inutilizzate e non rinomina nulla: sono compiti del linter (ruff check --fix se ne occupa). Commenti e docstring vengono mantenuti, e il formattatore si rifiuta di modificare codice che non riesce ad analizzare invece di tirare a indovinare.
Suggerimenti
- Usa la stessa larghezza di riga del
pyproject.tomldel tuo progetto, così il risultato corrisponde alla tua CI. - Formattare uno snippet prima di pubblicarlo in una domanda o in una review lo rende molto più leggibile.
- Se il codice arriva da un notebook o da una chat e mescola tabulazioni e spazi, il formattatore lo normalizza in un solo passaggio.
Domande frequenti
› L'output è uguale a quello di Black?
Il formatter di Ruff è pensato come sostituto diretto di Black e ne riproduce l'output su oltre il 99,9% delle righe in grandi progetti reali. Le impostazioni predefinite qui (indentazione di 4 spazi, 88 colonne, virgolette doppie) sono quelle di Black.
› Che cos'è la "magic trailing comma"?
Se una lista, una chiamata o una definizione termina con una virgola finale, Black e Ruff la mantengono espansa con un elemento per riga anche quando starebbe su una sola riga. Disattiva l'interruttore per compattare queste collezioni ogni volta che ci stanno.
› Quali versioni di Python sono supportate?
Il parser riconosce la sintassi moderna di Python 3, comprese le istruzioni match, le liste di parametri di tipo e le f-string con virgolette annidate. Il codice Python 2 come `print "x"` è un errore di sintassi.
› Il mio codice viene caricato?
No. Il modulo WebAssembly di Ruff viene scaricato una volta e la formattazione avviene nel tuo browser.