The csv
module provide tools for working with and manipulating csv(comma separated values) files.
csv files are used to store tabular data in plain text formats. csv data consists of records and each record is made up of fields. Normally, a line in a csv file represents a single record while fields in a record are separated by commas.
The following is an example of csv data.
first_name,last_name,age,gender
John,Main,30,male
Jane,Doe,24,female
Morrison,Smith,22,male
Brian,Gates,32,male
Mary,Reagan,25,female
Typically, files with a .csv
extension are normally associated with csv data.
Reading csv data
To read data from a csv file, use the reader()
function. The function has the following basic syntax:
csv.reader(iterable)
The reader()
function takes any iterable that yields a line during each iteration. This can be a file object, a list or any other iterable made of lines. It returns an iterator of lists, where each list represents a record in the csv data.
Consider if the previous csv data exists in a file called demo.csv
.
['first_name', 'last_name', 'age', 'gender']
['John', 'Main', '30', 'male']
['Jane', 'Doe', '24', 'female']
['Morrison', 'Smith', '22', 'male']
['Brian', 'Gates', '32', 'male']
['Mary', 'Reagan', '25', 'female']
In the above example, we used data stored in a file object but as earlier mentioned, you can literally use any iterable. In the following example, we use a list instead of a file object.
['first_name', 'last_name', 'age', 'gender']
['John', 'Main', '30', 'male']
['Jane', 'Doe', '24', 'female']
['Morrison', 'Smith', '22', 'male']
['Brian', 'Gates', '32', 'male']
['Mary', 'Reagan', '25', 'female']
Writing csv data
The writer()
function creates an object for writing csv data. It has the following basic syntax:
csv.writer(fileobj)
Where the fileobj
is the opened file where the csv data will be written to.
After creating the writer object, we can then use writerow()
method to write a single record into the file or writerows()
to write multiple rows at once.
Note that in the above example, we opened the demo.csv
file with the "a"
mode. This ensures that the new rows are appended to the file, if we had used the "w"
mode instead, the existing rows would have been overwritten.
first_name,last_name,age,gender
John,Main,30,male
Jane,Doe,24,female
Morrison,Smith,22,male
Brian,Gates,32,male
Mary,Reagan,25,female
Ruth,Miller,24,female
Brandy,Jones,22,male
As you can see above, the new records have been added successfully.
To add multiple rows at once, use the writer.writerows()
method.
Quoting behavior
In cases where you want records of certain types to be stored in quotes, you can specify the quoting
flag when creating the writer
object. For example, if you want string items to be in quotes but numeric values not to be, you can specify the quoting parameter as csv.QUOTE_NONNUMERIC
.
If you open the demo.csv
file, you will see that in the written records , string fields are quoted.
"Stephen","King",32,"male"
"Molly","Jones",22,"female"
All the quoting options are as shown in the following table:
QUOTE_ALL |
Quote any field regardless of type |
QUOTE_NONE |
Don't quote any field. |
QUOTE_MINIMAL |
Quote only fields containing some special characters. This is the default quoting behavior. |
QUOTE_NONNUMERIC |
Quote all fields except those with numeric values like integers and floats. |
csv dialects
Separating csv fields with a comma is just the popular convention, there is really no well defined standard on csv format. For example, you could as well separate the fields with spaces instead of commas. This means that any csv parser needs to be very flexible when dealing with csv delimiters.
Dialects allow us to specify to the parser the delimiter and other important parameters that will be used when parsing the csv files. The csv.list_dialects()
function returns a list of the registered dialects.
['excel', 'excel-tab', 'unix']
The default dialect is excel
, in which the fields are delimited with commas.
If for example, you have csv data in which the fields are delimited by a pipe character "|"
or any other character instead of a comma, as shown below:
first_name|last_name|age|gender
John|Main|30|male
Jane|Doe|24|female
Morrison|Smith|22|male
Brian|Gates|32|male
Mary|Reagan|25|female
You can register a new dialect using the csv.register_dialect()
. You can then use the registered dialect with reader
and writer
objects.
Apart from delimiter
, you can specify other dialect parameters depending on the nature of your csv data. The supported parameters are shown in the following tables:
parameter | default value | description |
---|---|---|
delimiter |
, |
Field separator. |
quotechar |
" |
The character to enclose fields where quoting is allowed. |
lineterminator |
\r \n |
The string/character used to terminate a line |
doublequote |
True |
Whether quotchar parameters are doubled. |
escapechar |
None |
Character used to indicate an escape sequence |
skipintialspace |
False |
Ignore whitespace after the delimiter |
Automatic dialect detection
In cases where the csv format is not well known, we can use the csv.Sniffer
class, which automatically constructs a dialect object given a sample of csv data.
Consider if we have the following csv data.
first_name&last_name&age&gender
John&Main&30&male
Jane&Doe&24&female
Morrison&Smith&22&male
Brian&Gates&32&male
Mary&Reagan&25&female
In the above example, we used the "&"
character as the delimiter.
As you can see, the sniffer correctly detected that "&"
is used as the delimiter character. However, you should keep in mind that the sniffer is not always correct, it can only be said to be making educated guesses.
Using named fields
You can use csv.DictReader
and csv.DictWriter
classes to use named fields when reading or writing csv data.
The two classes allows you to specify in advance a list of field names to alias the fields in the csv data.
csv.DictReader
The DictReader
class allows you to read rows with the fields having an alias name.
Consider the following example:
Iterating through the DictReader
object will yield a list of dictionaries, where each dictionary represents a row in the csv data.
csv.DictWriter
DictWriter
objects writes data into a csv file with argument given as dictionaries. Consider the following example:
As shown above, when using named fields, the order is not important as long as the field names are correct.
Stephen,King,32,male
Molly,Jones,22,female