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.