9.23 `distutils.text_file` -- The TextFile class

Questo modulo fornisce la classe TextFile, che mette a disposizione un'interfaccia a file di testo che (facoltativamente) si occupa di eliminare i commenti, ignorare le righe vuote ed unire le righe con dei backslash.

class TextFile( [filename=None, file=None, **options])

Questa classe fornisce un oggetto simil-file che si occupa di tutti i compiti che comunemente si vogliono fare quando si processa un file di testo che ha una sintassi riga per riga: elimina i commenti (quelli in cui # è il carattere che rappresenta il commento), salta le righe vuote, unisce righe adiacenti, inserendo l'escape al carattere di fine riga (per esempio backslash alla fine della riga), rimuove spazi vuoti all'inizio o alla fine. Tutto ciò è facoltativo e controllabile indipendentemente.

La classe fornisce un metodo warn() per la generazione di messaggi di avviso che riportano il numero di riga fisica, sia se la riga logica in questione spazia tra multiple righe fisiche. Fornisce anche unreadline() per l'implementazione di line-at-a-time lookahead.

L'istanza TextFile viene creata sia con filename, file o entrambe. L'eccezione RuntimeError viene sollevata se entrambi sono None. filename dovrebbe essere una stringa e file un oggetto file (o qualcosa che fornisce i metodi readline() e close()). Si raccomanda che venga fornito almeno filename, in modo che TextFile possa includerlo nel messaggio di avvertimento. Se file non viene fornito, TextFile crea il proprio, usando la funzione built-in open().

Le opzioni sono tutte booleane e controllano i valori restituiti da readline().

nome dell'opzione descrizione predefinito

rimuove dal carattere "#" alla fine della riga, compreso ogni spazio vuoto, fino al carattere "#"--fatta eccezione se segnato da un backslash true
rimuove gli spazi vuoti restanti da ogni riga prima di restituirla false
rimuove gli spazi vuoti prima e dopo (incluso il terminatore di riga!) da ogni riga prima di restituirla true
salta le righe vuote *dopo* la rimozione del commento e degli spazi vuoti. (Se sia lstrip_ws che rstrip_ws hanno come valore falso, alcune righe possono essere formate da spazi vuoti solitari: questi non verranno saltati, anche se skip_blanks è vero.) true
se un backslash è l'ultimo carattere non-di-fine-riga su di una riga, dopo la rimozione dei commenti e degli spazi vuoti, unisce la riga seguente all'attuale, a formare una sola riga logica; se N righe consecutive terminano con un backslash, N+1 righe verranno unite a formare una sola riga logica false
rimuove gli spazi restanti dalle righe che vengono unite a quella precedente; solo se "(join_lines and not lstrip_ws)" false

nome dell'opzione	descrizione	predefinito
	rimuove dal carattere "`#`" alla fine della riga, compreso ogni spazio vuoto, fino al carattere "`#`"--fatta eccezione se segnato da un backslash	true
	rimuove gli spazi vuoti restanti da ogni riga prima di restituirla	false
	rimuove gli spazi vuoti prima e dopo (incluso il terminatore di riga!) da ogni riga prima di restituirla	true
	salta le righe vuote dopo la rimozione del commento e degli spazi vuoti. (Se sia lstrip_ws che rstrip_ws hanno come valore falso, alcune righe possono essere formate da spazi vuoti solitari: questi non verranno saltati, anche se `skip_blanks` è vero.)	true
	se un backslash è l'ultimo carattere non-di-fine-riga su di una riga, dopo la rimozione dei commenti e degli spazi vuoti, unisce la riga seguente all'attuale, a formare una sola riga logica; se N righe consecutive terminano con un backslash, N+1 righe verranno unite a formare una sola riga logica	false
	rimuove gli spazi restanti dalle righe che vengono unite a quella precedente; solo se "`(join_lines and not lstrip_ws)`"	false

Si noti che come rstrip_ws può rimuovere il carattere di nuova riga, la semantica di readline(), deve differire da quella del metodo readline() integrato nell'oggetto file! In particolare, readline() restituisce None per la fine del file: una stringa vuota potrebbe essere semplicemente una riga vuota (o una riga di spazi vuoti), se rstrip_ws è vero ma skip_blanks no.

open( filename): Apre un nuovo file filename. Questo si sovrappone a qualsiasi argomento del costruttore file o filename.

close( ): Chiude il file corrente e rimuove qualsiasi informazione circa il file stesso (incluso il nome del file ed il numero della riga corrente).

warn( msg[,line=None]): Stampa (su stderr) un messaggio di avviso collegato alla riga logica corrente nel file corrente. Se la riga logica corrente nel file, riguarda righe fisiche multiple, l'avviso riguarda l'intero insieme, come ""righe 3-5"". Se line viene fornito, sovrascrive la numerazione di riga corrente; potrebbe essere una lista o una tupla, per indicare un insieme di righe fisiche, o un numero intero per una singola riga fisica.

readline( ): Legge e restituisce una singola riga logica dal file corrente (o da un buffer interno se viene precedentemente considerata ``unread'' con unreadline()). Se l'opzione join_lines è vera, questo può indicare la lettura di righe fisiche multiple in una singola striga. Aggiorna il numero della riga corrente, così chiamando warn() dopo readline(), emette un avviso circa la riga/righe appena letta. Restituisce None sulla fine del file, fintantoché la stringa vuota può capitare se rstrip_ws è vera ma strip_blanks no.

readlines( ): Legge e restituisce l'elenco di tutte le righe logiche restanti nel file corrente. Questo aggiorna il numero di riga corrente all'ultima riga nel file.

unreadline( line): Inserisce line (una stringa) in un buffer interno che verrà verificato da future chiamate a readline(). Comodo per l'implementazione di un parser di righe che funzioni una riga per volta. Si noti che le righe considerate ``unread'' con unreadline non vengono successivamente ripulite (rimozione di spazi vuoti, o altro) quando lette con readline. Se chiamate multiple vengono fatte a unreadline prima di una chiamata a readline, le righe verranno restituite in ordine, a partire dalla più recente.

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

9.23 distutils.text_file -- The TextFile class

9.23 `distutils.text_file` -- The TextFile class