HOWTO · Python

Scrivi byte su un file in Python

Questo tutorial mostra come scrivere byte in un file binario in Python

In questa pagina

Per scrivere byte in un file in Python, chiama open() con la modalità wb e passa un oggetto compatibile con bytes al metodo write() del file. Usa un blocco with per chiudere automaticamente il file. Scegli invece ab per aggiungere dati al contenuto esistente.

Ogni esempio crea i file in una directory temporanea, che Python elimina al termine del blocco with dell’esempio. Per conservare un file, sostituisci il percorso temporaneo con quello di destinazione.

Come scrivere byte in un file in Python

La w in wb apre un file in scrittura: lo crea se necessario e tronca un file esistente non appena viene aperto. La b seleziona la modalità binaria, quindi Python scrive byte senza codificare il testo né convertire i caratteri di nuova riga.

Esegui questo esempio per scrivere i dati e rileggerli:

Il codice e le etichette o gli output visibili in questa sezione restano in inglese.

from pathlib import Path
from tempfile import TemporaryDirectory

with TemporaryDirectory() as directory:
    path = Path(directory) / "example.bin"
    data = b"This is some binary data."

    with open(path, "wb") as file:
        written = file.write(data)

    with open(path, "rb") as file:
        saved = file.read()

    print(written)
    print(saved == data)
25
True

Per questo file regolare con buffer, write() restituisce il numero di byte scritti. Il programma stampa il conteggio e confronta i dati salvati con quelli originali. La lettura avviene dopo che il blocco di scrittura chiude il file e svuota il buffer di Python. L’estensione .bin è una convenzione per il nome del file: la modalità binaria dipende dall’argomento della modalità di apertura.

Usa xb se vuoi creare un file solo quando non esiste già. A differenza di wb, questa modalità rifiuta di sovrascrivere una destinazione esistente. Nessuna delle due modalità crea le directory padre mancanti.

Scrivere più sequenze di byte in un file

Tieni aperto il file mentre scrivi i blocchi in successione. Ogni chiamata a write() continua dalla posizione corrente; se aprissi il file con wb all’interno del ciclo, i blocchi precedenti verrebbero eliminati.

Il codice e le etichette o gli output visibili in questa sezione restano in inglese.

from pathlib import Path
from tempfile import TemporaryDirectory

chunks = [b"First line.\n", b"Second line.\n", b"Third line.\n"]

with TemporaryDirectory() as directory:
    path = Path(directory) / "chunks.bin"
    with open(path, "wb") as file:
        for chunk in chunks:
            file.write(chunk)

Ogni blocco deve contenere dati compatibili con bytes, come bytes, bytearray o una vista del buffer adatta. Puoi anche passare un iterabile di sequenze di byte a file.writelines(chunks). Nonostante il nome, writelines() non aggiunge separatori né caratteri di nuova riga: se servono, includili nei blocchi. Un ciclo permette inoltre di elaborare i blocchi man mano che arrivano, senza unire l’intero contenuto in memoria.

Scrivere un bytearray in un file

Un oggetto bytes è immutabile, mentre bytearray permette di modificare singoli byte o estendere la sequenza prima di salvarla. Entrambi possono essere scritti direttamente in un file binario.

Il codice e le etichette o gli output visibili in questa sezione restano in inglese.

from pathlib import Path
from tempfile import TemporaryDirectory

payload = bytearray(b"Line 1\n")
payload.extend(b"Line 2\n")
payload[0] = ord("l")

with TemporaryDirectory() as directory:
    path = Path(directory) / "bytearray.bin"
    with open(path, "wb") as file:
        file.write(payload)

Qui, extend() aggiunge un’altra sequenza e l’assegnazione tramite indice modifica il primo byte. Per scrivere non serve convertire il valore con bytes(payload); usa la conversione quando ti occorre altrove un valore immutabile. Le modifiche successive a bytearray non aggiornano automaticamente il file.

Scrivere i dati di BytesIO in un file

BytesIO, del modulo io, fornisce un flusso binario in memoria. Il suo metodo getbuffer() restituisce una vista dell’intero buffer sottostante senza copiarne il contenuto in un oggetto bytes separato.

Il codice e le etichette o gli output visibili in questa sezione restano in inglese.

from io import BytesIO
from pathlib import Path
from tempfile import TemporaryDirectory

with TemporaryDirectory() as directory:
    path = Path(directory) / "buffer.bin"
    with BytesIO() as buffer:
        buffer.write(b"Header\n")
        buffer.write(b"Payload\n")
        with buffer.getbuffer() as view:
            with open(path, "wb") as file:
                file.write(view)

La vista comprende tutti i dati presenti nel buffer, indipendentemente dalla posizione corrente del flusso. Finché la vista esiste, l’oggetto BytesIO non può essere ridimensionato né chiuso; i gestori di contesto annidati rilasciano la vista prima di chiudere il flusso. Usa buffer.getvalue() se ti serve invece un valore bytes. Per copiare i dati con buffer.read(), chiama prima buffer.seek(0) se vuoi partire dall’inizio.

Aggiungere byte o scrivere in una posizione specifica

Apri il file con ab per aggiungere byte alla fine senza troncare il contenuto esistente. Questa modalità crea la destinazione anche se non esiste. Per sovrascrivere byte a un determinato offset in un file esistente, usa r+b e il metodo seek() dell’oggetto file.

Il codice e le etichette o gli output visibili in questa sezione restano in inglese.

from pathlib import Path
from tempfile import TemporaryDirectory

with TemporaryDirectory() as directory:
    path = Path(directory) / "records.bin"
    with open(path, "wb") as file:
        file.write(b"ABCDEF")

    with open(path, "ab") as file:
        file.write(b"GH")

    with open(path, "r+b") as file:
        file.seek(2)
        file.write(b"xy")

seek(2) sposta la posizione all’offset di 2 byte, contando dall’inizio. La scrittura successiva sostituisce due byte senza inserire dati né rimuovere quelli rimanenti. Se una sostituzione più breve deve eliminare i byte finali, usa esplicitamente truncate().

r+b richiede un file esistente e ne conserva il contenuto all’apertura. w+b consente lettura e scrittura, ma prima tronca il file. Evita la modalità di aggiunta per gli aggiornamenti in una posizione specifica: le scritture vengono indirizzate alla fine e usare seek() non è un modo portabile per aggirare questo comportamento. Spostarsi oltre la fine del file non lo estende da solo; una scrittura successiva può estenderlo, mentre i dettagli su come viene gestito lo spazio vuoto dipendono dal file system.

Buffer e scritture di grandi dimensioni

I file binari regolari aperti con open() usano un buffer per impostazione predefinita. Un’impostazione esplicita, come buffering=8192, richiede una dimensione del buffer, ma non garantisce scritture più veloci né impone che ogni scrittura al sistema operativo contenga esattamente 8192 byte.

Per generare grandi quantità di dati, scrivi blocchi riutilizzabili invece di costruire un unico oggetto combinato di grandi dimensioni:

Il codice e le etichette o gli output visibili in questa sezione restano in inglese.

from pathlib import Path
from tempfile import TemporaryDirectory

chunk = b"record\n" * 1024

with TemporaryDirectory() as directory:
    path = Path(directory) / "large.bin"
    with open(path, "wb", buffering=8192) as file:
        for _ in range(100):
            file.write(chunk)

Questo esempio mostra un’impostazione facoltativa del buffer e riutilizza un unico blocco. Scegli la dimensione del buffer misurando il comportamento del tuo carico di lavoro: non esiste una dimensione ottimale per ogni situazione. Quando il file viene chiuso, Python svuota il buffer. Una chiamata anticipata a flush() trasferisce i dati dal buffer al flusso sottostante, ma da sola non garantisce che vengano salvati sul supporto fisico.

Domande frequenti sulla scrittura di byte

Come posso rileggere i byte? Apri il file con rb e chiama file.read(). Il valore restituito è bytes. Per un file di grandi dimensioni, leggi blocchi di dimensione fissa invece di caricare tutto in una volta.

Posso scrivere testo in modalità binaria? Codificalo prima, per esempio con text.encode("utf-8") o bytes(text, "utf-8"). Per ricostruire il testo, chi lo legge deve usare la codifica corrispondente. Se devi salvare solo testo, può essere più chiaro aprire il file in modalità testo con encoding="utf-8".

Perché write() genera un TypeError? Un flusso binario richiede dati compatibili con bytes. Passare direttamente una str, un intero o una lista non soddisfa questo requisito. Codifica il testo oppure converti una sequenza di valori interi che rappresentano byte con bytes(values); ogni intero deve essere compreso tra 0 e 255.

Cosa succede con un contenuto vuoto? Scrivere b"" non scrive byte, ma l’apertura di un file esistente con wb lo ha già troncato. Usa ab per conservare i dati esistenti quando aggiungi contenuto, anche se il nuovo contenuto è vuoto.

Perché la destinazione non è stata creata? Controlla che la directory padre esista e che il processo abbia il permesso di scriverci. Un percorso relativo viene risolto a partire dalla directory di lavoro corrente del processo. Gestisci nel codice le eccezioni OSError pertinenti e ricorda che la scrittura o la chiusura possono fallire anche dopo l’apertura corretta del file.