12.20.1 Contenuti del modulo

Il modulo csv definisce le seguenti funzioni:

reader( csvfile[, dialect='excel'[, fmtparam]]): Restituisce un oggetto reader che effettuerà un'iterazione sulle righe di un dato csvfile. csvfile può essere qualsiasi oggetto che supporti il protocollo iterator e che restituisca una stringa ogni volta che il suo metodo next viene chiamato. Se csvfile è un oggetto di tipo file deve essere stato aperto con l'opzione 'b' in tutte le piattaforme dove questo può fare differenza. Un parametro facoltativo dialect può essere utilizzato per definire una serie di parametri specifici di un particolare dialetto CSV. Tale parametro può essere un'istanza di una sotto classe di una classe Dialect oppure una delle stringhe restituite dalla funzione list_dialects. L'ulteriore parametro facoltativo fmtparam può essere utilizzato per sostituire alcuni parametri di formattazione previsti dal dialetto scelto, vedete la sezione 12.20.2, ``Dialetti e parametri di formattazione'' per i dettagli relativi a questi parametri.
Tutti i dati letti vengono restituiti sotto forma di stringhe. Non viene effettuata alcuna conversione automatica del tipo.

writer( csvfile[, dialect='excel'[, fmtparam]]): Restituisce un oggetto writer responsabile per la conversione dei dati dell'utente da stringhe limitate ad un oggetto simile a file. csvfile può essere qualsiasi oggetto con un metodo write. Se csvfile è un oggetto di tipo file deve essere stato aperto con il flag 'b' in tutte le piattaforme dove questo può fare differenza. Un parametro facoltativo dialect può essere utilizzato per definire una serie di parametri specifici di un particolare dialetto CSV. Tale parametro può essere un'istanza di una sotto classe di una classe Dialect, oppure una delle stringhe restituite dalla funzione list_dialects. L'ulteriore parametro facoltativo fmtparam può essere utilizzato per sostituire alcuni parametri di formattazione previsti dal dialetto scelto, vedete la sezione 12.20.2, ``Dialetti e parametri di formattazione'' per i dettagli relativi a questi parametri. Per rendere più semplice possibile l'utilizzo di questo modulo insieme ad altri moduli che implementano la DB API, il valore None viene scritto come una stringa vuota. Sebbene questa sia una trasformazione irreversibile, tuttavia rende più facile la scrittura di valori SQL NULL all'interno di file CSV senza la necessità di elaborare i dati restituiti dalla chiamata cursor.fetch*(). Tutti i dati che non sono di tipo stringa vengono convertiti a tale tipo mediante str() prima di essere scritti.

register_dialect( name, dialect): Associate dialect con name. dialect deve essere una sotto classe della classe csv.Dialect. name deve essere una stringa o un oggetto Unicode.

unregister_dialect( name): Cancella dall'elenco dei dialetti registrati dal dialetto associato al parametro name. Viene sollevata un'eccezione Error se name non è un dialetto registrato.

get_dialect( name): Restituisce il dialetto associato al parametro name. Viene sollevata un'eccezione Error se name non è un dialetto registrato.

list_dialects( ): Restituisce i nomi di tutti i dialetti registrati.

Il modulo csv definisce le seguenti classi:

class DictReader( csvfile[, fieldnames=None,[, restkey=None[, restval=None[, dialect='excel'[, *args, **kwds]]]]]): Crea un oggetto che opera come un normale reader ma che mappa l'informazione letta all'interno di un dizionario le cui chiavi vengono passate dal parametro facoltativo opzionale fieldnames. Se il parametro fieldnames è assente vengono utilizzate come chiavi i valori presenti nella prima riga di csvfile. Se una riga letta ha meno valori della sequenza fieldnames, il valore restval viene usato come valore predefinito. Se una riga letta ha più valori della sequenza fieldnames, i valori rimanenti vengono aggiunti come ad una sequenza, la cui chiave associata è restkey. Se una riga letta ha meno valori della sequenza fieldnames, le chiavi rimanenti acquisiscono il loro valore dal parametro facoltativo restval. Qualsiasi altro argomento facoltativo o a parola chiave viene passato alla sottostante istanza reader.

class DictWriter( csvfile, fieldnames[, restval=""[, extrasaction='raise'[, dialect='excel'[, *args, **kwds]]]])

Crea un oggetto che opera come un normale writer ma che mappa dizionari in righe di output. Il parametro fieldnames specifica l'ordine con il quale i valori del dizionario passato al metodo writerow() vengono scritti in csvfile. Il parametro facoltativo restval specifica il valore da scrivere se il dizionario non contiene una particolare chiave. Se il dizionario passato al metodo writerow() contiene una chiave non presente in fieldnames, il parametro facoltativo extrasaction indica l'azione da eseguire. Se viene impostato a 'raise' viene sollevata un'eccezione ValueError. Se viene impostato a 'ignore', i valori eccedenti vengono ignorati. Qualsiasi altro argomento facoltativo o a parola chiave viene passato alla sottostante istanza writer.

Notare che, diversamente da quanto accade per la classe DictReader, il parametro fieldnames di DictWriter non è facoltativo. Dato che i dizionari, dict, in Python non sono ordinati, risulta mancante l'informazione circa l'ordine con il quale la riga dovrebbe essere scritta in csvfile.

class Dialect: La classe Dialect è un contenitore importante principalmente per i sui attributi, che vengono utilizzati come parametri per una particolare istanza reader o writer.

class Sniffer( ): La classe Sniffer viene usata per dedurre il formato di un file CSV.

La classe Sniffer fornisce un solo metodo:

sniff( sample[,delimiters=None]): Analizza un dato sample e restituisce una sotto classe di Dialect che rispecchia i parametri trovati. Se il parametro facoltativo delimiters è presente, viene interpretato come stringa contenente i possibili caratteri separatori validi.

has_header( sample): Analizza un semplice testo, sample, (presupponendo che sia in formato CSV) e restituisce True se la prima riga sembra essere una serie di colonne di intestazioni.

Il modulo csv definisce le seguenti costanti:

QUOTE_ALL: Ordina agli oggetti writer di quotare tutti i campi.

QUOTE_MINIMAL: Ordina agli oggetti writer di quotare solo i campi che contengono il delimitatore, delimiter, corrente o quelli iniziano con quotechar, ovvero il carattere utilizzato per quotare il testo.

QUOTE_NONNUMERIC: Ordina agli oggetti writer di quotare tutti i campi che non contengono valori numerici.

QUOTE_NONE: Ordina agli oggetti writer di non quotare i campi. Quando il carattere delimiter corrente compare nei dati di output viene preceduto da escapechar, ovvero il carattere di protezione corrente. Quando è attiva QUOTE_NONE è un errore non definire un carattere singolo di protezione anche se nessun dato da scrivere contiene il carattere delimiter corrente.

Il modulo csv definisce la seguente eccezione:

exception Error: Viene sollevata quando viene rilevato un errore in una delle funzioni del modulo

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