# `csv` --- CSV ファイルの読み書き

ソースコード: Lib/csv.py

CSV (Comma Separated Values、カンマ区切り値列) と呼ばれる形式は、 スプレッドシートやデータベース間でのデータのインポートやエクスポートにおける最も一般的な形式です。 CSVフォーマットは、 RFC 4180 によって標準的な方法でフォーマットを記述する試みが行われる以前から長年使用されました。明確に定義された標準がないということは、異なるアプリケーション によって生成されたり取り込まれたりするデータ間では、しばしば微妙な違いが発生するということを意味します。こうした違いのために、複数のデータ源から得られた CSV ファイルを処理する作業が鬱陶しいものになることがあります。とはいえ、デリミタ (delimiter) やクオート文字の 相違はあっても、全体的な形式は十分似通っているため、こうしたデータを効率的に操作し、データの読み書きにおける細々としたことをプログラマ から隠蔽するような単一のモジュールを書くことは可能です。

The `csv` module implements classes to read and write tabular data in CSV format. It allows programmers to say, "write this data in the format preferred by Excel," or "read data from this file which was generated by Excel," without knowing the precise details of the CSV format used by Excel. Programmers can also describe the CSV formats understood by other applications or define their own special-purpose CSV formats.

The `csv` module's `reader` and `writer` objects read and write sequences. Programmers can also read and write data in dictionary form using the `DictReader` and `DictWriter` classes.

参考

PEP 305 - CSV File API

  Python へのこのモジュールの追加を提案している Python 改良案 (PEP: Python Enhancement Proposal)。

## モジュールコンテンツ

The `csv` module defines the following functions:

csv.reader(csvfile, /, dialect='excel', **fmtparams)

  Return a reader object that will process lines from the given csvfile. A csvfile must be an iterable of strings, each in the reader's defined csv format. A csvfile is most commonly a file-like object or list. If csvfile is a file object, it should be opened with `newline=''`. [1] An optional dialect parameter can be given which is used to define a set of parameters specific to a particular CSV dialect. It may be an instance of a subclass of the `Dialect` class or one of the strings returned by the `list_dialects()` function. The other optional fmtparams keyword arguments can be given to override individual formatting parameters in the current dialect. For full details about the dialect and formatting parameters, see section Dialect クラスと書式化パラメータ.

  csv ファイルから読み込まれた各行は、文字列のリストとして返されます。`QUOTE_NONNUMERIC` フォーマットオプションが指定された場合を除き、データ型の変換が自動的に行われることはありません (このオプションが指定された場合、クォートされていないフィールドは浮動小数点数に変換されます)。

  短い利用例:

      >>> import csv
      >>> with open('eggs.csv', newline='') as csvfile:
      ...     spamreader = csv.reader(csvfile, delimiter=' ', quotechar='|')
      ...     for row in spamreader:
      ...         print(', '.join(row))
      Spam, Spam, Spam, Spam, Spam, Baked Beans
      Spam, Lovely Spam, Wonderful Spam

csv.writer(csvfile, /, dialect='excel', **fmtparams)

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

  短い利用例:

      import csv
      with open('eggs.csv', 'w', newline='') as csvfile:
          spamwriter = csv.writer(csvfile, delimiter=' ',
                                  quotechar='|', quoting=csv.QUOTE_MINIMAL)
          spamwriter.writerow(['Spam'] * 5 + ['Baked Beans'])
          spamwriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])

csv.register_dialect(name, /, dialect='excel', **fmtparams)

  dialect を name と関連付けます。 name は文字列でなければなりません。表現形式(dialect)は `Dialect` のサブクラスを渡すか、またはキーワード引数 fmtparams 、もしくは両方で指定できますが、キーワード引数の方が優先されます。表現形式と書式化パラメータについての詳細は、 Dialect クラスと書式化パラメータ 節を参照してください。

csv.unregister_dialect(name)

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

csv.get_dialect(name)

  name に関連づけられた表現形式を返します。 name が表現形式名でない場合には `Error` を送出します。この関数は不変の `Dialect` を返します。

csv.list_dialects()

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

csv.field_size_limit()
csv.field_size_limit(new_limit)

  パーサが許容する現在の最大フィールドサイズを返します。 new_limit が渡されたときは、その値が新しい上限になります。

The `csv` module defines the following classes:

class csv.DictReader(f, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds)

  通常の reader のように動作しますが、個々の行の情報を `dict` にマップするオブジェクトを生成します。マップのキーは省略可能な fieldnames パラメータで与えられます。

  The fieldnames parameter is a sequence. If fieldnames is omitted, the values in the first row of file f will be used as the fieldnames and will be omitted from the results. If fieldnames is provided, they will be used and the first row will be included in the results. Regardless of how the fieldnames are determined, the dictionary preserves their original ordering.

  行がフィールド名より多くのフィールドを持っていた場合、残りのデータはリストに入れられて、 restkey により指定されたフィールド名 (デフォルトでは `None`) で保存されます。空白でない行がフィールド名よりも少ないフィールドしか持たない場合、足りない値は restval の値 (デフォルトは `None` ) によって埋められます。

  その他の省略可能またはキーワード形式のパラメータは、ベースになっている `reader` インスタンスに渡されます。

  fieldnames に渡された引数がイテレータの場合、 `list` に変換されます。

  バージョン 3.6 で変更: 返される行の型は `OrderedDict` になりました。

  バージョン 3.8 で変更: 返される行の型は `dict` になりました。

  短い利用例:

      >>> import csv
      >>> with open('names.csv', newline='') as csvfile:
      ...     reader = csv.DictReader(csvfile)
      ...     for row in reader:
      ...         print(row['first_name'], row['last_name'])
      ...
      Eric Idle
      John Cleese

      >>> print(row)
      {'first_name': 'John', 'last_name': 'Cleese'}

class csv.DictWriter(f, fieldnames, restval='', extrasaction='raise', dialect='excel', *args, **kwds)

  通常の writer のように動作しますが、辞書を出力行にマップするオブジェクトを生成します。 fieldnames パラメータは、`writerow()` メソッドに渡された辞書の値がどのような順番でファイル f に書かれるかを指定するキーの `sequence` です。 `writerow()` メソッドに渡された辞書に fieldnames には存在しないキーが含まれている場合、オプションの extrasaction パラメータによってどんな動作を行うかが指定されます。この値がデフォルト値である `'raise'` に設定されている場合、 `ValueError` が送出されます。 `'ignore'` に設定されている場合、辞書の余分な値は無視されます。その他のパラメータはベースになっている `writer` インスタンスに渡されます。

  `DictReader` クラスとは異なり、 `DictWriter` の fieldnames パラメータは省略可能ではありません。

  fieldnames に渡された引数がイテレータの場合、 `list` に変換されます。

  短い利用例:

      import csv

      with open('names.csv', 'w', newline='') as csvfile:
          fieldnames = ['first_name', 'last_name']
          writer = csv.DictWriter(csvfile, fieldnames=fieldnames)

          writer.writeheader()
          writer.writerow({'first_name': 'Baked', 'last_name': 'Beans'})
          writer.writerow({'first_name': 'Lovely', 'last_name': 'Spam'})
          writer.writerow({'first_name': 'Wonderful', 'last_name': 'Spam'})

class csv.Dialect

  `Dialect` クラスはコンテナクラスです。その属性に、ダブルクォート、空白文字、デリミタなどの扱い方に関する情報を含みます。CSV には厳密な規格がないため、アプリケーションによって生成される CSV データはそれぞれ僅かに異なります。 `Dialect` クラスのインスタンスは `reader` と `writer` のインスタンスの挙動を定義します。

  All available `Dialect` names are returned by `list_dialects()`, and they can be registered with specific `reader` and `writer` classes through their initializer (`__init__`) functions like this:

      import csv

      with open('students.csv', 'w', newline='') as csvfile:
          writer = csv.writer(csvfile, dialect='unix')

class csv.excel

  `excel` クラスは Excel で生成される CSV ファイルの通常のプロパティを定義します。これは `'excel'` という名前の dialect として登録されています。

class csv.excel_tab

  `excel_tab` クラスは Excel で生成されるタブ分割ファイルの通常のプロパティを定義します。これは `'excel-tab'` という名前の dialect として登録されています。

class csv.unix_dialect

  `unix_dialect` クラスは UNIX システムで生成される CSV ファイルの通常のプロパティ (行終端記号として `'\n'` を用い全てのフィールドをクォートするもの) を定義します。これは `'unix'` という名前の dialect として登録されています。

  Added in version 3.2.

class csv.Sniffer

  `Sniffer` クラスは CSV ファイルの書式を推理するために用いられるクラスです。

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

  sniff(sample, delimiters=None)

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

  has_header(sample)

    Analyze the sample text (presumed to be in CSV format) and return `True` if the first row appears to be a series of column headers. Inspecting each column, one of two key criteria will be considered to estimate if the sample contains a header:

    - 2番目からn番目の行は数値を含みます。

    - the second through n-th rows contain strings where at least one value's length differs from that of the putative header of that column.

    Twenty-one rows after the header are sampled; if more than half of the columns + rows meet the criteria, `True` is returned.

  注釈

  このメソッドは大雑把なヒューリスティックであり、結果が偽陽性や偽陰性である可能性があります。

`Sniffer` の利用例:

    with open('example.csv', newline='') as csvfile:
        dialect = csv.Sniffer().sniff(csvfile.read(1024))
        csvfile.seek(0)
        reader = csv.reader(csvfile, dialect)
        # ... process CSV file contents here ...

The `csv` module defines the following constants:

csv.QUOTE_ALL

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

csv.QUOTE_MINIMAL

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

csv.QUOTE_NONNUMERIC

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

  `reader` オブジェクトに、クォーテーションで囲まれていないすべてのフィールドを `float` 型に変換するよう指示します。

  注釈

  Some numeric types, such as `bool`, `Fraction`, or `IntEnum`, have a string representation that cannot be converted to `float`. They cannot be read in the `QUOTE_NONNUMERIC` and `QUOTE_STRINGS` modes.

csv.QUOTE_NONE

  Instructs `writer` objects to never quote fields. When the current delimiter, quotechar, escapechar, `'\r'`, `'\n'` or any of the characters in lineterminator occurs in output data it is preceded by the current escapechar character. If escapechar is not set, the writer will raise `Error` if any characters that require escaping are encountered. Set quotechar to `None` to prevent its escaping.

  `reader` オブジェクトに、クオート文字に対する特殊処理を行わないよう指示します。

csv.QUOTE_NOTNULL

  Instructs `writer` objects to quote all fields which are not `None`. This is similar to `QUOTE_ALL`, except that if a field value is `None` an empty (unquoted) string is written.

  Instructs `reader` objects to interpret an empty (unquoted) field as `None` and to otherwise behave as `QUOTE_ALL`.

  Added in version 3.12.

csv.QUOTE_STRINGS

  Instructs `writer` objects to always place quotes around fields which are strings. This is similar to `QUOTE_NONNUMERIC`, except that if a field value is `None` an empty (unquoted) string is written.

  Instructs `reader` objects to interpret an empty (unquoted) string as `None` and to otherwise behave as `QUOTE_NONNUMERIC`.

  Added in version 3.12.

The `csv` module defines the following exception:

exception csv.Error

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

## Dialect クラスと書式化パラメータ

To make it easier to specify the format of input and output records, specific formatting parameters are grouped together into dialects. A dialect is a subclass of the `Dialect` class containing various attributes describing the format of the CSV file. When creating `reader` or `writer` objects, the programmer can specify a string or a subclass of the `Dialect` class as the dialect parameter. In addition to, or instead of, the dialect parameter, the programmer can also specify individual formatting parameters, which have the same names as the attributes defined below for the `Dialect` class.

Dialect は以下の属性をサポートしています:

Dialect.delimiter

  フィールド間を分割するのに用いられる 1 文字からなる文字列です。デフォルトでは `','` です。

Dialect.doublequote

  フィールド内に現れた quotechar のインスタンスで、クオートではないその文字自身でなければならない文字をどのようにクオートするかを制御します。 `True` の場合、この文字は二重化されます。 `False` の場合、 escapechar は quotechar の前に置かれます。デフォルトでは `True` です。

  出力においては、 doublequote が `False` で escapechar がセットされていない場合、フィールド内に quotechar が現れると `Error` が送出されます。

Dialect.escapechar

  A one-character string used by the writer to escape characters that require escaping:

  > - the delimiter, the quotechar, `'\r'`, `'\n'` and any of the characters in lineterminator are escaped if quoting is set to `QUOTE_NONE`;

  > - the quotechar is escaped if doublequote is `False`;

  > - the escapechar itself.

  On reading, the escapechar removes any special meaning from the following character. It defaults to `None`, which disables escaping.

  バージョン 3.11 で変更: 空の escapechar は許可されていません。

Dialect.lineterminator

  `writer` が作り出す各行を終端する際に用いられる文字列です。デフォルトでは `'\r\n'` です。

  注釈

  `reader` は `'\r'` または `'\n'` のどちらかを行末と認識するようにハードコードされており、 lineterminator を無視します。この振る舞いは将来変更されるかもしれません。

Dialect.quotechar

  A one-character string used to quote fields containing special characters, such as the delimiter or the quotechar, or which contain new-line characters (`'\r'`, `'\n'` or any of the characters in lineterminator). It defaults to `'"'`. Can be set to `None` to prevent escaping `'"'` if quoting is set to `QUOTE_NONE`.

  バージョン 3.11 で変更: 空の quotechar は許可されていません。

Dialect.quoting

  Controls when quotes should be generated by the writer and recognised by the reader. It can take on any of the QUOTE_* constants and defaults to `QUOTE_MINIMAL` if quotechar is not `None`, and `QUOTE_NONE` otherwise.

Dialect.skipinitialspace

  When `True`, spaces immediately following the delimiter are ignored. The default is `False`. When combining `delimiter=' '` with `skipinitialspace=True`, unquoted empty fields are not allowed.

Dialect.strict

  `True` の場合、 不正な CSV 入力に対して `Error` を送出します。デフォルトでは `False` です。

## reader オブジェクト

reader オブジェクト(`DictReader` インスタンス、および `reader()` 関数によって返されたオブジェクト) は、以下の public なメソッドを持っています:

csvreader.__next__()

  reader の反復可能なオブジェクトから、現在の表現形式 (`Dialect`) に基づいて次の行を解析してリスト（オブジェクトが `reader()` から返された場合）または辞書 （ `DictReader` のインスタンスの場合）として返します。通常は `next(reader)` のようにして呼び出すことになります。

reader オブジェクトには以下の公開属性があります:

csvreader.dialect

  パーサで使われる表現形式の読み出し専用の記述です。

csvreader.line_num

  ソースイテレータから読んだ行数です。この数は返されるレコードの数とは、レコードが複数行に亘ることがあるので、一致しません。

DictReader オブジェクトは、以下の public な属性を持っています:

DictReader.fieldnames

  オブジェクトを生成するときに渡されなかった場合、この属性は最初のアクセス時か、ファイルから最初のレコードを読み出したときに初期化されます。

## writer オブジェクト

`writer` オブジェクト(`DictWriter` インスタンス、および `writer()` 関数によって返されたオブジェクト) は、以下の public なメソッドを持っています: row には、 `writer` オブジェクトの場合には文字列か数値のイテラブルを指定し、 `DictWriter` オブジェクトの場合はフィールド名をキーとして対応する文字列か数値を格納した辞書オブジェクトを指定します(数値は `str()` で変換されます)。複素数を出力する場合、値をかっこで囲んで出力します。このため、CSV ファイルを読み込むアプリケーションで（そのアプリケーションが複素数をサポートしていたとしても）問題が発生する場合があります。

csvwriter.writerow(row, /)

  現在の表現形式 (`Dialect`.)に沿ってフォーマットされた row パラメータを writer のファイルオブジェクトに書き込みます。ファイルオブジェクトの write メソッドを呼び出した際の戻り値を返します。

  バージョン 3.5 で変更: 任意のイテラブルのサポートの追加。

csvwriter.writerows(rows, /)

  rows 引数 (上で解説した row オブジェクトのイテラブル) の全ての要素を現在の表現形式に基づいて書式化し、writer のファイルオブジェクトに書き込みます。

writer オブジェクトには以下の公開属性があります:

csvwriter.dialect

  writer で使われる表現形式の読み出し専用の記述です。

DictWriter のオブジェクトは以下の public メソッドを持っています:

DictWriter.writeheader()

  Write a row with the field names (as specified in the constructor) to the writer's file object, formatted according to the current dialect. Return the return value of the `csvwriter.writerow()` call used internally.

  Added in version 3.2.

  バージョン 3.8 で変更: `writeheader()` は内部的に利用している `csvwriter.writerow()` メソッドの返り値を返すようになりました。

## 使用例

最も簡単な CSV ファイル読み込みの例です:

    import csv
    with open('some.csv', newline='') as f:
        reader = csv.reader(f)
        for row in reader:
            print(row)

別の書式での読み込み:

    import csv
    with open('passwd', newline='') as f:
        reader = csv.reader(f, delimiter=':', quoting=csv.QUOTE_NONE)
        for row in reader:
            print(row)

上に対して、単純な書き込みのプログラム例は以下のようになります。

    import csv
    with open('some.csv', 'w', newline='') as f:
        writer = csv.writer(f)
        writer.writerows(someiterable)

`open()` が CSV ファイルの読み込みに使われるため、ファイルはデフォルトではシステムのデフォルトエンコーディングでユニコード文字列にデコードされます (`locale.getencoding()` を参照)。他のエンコーディングを用いてデコードするには、open の引数 `encoding` を設定して、以下のようにします:

    import csv
    with open('some.csv', newline='', encoding='utf-8') as f:
        reader = csv.reader(f)
        for row in reader:
            print(row)

システムのデフォルトエンコーディング以外で書き込む場合も同様です。出力ファイルを開く際に引数 `encoding` を明示してください。

新しい表現形式の登録:

    import csv
    csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
    with open('passwd', newline='') as f:
        reader = csv.reader(f, 'unixpwd')

もう少し手の込んだ reader の使い方 --- エラーを捉えてレポートします。

    import csv, sys
    filename = 'some.csv'
    with open(filename, newline='') as f:
        reader = csv.reader(f)
        try:
            for row in reader:
                print(row)
        except csv.Error as e:
            sys.exit(f'file {filename}, line {reader.line_num}: {e}')

このモジュールは文字列の解析は直接サポートしませんが、簡単にできます。

    import csv
    for row in csv.reader(['one,two,three']):
        print(row)

脚注

[1] (1,2)

If `newline=''` is not specified, newlines embedded inside quoted fields will not be interpreted correctly, and on platforms that use `\r\n` line endings on write an extra `\r` will be added. It should always be safe to specify `newline=''`, since the csv module does its own (universal) newline handling.