12.20.1 モジュールの内容

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

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

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

register_dialect( name, dialect): dialect を name と関連付けます。 dialect は csv.Dialect のサブクラスでなければなりません。 name は文字列か Unicode オブジェクトでなければなりません。

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

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

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

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 のインスタンスに渡されます。

+Note that unlike the DictReader class, the fieldnames +parameter of the DictWriter is not optional. Since Python's +dict objects are not ordered, there is not enough information +available to deduce the order in which the row should be written to the +csvfile.

DictReaderクラスとは違い、DictWriterのfieldnames パラメータは省略可能ではありません。Pythonのdictオブジェクトは整列されていないので、列がcsvfileに書かれるべき順序を推定するための十分な情報はありません。

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

クラス 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 で始まるフィールドだけをクオートするように指示します。

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

QUOTE_NONE: writer オブジェクトに対し、フィールドを決してクオートしないように指示します。現在の delimiter が出力データ中に現れた場合、現在設定されている excapechar 文字が前に付けられます。 QUOTE_NONE の効果下にある時には、1 文字からなる文字列 escapechar が定義されていないと、たとえ書き出されるデータ中に delimiter 文字が入っていなくてもエラーになります。

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

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

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