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 オブジェクトを返します。 csvfilewrite メソッドを持つ任意のオブジェクトで かまいません。 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)
dialectname と関連付けます。 dialectcsv.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クラスとは違い、DictWriterfieldnames パラメータは省略可能ではありません。Pythonのdictオブジェクトは 整列されていないので、列がcsvfileに書かれるべき順序を推定するた めの十分な情報はありません。

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

クラス 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
全ての関数において、エラーが検出された際に送出される例外です。

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