{"id":3863,"library":"aiocsv","title":"aiocsv","description":"aiocsv is a Python library for asynchronous CSV reading and writing. It strives to be a drop-in replacement for Python's built-in `csv` module, providing `AsyncReader`, `AsyncDictReader`, `AsyncWriter`, and `AsyncDictWriter` classes. It supports Python 3.9+ and utilizes a C extension for improved performance. The library is actively maintained and currently at version 1.4.0.","status":"active","version":"1.4.0","language":"en","source_language":"en","source_url":"https://github.com/MKuranowski/aiocsv","tags":["async","csv","io","parser","writer","asynchronous"],"install":[{"cmd":"pip install aiocsv","lang":"bash","label":"Install aiocsv"}],"dependencies":[{"reason":"Commonly used for asynchronous file I/O with aiocsv, as demonstrated in official examples.","package":"aiofiles","optional":true}],"imports":[{"symbol":"AsyncReader","correct":"from aiocsv import AsyncReader"},{"symbol":"AsyncDictReader","correct":"from aiocsv import AsyncDictReader"},{"symbol":"AsyncWriter","correct":"from aiocsv import AsyncWriter"},{"symbol":"AsyncDictWriter","correct":"from aiocsv import AsyncDictWriter"}],"quickstart":{"code":"import asyncio\nimport csv\nimport aiofiles\nfrom aiocsv import AsyncReader, AsyncDictReader, AsyncWriter, AsyncDictWriter\n\nasync def main():\n    # Create a dummy CSV file for reading\n    async with aiofiles.open(\"example.csv\", mode=\"w\", encoding=\"utf-8\", newline=\"\") as afp:\n        writer = AsyncWriter(afp)\n        await writer.writerow([\"name\", \"age\"])\n        await writer.writerows([[\"John\", 26], [\"Sasha\", 42]])\n\n    print(\"--- Reading simple CSV ---\")\n    async with aiofiles.open(\"example.csv\", mode=\"r\", encoding=\"utf-8\", newline=\"\") as afp:\n        async for row in AsyncReader(afp):\n            print(row)\n\n    # Create a dummy TSV file for dict reading\n    async with aiofiles.open(\"example.tsv\", mode=\"w\", encoding=\"utf-8\", newline=\"\") as afp:\n        writer = AsyncDictWriter(afp, fieldnames=[\"name\", \"city\"], delimiter=\"\\t\")\n        await writer.writeheader()\n        await writer.writerow({\"name\": \"Alice\", \"city\": \"New York\"})\n        await writer.writerow({\"name\": \"Bob\", \"city\": \"London\"})\n\n    print(\"\\n--- Reading Dict CSV (TSV) ---\")\n    async with aiofiles.open(\"example.tsv\", mode=\"r\", encoding=\"utf-8\", newline=\"\") as afp:\n        async for row in AsyncDictReader(afp, delimiter=\"\\t\"):\n            print(row)\n\n    # Writing new CSV file with AsyncWriter\n    print(\"\\n--- Writing simple CSV ---\")\n    async with aiofiles.open(\"output.csv\", mode=\"w\", encoding=\"utf-8\", newline=\"\") as afp:\n        writer = AsyncWriter(afp, dialect=\"unix\")\n        await writer.writerow([\"product\", \"price\"])\n        await writer.writerows([[\"Laptop\", 1200], [\"Mouse\", 25], [\"Keyboard\", 75]])\n    print(\"Written to output.csv\")\n\n    # Writing new CSV file with AsyncDictWriter\n    print(\"\\n--- Writing Dict CSV ---\")\n    async with aiofiles.open(\"output_dict.csv\", mode=\"w\", encoding=\"utf-8\", newline=\"\") as afp:\n        writer = AsyncDictWriter(afp, [\"item\", \"quantity\", \"status\"], restval=\"N/A\", quoting=csv.QUOTE_ALL)\n        await writer.writeheader()\n        await writer.writerow({\"item\": \"Shirt\", \"quantity\": 2, \"status\": \"available\"})\n        await writer.writerows([\n            {\"item\": \"Pants\", \"quantity\": 1},\n            {\"item\": \"Socks\", \"quantity\": 5, \"status\": \"low stock\"}\n        ])\n    print(\"Written to output_dict.csv\")\n\nasyncio.run(main())","lang":"python","description":"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."},"warnings":[{"fix":"Replace direct access to `AsyncDictReader.fieldnames` with `await reader.get_fieldnames()`.","message":"When using `AsyncDictReader`, `fieldnames` can sometimes be `None`. Instead of accessing `AsyncDictReader.fieldnames` directly, use `await AsyncDictReader.get_fieldnames()` to reliably retrieve field names.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure the underlying file object provides an `async read` method (e.g., `aiofiles`). Do not pass an `AsyncIterable` of lines.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If `csv.field_size_limit` needs to be changed, do so *before* creating `AsyncReader` instances, or create new `AsyncReader` instances after the change.","message":"Changes to `csv.field_size_limit` are not dynamically picked up by existing `AsyncReader` instances. The field size limit is cached during `Reader` instantiation.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `mode='r'` or `mode='w'` and `newline=''` when opening files with `aiofiles` for `aiocsv`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}