2.3.9 File oggetto

I file oggetto vengono implementati utilizzando il package stdio del C, e possono essere creati con il costruttore built-in file() descritto nella sezione 2.1, ``Funzioni built-in''^2.10 I file oggetto vengono restituiti anche da degli altri metodi e funzioni built-in, come os.popen(), os.fdopen() ed il metodo makefile() degli oggetti socket.

Quando un'operazione su file fallisce per motivi legati all'I/O, viene sollevata l'eccezione IOError. Questo include situazioni dove l'operazione non viene definita per qualche ragione, come un seek() su un dispositivo tty o la scrittura di un file aperto in sola lettura.

I file hanno i seguenti metodi:

close( ): Chiude il file. Un file chiuso non può essere più letto o scritto. Ogni operazione che richiede l'apertura di quel file solleverà un'eccezione del tipo ValueError dopo che il file sarà stato chiuso. È concesso di chiamare più di una volta il metodo close().

flush( ): Svuota il buffer interno, come fflush() di stdio. Questo può essere una no-op su qualche oggetto simile a file.

fileno( ): Restituisce l'intero ``descrittore di file'' che viene usato dall'implementazione sottostante per la richiesta di operazioni di I/O da parte del sistema operativo. Questo può essere utile per altre interfacce di basso livello che usano i descrittori di file, come il modulo fcntl o os.read() e simili. Note: Gli oggetti simili a file che non hanno un reale descrittore di file non dovrebbero fornire questo metodo!

isatty( ): Restituisce True se il file è connesso ad un dispositivo tty(-simile), altrimenti False. Note: Se un simile a file non è associato ad un file reale, questo metodo non dovrebbe essere implementato!

next( ): Un file oggetto è il suo iteratore personale, per esempio iter(f) restituisce f (a meno che f non sia chiuso). Quando un file viene usato come iteratore, tipicamente in un ciclo for (per esempio, for line in f: print line), il metodo next() viene chiamato ripetutamente. Questo metodo restituisce la successiva riga di input, o solleva un'eccezione di tipo StopIteration quando viene raggiunto l'EOF. Per avere un ciclo for più efficiente, che iteri su ogni riga del file (un'operazione molto comune), il metodo next() usa un buffer nascosto read-ahead. Come conseguenza dell'uso di un buffer read-ahead, combinando il metodo next() con un altro metodo per i file (come readline()), l'associazione non funzionerà correttamente. Tuttavia, usando seek() per inserire il file in una posizione assoluta si riuscirà a svuotare il buffer read-ahead. Nuovo nella versione 2.3.

read( [size]): Legge al più una quantità (size) di byte da un file (di meno se viene letto l'EOF prima di ottenere la quantità size di byte). Se l'argomento size è negativo o viene omesso, legge tutti i dati fino a che non viene raggiunto l'EOF. I byte vengono restituiti come un oggetto stringa. Viene restituita una stringa vuota quando l'EOF viene incontrato immediatamente. (Per certi file , come ttys, ha senso continuare la lettura dopo che è stato incontrato l'EOF.) Notate che questo metodo può chiamare la funzione C sottostante fread() più di una volta, per acquisire più byte ed arrivare il più vicino possibile alla dimensione (size). Notate anche che, quando in modo non bloccante, possono essere restituiti meno dati di quelli richiesti, se non viene passato il parametro size.

readline( [size]): Legge un'intera riga dal file. Un codice di controllo di fine riga viene catturato nella stringa (ma è assente quando il file finisce con una riga incompleta).^2.11 Se l'argomento size è presente e non negativo, rappresenta il conteggio massimo dei byte (inclusi i caratteri di fine riga) e può restituire una riga incompleta. Una stringa vuota viene restituita solo quando viene trovato immediatamente un EOF. Note: Diversamente dal metodo fgets() di stdio, la stringa restituita contiene caratteri nulli ('\0') se vengono incontrati nell'input.

readlines( [sizehint]): Legge fino a EOF usando readline(), e restituisce una lista contenente le righe lette. Se l'argomento facoltativo sizehint è presente, invece di leggere fino a EOF, legge le righe intere il cui valore approssimativo ammonta a sizehint byte (possibilmente dopo l'arrotondamento superiore alla misura del buffer interno). Usando l'implementazione di oggetti con interfaccia simile a file, si potrà scegliere di ignorare sizehint se non può essere implementato, o se non può esserlo efficientemente.

xreadlines( ): Questo metodo restituisce le medesime funzionalità di iter(f). Nuovo nella versione 2.1.
Deprecato dalla versione 2.3 di Python. Usate invece "for line in file".

seek( offset[, whence]): Imposta la corrente posizione del file, come fseek() di stdio. L'argomento whence è facoltativo e per definizione viene impostato a 0 (posizionamento assoluto del file); altri valori sono 1 (ricerca relativa alla posizione corrente) e 2 (ricerca relativa alla fine del file). Non ci sono valori restituiti. Notate che se il file viene aperto in modalità appending (NdT: aggiunta) (modo 'a' o 'a+') tutte le operazioni seek() non verranno effettuate alla prossima scrittura. Se il file viene aperto solo in scrittura in modalità append (modo 'a'), questo metodo è essenzialmente un no-op, ma rimane utile per file aperti in modalità append con la lettura abilitata (modo 'a+'). Se il file viene aperto in modalità testo (mode 't'), solo gli offset restituiti da tell() sono ammessi. L'uso di altri offset causa comportamenti imprevisti.
Notate che non tutti i file oggetto sono soggetti al metodo seek().

tell( ): Restituisce la corrente posizione del file, come il metodo ftell() di stdio.

truncate( [size]): Tronca la dimensione del file. Se l'agomento facoltativo size è presente, il file viene troncato a (al massimo) quella misura. La misura viene predefinita alla posizione corrente. La posizione corrente nel file non viene cambiata. Notate che se la misura specificata eccede la misura del file corrente, il risultato dipende dalla piattaforma: risultati possibili includono che il file resti immutato, aumenti fino alla misura specificata come se fosse zero-filled, o incrementi fino alla misura specifica con nuovo contenuto non specificato. Disponibilità: Windows e la maggior parte delle varianti Unix.

write( str): Scrive una stringa nel file. Non ci sono valori restituiti. Fino a che viene bufferizzata, la stringa non può essere mostrata nel file prima che vengano chiamati i metodi flush() o close().

writelines( sequence): Scrive una sequenza di stringhe nel file. La sequenza può essere ogni oggetto iterabile che produce stringhe. Non ci sono valori restituiti. (Il nome viene inteso per ricercare readlines(); writelines() non aggiunge separatori di riga.)

File supporta il protocollo iteratore. Ogni iterazione restituisce lo stesso risultato di file.readline(), e l'iterazione finisce quando il metodo readline() restituisce una stringa vuota.

I file oggetto possono offrire un numero di altri interessanti attributi. Questi non sono richiesti per gli oggetti simile a file, ma dovrebbero essere implementati se hanno senso per il particolare oggetto.

closed: Un valore booleano indicante il corrente stato del file oggetto. Questo è un attributo in sola lettura; il metodo close() cambia il valore. Può non essere disponibile su tutti gli oggetti simile a file.

encoding: La codifica usata dal file. Quando delle stringhe Unicode vengono scritte in un file, vengono convertite in stringhe di byte, usando questa codifica. In aggiunta, quando il file è connesso ad un terminale, l'attributo prende la codifica che il terminale usa abitualmente (questa informazione potrebbe essere sbagliata se l'utente ha il terminale configurato male). L'attributo è in sola lettura e non può essere presente su tutti gli oggetti simile a file. Potrebbe essere anche None, in quel caso il file userà la codifica predefinita del sistema per convertire le stringhe Unicode.
Nuovo nella versione 2.3.

mode: Il modo I/O per il file. Se il file è stato creato usando la funzione built-in open(), questo sarà il valore del parametro mode. Questo è un attributo in sola lettura e può non essere presente in tutti gli oggetti simile a file.

name: Se il file oggetto è stato creato usando open(), il nome del file. Altrimenti, alcune stringhe che indichino il sorgente del file oggetto, nella forma "<...>". Questo è un attributo in sola lettura e può non essere presente in tutti gli oggetti simile a file.

newlines: Se Python è stato compilato con l'opzione --with-universal-newlines al momento del configure (predefinita), questo attributo in sola lettura esiste, e per i file aperti in modalità di lettura universal newline (NdT: fine riga), tiene traccia dei tipi di fine riga incontrati durante la lettura del file. I valori che possono essere presi in considerazione sono '\r', '\n', '\r\n', None (sconosciuto, non vengono più letti i fine riga) o una tupla contenente tutti i tipi di fine riga visti, per indicare i fine riga multipli che sono stati trovati. Per i file che non vengono letti nel modo universal newline il valore di questi attributi sarà None.

softspace: Valore booleano che indica se uno spazio necessita di essere stampato prima di un altro valore quando si usa l'istruzione print. Le classi che stanno tentando di simulare un file oggetto dovrebbero avere anche un attributo softspace scrivibile, che dovrebbe essere inizializzato a zero. Questo sarà automatico per la maggior parte delle classi implementate in Python (dovrà essere usata una certa cutela per gli oggetti che sovrascrivono gli attributi di accesso); i tipi implementati in C dovranno fornire un attributo softspace scrivibile. Note: Questo attributo non viene usato per controllare l'istruzione print, ma permetterà l'implementazione di print per tenere traccia del suo stato interno.

Footnotes

... built-in''^2.10: file() è nuovo in Python 2.2. Il più vecchio built-in open() è un alias per file().
... incompleta).^2.11: Il vantaggio di lasciare il carattere di fine riga è che restituisce una stringa vuota, inequivocabile segno della fine del file. È anche utilizzabile (nei casi in cui può interessare, per esempio, se voleste fare una copia esatta del file mentre ne state analizzando le righe) per avvertire se l'ultima riga del file finisce con un carattere di fine riga oppure no (sì, questo succede!).

Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.