< Previous
Next >

Writing CSV Files in Python

CSV (Comma-Separated Values) files are a common way of storing and exchanging tabular data. Python’s csv module makes it easy to write data to CSV files. Whether you're exporting data for reporting, sharing datasets, or saving results from your program, understanding how to write to CSV files is essential.

In this guide, we will cover:

  • What is a CSV file?
  • How to write data to CSV files using Python
    • Writing simple CSV files
    • Writing CSV files with headers
    • Writing data with custom delimiters
  • Writing CSV files with different data types
  • Handling special characters and encoding
  • Best practices for writing CSV files

What is a CSV File?

A CSV file is a plain-text file used to store tabular data. Each row in the file represents a record, and the values are separated by commas (or other delimiters). A simple CSV file might look like this:

Name, Age, Occupation
John, 28, Software Engineer
Jane, 34, Data Scientist
Doe, 45, Project Manager
  • The first line is the header, which contains the column names.
  • Each subsequent line represents an entry or record in the table.

How to Write Data to CSV Files Using Python

Python provides several ways to write data to CSV files, primarily through the csv.writer() and csv.DictWriter() classes. Let's explore these methods in detail.

1. Writing Simple CSV Files with csv.writer()

The csv.writer() function allows you to write rows of data to a CSV file. You can write data as lists of values, where each list corresponds to a row in the CSV file.

Example: Writing Simple CSV Data

import csv

# Data to write
data = [
    ['Name', 'Age', 'Occupation'],
    ['John', 28, 'Software Engineer'],
    ['Jane', 34, 'Data Scientist'],
    ['Doe', 45, 'Project Manager']
]

# Open the file in write mode
with open('output.csv', 'w', newline='') as file:
    writer = csv.writer(file)
    
    # Write each row of data to the CSV file
    writer.writerows(data)

Explanation:

  • csv.writer(file) creates a writer object for the file.
  • writer.writerows(data) writes a list of rows (each row is itself a list of values).
  • The newline='' parameter is used to ensure that there are no extra blank lines between rows, especially on Windows systems.

Output (output.csv):

Name,Age,Occupation
John,28,Software Engineer
Jane,34,Data Scientist
Doe,45,Project Manager

2. Writing CSV Files with Headers Using csv.DictWriter()

If you want to write data to a CSV file using dictionaries (where keys are column names), you can use csv.DictWriter(). This is particularly useful when dealing with structured data.

Example: Writing CSV with Headers Using DictWriter

import csv

# Data to write as a list of dictionaries
data = [
    {'Name': 'John', 'Age': 28, 'Occupation': 'Software Engineer'},
    {'Name': 'Jane', 'Age': 34, 'Occupation': 'Data Scientist'},
    {'Name': 'Doe', 'Age': 45, 'Occupation': 'Project Manager'}
]

# Open the file in write mode
with open('output_with_header.csv', 'w', newline='') as file:
    # Define the fieldnames (column names)
    fieldnames = ['Name', 'Age', 'Occupation']
    
    # Create a DictWriter object
    writer = csv.DictWriter(file, fieldnames=fieldnames)
    
    # Write the header (column names)
    writer.writeheader()
    
    # Write the rows (data)
    writer.writerows(data)

Explanation:

  • csv.DictWriter(file, fieldnames=fieldnames) creates a writer object that expects dictionaries with keys corresponding to the column names.
  • writer.writeheader() writes the column headers to the CSV file.
  • writer.writerows(data) writes each dictionary in the data list to the CSV file.

Output (output_with_header.csv):

Name,Age,Occupation
John,28,Software Engineer
Jane,34,Data Scientist
Doe,45,Project Manager

3. Writing Data with Custom Delimiters

By default, the csv.writer() and csv.DictWriter() functions use a comma (,) as the delimiter between values. However, you can specify a custom delimiter if your CSV file uses a different character, such as a semicolon (;).

Example: Writing CSV with a Semicolon as the Delimiter

import csv

# Data to write
data = [
    ['Name', 'Age', 'Occupation'],
    ['John', 28, 'Software Engineer'],
    ['Jane', 34, 'Data Scientist'],
    ['Doe', 45, 'Project Manager']
]

# Open the file in write mode with a semicolon delimiter
with open('semicolon_output.csv', 'w', newline='') as file:
    writer = csv.writer(file, delimiter=';')
    
    # Write each row to the CSV file
    writer.writerows(data)

Output (semicolon_output.csv):

Name;Age;Occupation
John;28;Software Engineer
Jane;34;Data Scientist
Doe;45;Project Manager

In this example, we specify delimiter=';' to write the CSV file with a semicolon as the delimiter.

Writing CSV Files with Different Data Types

In Python, CSV files are text-based, so all data written to a CSV file will be converted to strings. If you need to write numbers, dates, or other data types, you can use Python’s str() function to explicitly convert the data to a string before writing.

Example: Writing CSV with Mixed Data Types

import csv
import datetime

# Data with mixed data types (string, integer, datetime)
data = [
    {'Name': 'John', 'Age': 28, 'Occupation': 'Software Engineer', 'Start Date': datetime.date(2020, 5, 1)},
    {'Name': 'Jane', 'Age': 34, 'Occupation': 'Data Scientist', 'Start Date': datetime.date(2019, 8, 15)},
    {'Name': 'Doe', 'Age': 45, 'Occupation': 'Project Manager', 'Start Date': datetime.date(2015, 3, 23)}
]

# Open the file in write mode
with open('mixed_data.csv', 'w', newline='') as file:
    fieldnames = ['Name', 'Age', 'Occupation', 'Start Date']
    writer = csv.DictWriter(file, fieldnames=fieldnames)
    
    # Write the header
    writer.writeheader()
    
    # Write each row, ensuring the date is formatted as a string
    for row in data:
        row['Start Date'] = row['Start Date'].strftime('%Y-%m-%d')  # Convert date to string
        writer.writerow(row)

Explanation:

  • We convert the Start Date from a datetime.date object to a string using the strftime() method, so it can be written to the CSV file.

Output (mixed_data.csv):

Name,Age,Occupation,Start Date
John,28,Software Engineer,2020-05-01
Jane,34,Data Scientist,2019-08-15
Doe,45,Project Manager,2015-03-23

Handling Special Characters and Encoding

CSV files may contain special characters like commas, newlines, or quotes. The csv module automatically handles some of these, but there are cases where you might need to take extra care.

Example: Writing CSV with Special Characters (Quotes, Newlines)

If your data contains quotes or newlines, the csv module will escape these characters for you. For example:

import csv

# Data containing special characters
data = [
    ['Name', 'Age', 'Occupation'],
    ['John "The Coder"', 28, 'Software Engineer'],
    ['Jane', 34, 'Data Scientist\nwith a multiline description']
]

# Open the file in write mode
with open('special_characters.csv', 'w', newline='') as file:
    writer = csv.writer(file)
    
    # Write rows to the CSV file
    writer.writerows(data)

Output (special_characters.csv):

Name,Age,Occupation
"John ""The Coder""",28,Software Engineer
Jane,34,"Data Scientist
with a multiline description"

In this example:

  • The double quotes within the Name field are escaped as "" (double quotes).
  • The multiline string in the Occupation field is properly handled by enclosing it in double quotes.

Specifying File Encoding

When working with non-ASCII characters, such as accented letters or other languages, you may need to specify the encoding explicitly.

with open('utf8_output.csv', 'w', newline='', encoding='utf-8') as file:
    writer = csv.writer(file)
    writer.writerow(['Name', 'Age', 'Occupation'])
    writer.writerow(['José', 28, 'Software Engineer'])

By specifying encoding='utf-8', you ensure that non-ASCII characters are written correctly.

Best Practices for Writing CSV Files

  1. Use with Statements: Always use a with statement to open CSV files. It ensures proper closing of the file, even if an error occurs.
  2. Choose Appropriate Delimiters: Stick with commas unless there’s a need for a different delimiter, such as semicolons.
  3. Handle Special Characters: Ensure that your data containing special characters (quotes, commas, newlines) is properly escaped.
  4. Be Mindful of Encoding: Specify the correct encoding (utf-8 for non-ASCII characters) when working with international characters.
  5. Use DictWriter for Structured Data: Use csv.DictWriter() when your data is in dictionary form, especially for structured records with headers.


< Previous
Next >