Python Reference ยท Files, Paths and Text I/O
The csv module
Reference for Python's csv module: reader, writer, DictReader, DictWriter, delimiters, quoting rules, newline='' and common CSV pitfalls.
CSV (comma-separated values) looks simple, but real files contain commas inside values, quotes, line breaks inside cells and different delimiters. The csv module handles all of that for you, so you should not split lines on "," yourself.
It offers four main tools: csv.reader and csv.writer work with lists of strings, csv.DictReader and csv.DictWriter work with dictionaries keyed by column name. All of them wrap a file object (or any iterable of lines).
import csv with open("people.csv", newline="", encoding="utf-8") as f: for row in csv.reader(f): print(row)
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Syntax
csv.reader(csvfile, dialect="excel", **fmtparams) csv.writer(csvfile, dialect="excel", **fmtparams) csv.DictReader(f, fieldnames=None, restkey=None, restval=None, dialect="excel", **fmtparams) csv.DictWriter(f, fieldnames, restval="", extrasaction="raise", dialect="excel", **fmtparams)
| Name | Description |
|---|---|
csvfile / f |
A file opened with newline="", or any iterable of strings (reader) or object with write() (writer). |
delimiter |
Single character between fields; default ",". Use "\t" for TSV or ";" for many European exports. |
quotechar |
Character that wraps fields containing special characters; default '"'. |
quoting |
csv.QUOTE_MINIMAL (default), QUOTE_ALL, QUOTE_NONNUMERIC, QUOTE_NONE. |
lineterminator |
Row ending written by writers; default "\r\n". |
fieldnames |
Column names for the dict classes. DictReader takes them from the first row if omitted. |
extrasaction |
DictWriter: "raise" (default) or "ignore" for dictionary keys not in fieldnames. |
Writer methods: writerow(row), writerows(rows); DictWriter also has writeheader().
Return value: a reader yields one list of strings per row (a dict for DictReader; a plain dict since Python 3.8). A writer's writerow() returns what the underlying write() returned.
Raises: csv.Error for malformed input or bad arguments, ValueError from DictWriter for unknown keys, TypeError for invalid dialect parameters.
Usage notes
- Open files with
newline="". The module handles line endings itself. Without it, quoted cells containing newlines can break on read, and on Windows every row may get an extra blank line on write. - Everything is a string when reading. Convert numbers and dates yourself (
int(row["stock"])).QUOTE_NONNUMERICmakes the reader convert unquoted values tofloat, but explicit conversion is clearer. - Writing converts with
str().Nonebecomes an empty string, numbers become text, andQUOTE_NONNUMERICquotes only non-numbers. - Empty lines read as an empty list
[]withcsv.reader, butDictReaderskips them. - Short and long rows.
DictReaderfills missing values withrestval(defaultNone) and stores extra values as a list underrestkey(defaultNone). - Encoding. Pass
encoding="utf-8". For files exported from Excel with a byte-order mark, use"utf-8-sig". - Detecting formats.
csv.Sniffer().sniff(sample)can guess the delimiter, but it can be wrong; if you know the format, state it. - Large files. Readers are lazy, so a loop uses little memory.
list(reader)loads everything. - When to use something else. For analysis,
pandas.read_csv()is far more powerful. For nested data, JSON is a better fit.