aiocsv

aiocsv brings asynchronous CSV and TSV reading and writing to Python’s asyncio ecosystem, mirroring the standard library’s csv module closely enough that existing reader/writer patterns translate directly onto async file objects. AsyncReader, AsyncDictReader, AsyncWriter, and AsyncDictWriter accept any object exposing coroutine-based read or write methods (aiofiles being the typical companion) and support every dialect and quoting option the built-in csv module does, including custom delimiters, quote characters, and Python 3.12’s QUOTE_STRINGS/QUOTE_NOTNULL modes.

Reading is implemented as a custom character-by-character state-machine parser, available both as a pure-Python fallback and as a bundled C extension for speed, while writing wraps the synchronous csv.writer/DictWriter around an in-memory buffer that gets flushed to the async file. The result is a library built specifically to replace blocking CSV I/O in async codebases without reinventing CSV parsing semantics from scratch.

What You Get

• Drop-in async equivalents of csv.reader, csv.DictReader, csv.writer, and csv.DictWriter with matching keyword arguments and dialect support
• A dual-implementation parser: a C extension (aiocsv._parser) built via setup.py for speed, with an automatic pure-Python fallback (aiocsv.parser) when the extension isn’t available
• Full support for standard csv dialects, custom delimiters/quote characters, and Python 3.12’s QUOTE_STRINGS/QUOTE_NOTNULL quoting modes
• Typed protocols (WithAsyncRead, WithAsyncWrite, DialectLike) so any async file-like object, not just aiofiles, can be used as a reader/writer target

Common Use Cases

• Streaming large CSV exports from an async web handler without blocking the event loop on file I/O
• Bulk-loading TSV/CSV data files inside an asyncio-based ETL or data-ingestion pipeline
• Writing rows incrementally to a CSV log or report file from a long-running async worker
• Parsing CSV uploads received over an async HTTP or WebSocket connection using aiofiles-backed streams

Under The Hood

Architecture The library splits cleanly into four modules: protocols.py defines the Protocol interfaces (WithAsyncRead, WithAsyncWrite, DialectLike) that decouple aiocsv from any specific async I/O library like aiofiles; readers.py and writers.py expose the public AsyncReader/AsyncDictReader/AsyncWriter/AsyncDictWriter classes; and the actual character-level parsing logic lives in a C extension (_parser.c, compiled via setup.py’s Extension) with a hand-written state-machine fallback in parser.py that mirrors the C implementation using an explicit ParserState enum (START_RECORD, IN_FIELD, IN_QUOTED_FIELD, etc.) and a Decision enum to drive a manually implemented awaitable/generator protocol bridging asyncio’s read() coroutine into a synchronous parsing loop. AsyncDictReader wraps AsyncReader and lazily fetches fieldnames on first iteration via get_fieldnames(); AsyncWriter/AsyncDictWriter wrap the stdlib’s synchronous csv.writer/csv.DictWriter around an io.StringIO buffer flushed to the async file once it exceeds the default buffer size. The two parser implementations are substituted for each other via a try/except ImportError, so they must be kept behaviorally identical.

Tech Stack The project is pure Python 3.10+ plus a C extension, built with setuptools (setup.py plus pyproject.toml, with the version read dynamically from aiocsv.version), and carries a single runtime dependency (typing_extensions, for the Unpack construct used in dialect keyword typing). It relies entirely on Python’s built-in csv module for dialect and quoting semantics, documents aiofiles as the typical async file backend without requiring it, and uses cibuildwheel with pypa’s gh-action-pypi-publish in CI to build cross-platform wheels, including free-threaded (no-GIL) builds, on every tagged release. Development tooling is ruff for formatting and linting and pyright in strict mode for type-checking, with pytest and pytest-asyncio driving the test suite.

Code Quality Tests are substantive: five files under tests/ exercise dialects, dict-based reading/writing, newline handling, and the raw parser using real temp-file round-trips against fixture CSV/TSV data rather than mocks. Error handling follows stdlib csv conventions explicitly, raising csv.Error with the same messages the built-in module would (unexpected end of data, field-size-limit exceeded) rather than swallowing malformed input. Naming is consistent and PEP8-conformant, type hints are exhaustive and checked with pyright in strict mode, and the package ships a py.typed marker so consumers get full type information. CI runs the test suite across the full supported Python matrix, including free-threaded interpreters, with ruff lint and format checks enforced on every push and pull request.

What Makes It Unique aiocsv’s specific technical contribution is providing a behaviorally faithful async surface for Python’s stdlib csv module, including edge cases like Python 3.12’s QUOTE_STRINGS/QUOTE_NOTNULL modes and a deliberate workaround for a known CPython parser bug, backed by a purpose-built character-state-machine parser implemented twice (once in C for speed, once in pure Python as a fallback) rather than the more common approach of wrapping the synchronous csv module in a thread-pool executor. That is a narrow but genuine piece of engineering rather than a thin async wrapper, though the underlying domain of CSV parsing itself is well-understood territory.