aiocsv

Warnings

• gotcha When using `AsyncDictReader`, `fieldnames` can sometimes be `None`. Instead of accessing `AsyncDictReader.fieldnames` directly, use `await AsyncDictReader.get_fieldnames()` to reliably retrieve field names.
  Fix: Replace direct access to `AsyncDictReader.fieldnames` with `await reader.get_fieldnames()`.
• gotcha `aiocsv` readers (`AsyncReader`, `AsyncDictReader`) expect file-like objects with an `async read(size: int)` coroutine, *not* an `AsyncIterable` over lines from a file. This differs from the standard `csv` module's behavior.
  Fix: Ensure the underlying file object provides an `async read` method (e.g., `aiofiles`). Do not pass an `AsyncIterable` of lines.
• gotcha Changes to `csv.field_size_limit` are not dynamically picked up by existing `AsyncReader` instances. The field size limit is cached during `Reader` instantiation.
  Fix: If `csv.field_size_limit` needs to be changed, do so *before* creating `AsyncReader` instances, or create new `AsyncReader` instances after the change.
• gotcha Files *must* be opened in text mode (`'r'` or `'w'`) and with `newline=""`. Additionally, ensure the file's line terminators match the dialect's `lineterminator`. `aiocsv` is less tolerant of mismatched newlines than the built-in `csv` module.
  Fix: Always use `mode='r'` or `mode='w'` and `newline=''` when opening files with `aiofiles` for `aiocsv`.
• gotcha The `AsyncWriter.writerows()` and `AsyncDictWriter.writerows()` methods temporarily store *all* provided rows in RAM before writing them to the file. Providing a generator for extremely large datasets can lead to high memory consumption.
  Fix: For very large datasets, consider iterating and writing rows one by one using `writerow()` rather than `writerows()`, or ensure the input iterable is not excessively large.

Install

• pip install aiocsv Install aiocsv

Imports

• AsyncReader

  from aiocsv import AsyncReader

• AsyncDictReader

  from aiocsv import AsyncDictReader

• AsyncWriter

  from aiocsv import AsyncWriter

• AsyncDictWriter

  from aiocsv import AsyncDictWriter

Quickstart

This quickstart demonstrates both reading and writing CSV and TSV files asynchronously using `aiocsv` with `aiofiles`. It covers basic `AsyncReader` and `AsyncWriter` usage for list-based rows, as well as `AsyncDictReader` and `AsyncDictWriter` for dictionary-based rows, including header writing and custom delimiters.

import asyncio
import csv
import aiofiles
from aiocsv import AsyncReader, AsyncDictReader, AsyncWriter, AsyncDictWriter

async def main():
    # Create a dummy CSV file for reading
    async with aiofiles.open("example.csv", mode="w", encoding="utf-8", newline="") as afp:
        writer = AsyncWriter(afp)
        await writer.writerow(["name", "age"])
        await writer.writerows([["John", 26], ["Sasha", 42]])

    print("--- Reading simple CSV ---")
    async with aiofiles.open("example.csv", mode="r", encoding="utf-8", newline="") as afp:
        async for row in AsyncReader(afp):
            print(row)

    # Create a dummy TSV file for dict reading
    async with aiofiles.open("example.tsv", mode="w", encoding="utf-8", newline="") as afp:
        writer = AsyncDictWriter(afp, fieldnames=["name", "city"], delimiter="\t")
        await writer.writeheader()
        await writer.writerow({"name": "Alice", "city": "New York"})
        await writer.writerow({"name": "Bob", "city": "London"})

    print("\n--- Reading Dict CSV (TSV) ---")
    async with aiofiles.open("example.tsv", mode="r", encoding="utf-8", newline="") as afp:
        async for row in AsyncDictReader(afp, delimiter="\t"):
            print(row)

    # Writing new CSV file with AsyncWriter
    print("\n--- Writing simple CSV ---")
    async with aiofiles.open("output.csv", mode="w", encoding="utf-8", newline="") as afp:
        writer = AsyncWriter(afp, dialect="unix")
        await writer.writerow(["product", "price"])
        await writer.writerows([["Laptop", 1200], ["Mouse", 25], ["Keyboard", 75]])
    print("Written to output.csv")

    # Writing new CSV file with AsyncDictWriter
    print("\n--- Writing Dict CSV ---")
    async with aiofiles.open("output_dict.csv", mode="w", encoding="utf-8", newline="") as afp:
        writer = AsyncDictWriter(afp, ["item", "quantity", "status"], restval="N/A", quoting=csv.QUOTE_ALL)
        await writer.writeheader()
        await writer.writerow({"item": "Shirt", "quantity": 2, "status": "available"})
        await writer.writerows([
            {"item": "Pants", "quantity": 1},
            {"item": "Socks", "quantity": 5, "status": "low stock"}
        ])
    print("Written to output_dict.csv")

asyncio.run(main())