9.1.1 モジュールの内容

csv モジュールでは以下の関数を定義しています:

reader( csvfile[, dialect='excel'][, fmtparam])

与えられた csvfile 内の行を反復処理するような reader オブジェクトを返します。csvfile はイテレータプロトコルをサポートし、next メソッドが呼ばれた際に常に文字列を返すような任意のオブジェクトにすることができます -- ファイルオブジェクトでもリストでも構いません。 csvfile がファイルオブジェクトの場合、ファイルオブジェクトの形式に違いがあるようなプラットフォームでは 'b' フラグを付けて開かなければなりません。オプションとして dialect パラメタを与えることができ、特定の CSV 表現形式 (dialect) 特有のパラメタの集合を定義するために使われます。dialect パラメタは Dialect クラスのサブクラスのインスタンスか、list_dialects 関数が返す文字列の一つにすることができます。別のオプションである fmtparam キーワード引数は、現在の表現形式における個々の書式パラメタを上書きするために与えることができます。表現形式および書式化パラメタの詳細については、 9.1.2 節、 ``Dialect クラスと書式化パラメタ'' を参照してください。

読み出されたデータは全て文字列として返されます。データ型の変換が自動的に行われることはありません。

バージョン 2.5 で変更された仕様: パーサが複数行に亘るクオートされたフィールドに関して厳格になりました。以前は、クオートされたフィールドの中で終端の改行文字無しに行が終わった場合、返されるフィールドには改行が挿入されていましたが、この振る舞いはフールドの中に復帰文字を含むようなファイルを読むときに問題を起こしていました。そこでフィールドに改行文字を挿入せずに返すように改められました。この結果、フィールドに埋め込まれた改行文字が重要ならば、入力は改行文字を保存するような仕方で複数行に分割されなければなりません。

writer( csvfile[, dialect='excel'][, fmtparam]): ユーザが与えたデータをデリミタで区切られた文字列に変換し、与えられたファイルオブジェクトにするための writer オブジェクトを返します。 csvfile は write メソッドを持つ任意のオブジェクトでかまいません。 csvfile がファイルオブジェクトの場合、ファイルオブジェクトの形式に違いがあるようなプラットフォームでは 'b' フラグを付けて開かなければなりません。オプションとして dialect パラメタを与えることができ、特定の CSV 表現形式 (dialect) 特有のパラメタの集合を定義するために使われます。dialect パラメタは Dialect クラスのサブクラスのインスタンスか、list_dialects 関数が返す文字列の一つにすることができます。別のオプションである fmtparam キーワード引数は、現在の表現形式における個々の書式パラメタを上書きするために与えることができます。表現形式および書式化パラメタの詳細については、 9.1.2 節、 ``Dialect クラスと書式化パラメタ'' を参照してください。 DB API を実装するモジュールとのインタフェースを可能な限り容易にするために、None は空文字列として書き込まれます。この処理は可逆な変換ではありませんが、SQL で NULL データ値を CSV にダンプする処理を、cursor.fetch*() 呼び出しによって返されたデータを前処理することなく簡単に行うことができます。他の非文字データは、書き出される前に str() を使って文字列に変換されます。

register_dialect( name[, dialect][, fmtparam]): dialect を name と関連付けます。name は文字列か Unicode オブジェクトでなければなりません。表現形式(dialect)は Dialect のサブクラスを渡すか、またはキーワード引数 fmtparam、もしくは両方で指定できますが、キーワード引数の方が優先されます。表現形式と書式化パラメタについてより詳しいことは 9.1.2節「Dialect クラスと書式化パラメタ」を参照してください。

unregister_dialect( name): name に関連づけられた表現形式を表現形式レジストリから削除します。 name が表現形式名でない場合には Error を送出します。

get_dialect( name): name に関連づけられた表現形式を返します。 name が表現形式名でない場合には Error を送出します。

list_dialects( ): 登録されている全ての表現形式を返します。

field_size_limit( [new_limit]): パーサが許容する現在の最大フィールドサイズを返します。 new_limit が渡されたときは、その値が新しい上限になります。バージョン 2.5 で新たに追加された仕様です。

csv モジュールでは以下のクラスを定義しています:

クラス DictReader( csvfile[, fieldnames=None,[, restkey=None[, restval=None[, dialect='excel'[, *args, **kwds]]]]]): 省略可能なfieldnames パラメタで与えられたキーを読み出された情報に対応付ける他は正規の reader のように動作するオブジェクトを生成します。 fieldnamesパラメタが無い場合には、csvfileの最初の行の値がフィールド名として利用されます。読み出された行が fieldnames のシーケンスよりも多くのフィールドを持っていた場合、残りのフィールドデータは restkey の値をキーとするシーケンスに追加されます。読み出された行が fieldnames のシーケンスよりも少ないフィールドしか持たない場合、残りのキーはオプションの restval パラメタに指定された値を取ります。その他の省略可能またはキーワード形式のパラメタはベースになっている reader のインスタンスに渡されます。

クラス DictWriter( csvfile, fieldnames[, restval=""[, extrasaction='raise'[, dialect='excel'[, *args, **kwds]]]]): 辞書を出力行に対応付ける他は正規の writer のように動作するオブジェクトを生成します。fieldnames パラメタには、辞書中の writerow() メソッドに渡される値がどの順番で csvfile に書き出されるかを指定します。オプションの restval パラメタは、fieldnames 内のキーが辞書中にない場合に書き出される値を指定します。 writerow() メソッドに渡された辞書に、 fieldnames 内には存在しないキーが入っている場合、オプションの extraaction パラメタでどのような動作を行うかを指定します。この値が 'raise' に設定されている場合 ValueError が送出されます。 'ignore' に設定されている場合、辞書の余分の値は無視されます。その他のパラメタはベースになっている writer のインスタンスに渡されます。
DictReaderクラスとは違い、DictWriterのfieldnames パラメータは省略可能ではありません。Pythonのdictオブジェクトは整列されていないので、列がcsvfileに書かれるべき順序を推定するための十分な情報はありません。

class Dialect: Dialect クラスはコンテナクラスで、基本的な用途としては、その属性を特定の reader や writer インスタンスのパラメタを定義するために用います。

クラス excel( ): excel クラスは Excel で生成される CSV ファイルの通常のプロパティを定義します。

クラス excel_tab( ): excel クラスは Excel で生成されるタブ分割ファイルの通常のプロパティを定義します。

クラス Sniffer( [sample=16384]): Sniffer クラスは CSV ファイルの書式を推理するために用いられるクラスです。

Sniffer クラスではメソッドを二つ提供しています:

sniff( fileobj): 与えられた sample を解析し、発見されたパラメタを反映した Dialect サブクラスを返します。オプションの delimiters パラメタを与えた場合、有効なデリミタ文字を含んでいるはずの文字列として解釈されます。

has_header( sample): (CSV 形式と仮定される) サンプルテキストを解析して、最初の行がカラムヘッダの羅列のように推察される場合 True を返します。

csv モジュールでは以下の定数を定義しています:

QUOTE_ALL: writer オブジェクトに対し、全てのフィールドをクオートするように指示します。

QUOTE_MINIMAL: writer オブジェクトに対し、delimiter、quotechar または lineterminator に含まれる任意の文字のような特別な文字を含むフィールドだけをクオートするように指示します。

QUOTE_NONNUMERIC: writer オブジェクトに対し、全ての非数値フィールドをクオートするように指示します。
reader に対しては、クオートされていない全てのフィールドを float 型に変換するよう指示します。

QUOTE_NONE: writer オブジェクトに対し、フィールドを決してクオートしないように指示します。現在の delimiter が出力データ中に現れた場合、現在設定されている escapechar 文字が前に付けられます。 escapechar がセットされていない場合、エスケープが必要な文字に遭遇した writer は Error を送出します。
reader に対しては、クオート文字の特別扱いをしないように指示します。

csv モジュールでは以下の例外を定義しています:

exception Error: 全ての関数において、エラーが検出された際に送出される例外です。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。