4.9.1.3 Oggetti StreamReader

La classe StreamReader è una classe derivata di Codec e definisce i seguenti metodi che ogni lettore di flusso deve definire affinché sia compatibile con il registro dei codec di Python.

class StreamReader( stream[, errors])

Costruttore per l'istanza StreamReader.

Tutti i lettori di flusso devono fornire questa interfaccia per il costruttore. Sono liberi di aggiungere ulteriori argomenti chiave, ma solo quelli qui definiti vengono usati dal registro Python dei codec.

stream deve essere un oggetto simile a file, aperto in modalità lettura dati (modo binario).

La classe StreamWriter può implementare differenti schemi di gestione degli errori, fornendo l'argomento chiave errors. Questi sono i parametri definiti:

'strict' Solleva un'eccezione ValueError (o una classe derivata); questo è il predefinito.
'ignore' Ignora il carattere e continua con il successivo.
'replace' Sostituisce con un opportuno carattere di rimpiazzo.

L'argomento errors verrà assegnato ad un attributo con lo stesso nome. Assegnazioni a questo attributo rendono possibile il cambio con differenti strategie di gestione dell'errore durante la vita dell'oggetto StreamWriter.

L'insieme dei valori consentiti per l'argomento errors può venire esteso con register_error().

read( [size])

Decodifica i dati dallo flusso, e restituisce l'oggetto risultante.

size indica approssimativamente il numero massimo di bytes da leggere dal flusso per la decodifica. Il decodificatore può modificare questa impostazione in base alle necessità. Il valore predefinito -1 indica di leggere e decodificare il più possibile. size viene utilizzato per prevenire la decodifica di file troppo grandi in un solo passaggio.

Il metodo dovrebbe usare un'attenta strategia di lettura, cioè dovrebbe la massima quantità possibile di dati, consentita dala definizione della codifica e dalla misura indicata, per esempio se sono disponibili sul flusso delle estensioni facoltative di codifica o dei marcatori di stato, anche questi devono venir letti.

readline( [size])

Legge una riga dallo stream di input e restituire i dati decodificati.

Diversamente dal metodo readlines(), questo metodo eredita la conoscenza dell'interruzione di riga dal metodo readlines() dello stream sottostante - attualmente non esiste supporto per l'interruzione di riga usando il codec decoder, a causa di mancanze di righe nel buffer. Le classi derivate dovrebbero comunque, se possibile, tentare di implementare questo metodo, usando la loro conoscenza dell'interruzione di riga.

size, se indicato, viene passato come argomento dimensione nel metodo readline() dello stream.

readlines( [sizehint])

Legge tutte le righe disponibili nel flusso di input e le restituisce come una lista di righe.

Le interruzioni di riga vengono implementate usando il metodo decoder di codifica, e vengono incluse nell'elenco dei valori.

sizehint, se indicato, viene passato come argomento size, nel metodo read() dello stream.

reset( ): Azzera i buffer dei codec utilizzati per il mantenimento dello stato.
Notate che nessun riposizionamento nello stream dovrebbe venire messo in atto. Questo metodo viene utilizzato principalmente come sistema di recupero da errori di decodifica.

In aggiunta ai metodi sopra indicati, StreamReader deve anche ereditare tutti gli altri metodi e attributi dallo stream sottostante.

Le prossime due classi base vengono incluse per comodità. Non sono necessarie al registro dei codec, ma il loro utilizzo può tornare utile.

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