Meta

• License: MIT License
• Author:Mikołaj Kuranowski
• Tags async, asynchronous, csv, tsv
• Requires: Python >=3.8

Classifiers

• Development Status
  • 5 - Production/Stable
• Framework
  • AsyncIO
• License
  • OSI Approved :: MIT License
• Programming Language
  • Python :: 3 :: Only

aiocsv

Asynchronous CSV reading and writing.

Installation

pip install aiocsv. Python 3.8+ is required.

This module contains an extension written in C. Pre-build binariesmay not be available for your configuration. You might need a C compilerand Python headers to install aiocsv.

Usage

AsyncReader & AsyncDictReader accept any object that has aread(size: int) coroutine,which should return a string.

AsyncWriter & AsyncDictWriter accept any object that has awrite(b: str) coroutine.

Reading is implemented using a custom CSV parser, which should behave exactly like the CPython parser.

Writing is implemented using the synchronous csv.writer and csv.DictWriter objects -the serializers write data to a StringIO, and that buffer is then rewritten to the underlyingasynchronous file.

Example

Example usage withaiofiles.

importasyncioimportcsvimportaiofilesfromaiocsvimportAsyncReader,AsyncDictReader,AsyncWriter,AsyncDictWriterasyncdefmain():# simple readingasyncwithaiofiles.open("some_file.csv",mode="r",encoding="utf-8",newline="")asafp:asyncforrowinAsyncReader(afp):print(row)# row is a list# dict reading, tab-separatedasyncwithaiofiles.open("some_other_file.tsv",mode="r",encoding="utf-8",newline="")asafp:asyncforrowinAsyncDictReader(afp,delimiter="\t"):print(row)# row is a dict# simple writing, "unix"-dialectasyncwithaiofiles.open("new_file.csv",mode="w",encoding="utf-8",newline="")asafp:writer=AsyncWriter(afp,dialect="unix")awaitwriter.writerow(["name","age"])awaitwriter.writerows([["John",26],["Sasha",42],["Hana",37]])# dict writing, all quoted, "NULL" for missing fieldsasyncwithaiofiles.open("new_file2.csv",mode="w",encoding="utf-8",newline="")asafp:writer=AsyncDictWriter(afp,["name","age"],restval="NULL",quoting=csv.QUOTE_ALL)awaitwriter.writeheader()awaitwriter.writerow({"name":"John","age":26})awaitwriter.writerows([{"name":"Sasha","age":42},{"name":"Hana"}])asyncio.run(main())

Differences withcsv

aiocsv strives to be a drop-in replacement for Python's builtincsv module. However, there are 3 notable differences:

• Readers accept objects with asyncread methods, instead of an AsyncIterable over linesfrom a file.
• AsyncDictReader.fieldnames can beNone - useawait AsyncDictReader.get_fieldnames() instead.
• Changes tocsv.field_size_limit are not picked up by existing Reader instances.The field size limit is cached on Reader instantiation to avoid expensive function callson each character of the input.

Other, minor, differences include:

• AsyncReader.line_num,AsyncDictReader.line_num andAsyncDictReader.dialect are not settable,
• AsyncDictReader.reader is ofAsyncReader type,
• AsyncDictWriter.writer is ofAsyncWriter type,
• AsyncDictWriter provides an extra, read-onlydialect property.

Reference

aiocsv.AsyncReader

AsyncReader(    asyncfile: aiocsv.protocols.WithAsyncRead,    dialect: str | csv.Dialect | Type[csv.Dialect] = "excel",    **csv_dialect_kwargs: Unpack[aiocsv.protocols.CsvDialectKwargs],)

An object that iterates over records in the given asynchronous CSV file.Additional keyword arguments are understood as dialect parameters.

Iterating over this object returns parsed CSV rows (List[str]).

Methods:

• __aiter__(self) -> self
• async __anext__(self) -> List[str]

Read-only properties:

• dialect: The csv.Dialect used when parsing
• line_num: The number of lines read from the source file. This coincides with a 1-based indexof the line number of the last line of the recently parsed record.

aiocsv.AsyncDictReader

AsyncDictReader(    asyncfile: aiocsv.protocols.WithAsyncRead,    fieldnames: Optional[Sequence[str]] = None,    restkey: Optional[str] = None,    restval: Optional[str] = None,    dialect: str | csv.Dialect | Type[csv.Dialect] = "excel",    **csv_dialect_kwargs: Unpack[aiocsv.protocols.CsvDialectKwargs],)

An object that iterates over records in the given asynchronous CSV file.All arguments work exactly the same was as in csv.DictReader.

Iterating over this object returns parsed CSV rows (Dict[str, str]).

Methods:

• __aiter__(self) -> self
• async __anext__(self) -> Dict[str, str]
• async get_fieldnames(self) -> List[str]

Properties:

• fieldnames: field names used when converting rows to dictionaries
  ⚠️ Unlike csv.DictReader, this property can't read the fieldnames if they are missing -it's not possible toawait on the header row in a property getter.Useawait reader.get_fieldnames().

  reader=csv.DictReader(some_file)reader.fieldnames# ["cells", "from", "the", "header"]areader=aiofiles.AsyncDictReader(same_file_but_async)areader.fieldnames# ⚠️ Noneawaitareader.get_fieldnames()# ["cells", "from", "the", "header"]

• restkey: If a row has more cells then the header, all remaining cells are stored underthis key in the returned dictionary. Defaults toNone.
• restval: If a row has less cells then the header, then missing keys will use thisvalue. Defaults toNone.
• reader: Underlyingaiofiles.AsyncReader instance

Read-only properties:

• dialect: Link toself.reader.dialect - the current csv.Dialect
• line_num: The number of lines read from the source file. This coincides with a 1-based indexof the line number of the last line of the recently parsed record.

aiocsv.AsyncWriter

AsyncWriter(    asyncfile: aiocsv.protocols.WithAsyncWrite,    dialect: str | csv.Dialect | Type[csv.Dialect] = "excel",    **csv_dialect_kwargs: Unpack[aiocsv.protocols.CsvDialectKwargs],)

An object that writes csv rows to the given asynchronous file.In this object "row" is a sequence of values.

Additional keyword arguments are passed to the underlying csv.writer instance.

Methods:

• async writerow(self, row: Iterable[Any]) -> None:Writes one row to the specified file.
• async writerows(self, rows: Iterable[Iterable[Any]]) -> None:Writes multiple rows to the specified file.

Readonly properties:

• dialect: Link to underlying's csv.writer'sdialect attribute

aiocsv.AsyncDictWriter

AsyncDictWriter(    asyncfile: aiocsv.protocols.WithAsyncWrite,    fieldnames: Sequence[str],    restval: Any = "",    extrasaction: Literal["raise", "ignore"] = "raise",    dialect: str | csv.Dialect | Type[csv.Dialect] = "excel",    **csv_dialect_kwargs: Unpack[aiocsv.protocols.CsvDialectKwargs],)

An object that writes csv rows to the given asynchronous file.In this object "row" is a mapping from fieldnames to values.

Additional keyword arguments are passed to the underlying csv.DictWriter instance.

Methods:

• async writeheader(self) -> None: Writes header row to the specified file.
• async writerow(self, row: Mapping[str, Any]) -> None:Writes one row to the specified file.
• async writerows(self, rows: Iterable[Mapping[str, Any]]) -> None:Writes multiple rows to the specified file.

Properties:

• fieldnames: Sequence of keys to identify the order of values when writing rowsto the underlying file
• restval: Placeholder value used when a key from fieldnames is missing in a row,defaults to""
• extrasaction: Action to take when there are keys in a row, which are not present infieldnames, defaults to"raise" which causes ValueError to be raised on extra keys,may be also set to"ignore" to ignore any extra keys
• writer: Link to the underlyingAsyncWriter

Readonly properties:

• dialect: Link to underlying's csv.reader'sdialect attribute

aiocsv.protocols.WithAsyncRead

Atyping.Protocol describing an asynchronous file, which can be read.

aiocsv.protocols.WithAsyncWrite

Atyping.Protocol describing an asynchronous file, which can be written to.

aiocsv.protocols.CsvDialectArg

Type of thedialect argument, as used in thecsv module.

aiocsv.protocols.CsvDialectKwargs

Keyword arguments used bycsv module to override the dialect settings during reader/writerinstantiation.

Development

Contributions are welcome, however please open an issue beforehand.aiocsv is meant asa replacement for the built-incsv, any features not present in the latter will be rejected.

Building from source

To create a wheel (and a source tarball), runpython -m build.

For local development, use avirtual environment.pip install --editable . will build the C extension and make it available for the currentvenv. This is required for running the tests. However,due to the mess of Python packagingthis will force an optimized build without debugging symbols. If you need to debug the C partof aiocsv and build the library with e.g. debugging symbols, the only sane way is torunpython setup.py build --debug and manually copy the shared object/DLL frombuild/lib*/aiocsvtoaiocsv.

Tests

This project usespytest withpytest-asyncio for testing. Runpytestafter installing the library in the manner explained above.

Linting & other tools

This library usesblack andisortfor formatting andpyright in strict mode for type checking.

For the C part of library, please useclang-formatfor formatting andclang-tidy linting,however this are not yet integrated in the CI.

Installing required tools

pip install -r requirements.dev.txt will pull all of the development tools mentioned above,however this might not be necessary depending on your setup. For example, if you use VS Codewith the Python extension, pyright is already bundled and doesn't need to be installed again.

Recommended VS Code settings

UsePython,Pylance(should be installed automatically alongside Python extension),black andisort Python extensions.

You will need to install all dev dependencies fromrequirements.dev.txt, except forpyright.Recommended.vscode/settings.json:

{"C_Cpp.codeAnalysis.clangTidy.enabled":true,"python.testing.pytestArgs":["."],"python.testing.unittestEnabled":false,"python.testing.pytestEnabled":true,"[python]":{"editor.formatOnSave":true,"editor.codeActionsOnSave":{"source.organizeImports":"always"}},"[c]":{"editor.formatOnSave":true}}

For the C part of the library,C/C++ extension is sufficient.Ensure that your system has Python headers installed. Usually a separate package like python3-devneeds to be installed, consult with your system repositories on that..vscode/c_cpp_properties.jsonneeds to manually include Python headers underincludePath. On my particular system thisconfig file looks like this:

{"configurations":[{"name":"Linux","includePath":["${workspaceFolder}/**","/usr/include/python3.11"],"defines":[],"compilerPath":"/usr/bin/clang","cStandard":"c17","cppStandard":"c++17","intelliSenseMode":"linux-clang-x64"}],"version":4}

Verified details

Maintainers

MKuranowski

Unverified details

Project links

• Homepage

• Download URL:aiocsv-1.3.2.tar.gz
• Upload date: Apr 28, 2024
• Size: 24.8 kB
• Tags: Source
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/5.0.0 CPython/3.11.8

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp313-cp313-win_amd64.whl
• Upload date: Jan 21, 2025
• Size: 29.3 kB
• Tags: CPython 3.13, Windows x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/6.0.1 CPython/3.12.8

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp313-cp313-musllinux_1_2_x86_64.whl
• Upload date: Jan 21, 2025
• Size: 50.1 kB
• Tags: CPython 3.13, musllinux: musl 1.2+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/6.0.1 CPython/3.12.8

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp313-cp313-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
• Upload date: Jan 21, 2025
• Size: 51.3 kB
• Tags: CPython 3.13, manylinux: glibc 2.17+ x86-64, manylinux: glibc 2.5+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/6.0.1 CPython/3.12.8

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp313-cp313-macosx_10_13_x86_64.whl
• Upload date: Jan 21, 2025
• Size: 26.5 kB
• Tags: CPython 3.13, macOS 10.13+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/6.0.1 CPython/3.12.8

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp312-cp312-win_amd64.whl
• Upload date: Apr 28, 2024
• Size: 29.1 kB
• Tags: CPython 3.12, Windows x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/5.0.0 CPython/3.12.3

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp312-cp312-musllinux_1_2_x86_64.whl
• Upload date: Jan 21, 2025
• Size: 50.1 kB
• Tags: CPython 3.12, musllinux: musl 1.2+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/6.0.1 CPython/3.12.8

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp312-cp312-musllinux_1_1_x86_64.whl
• Upload date: Apr 28, 2024
• Size: 55.9 kB
• Tags: CPython 3.12, musllinux: musl 1.1+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/5.0.0 CPython/3.12.3

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
• Upload date: Apr 28, 2024
• Size: 51.5 kB
• Tags: CPython 3.12, manylinux: glibc 2.17+ x86-64, manylinux: glibc 2.5+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/5.0.0 CPython/3.12.3

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp312-cp312-macosx_10_13_x86_64.whl
• Upload date: Jan 21, 2025
• Size: 26.5 kB
• Tags: CPython 3.12, macOS 10.13+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/6.0.1 CPython/3.12.8

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp312-cp312-macosx_10_9_x86_64.whl
• Upload date: Apr 28, 2024
• Size: 26.5 kB
• Tags: CPython 3.12, macOS 10.9+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/5.0.0 CPython/3.12.3

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp311-cp311-win_amd64.whl
• Upload date: Apr 28, 2024
• Size: 29.1 kB
• Tags: CPython 3.11, Windows x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/5.0.0 CPython/3.12.3

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp311-cp311-musllinux_1_2_x86_64.whl
• Upload date: Jan 21, 2025
• Size: 48.2 kB
• Tags: CPython 3.11, musllinux: musl 1.2+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/6.0.1 CPython/3.12.8

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp311-cp311-musllinux_1_1_x86_64.whl
• Upload date: Apr 28, 2024
• Size: 54.3 kB
• Tags: CPython 3.11, musllinux: musl 1.1+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/5.0.0 CPython/3.12.3

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp311-cp311-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
• Upload date: Apr 28, 2024
• Size: 49.4 kB
• Tags: CPython 3.11, manylinux: glibc 2.17+ x86-64, manylinux: glibc 2.5+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/5.0.0 CPython/3.12.3

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp311-cp311-macosx_10_9_x86_64.whl
• Upload date: Apr 28, 2024
• Size: 26.4 kB
• Tags: CPython 3.11, macOS 10.9+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/5.0.0 CPython/3.12.3

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp310-cp310-win_amd64.whl
• Upload date: Apr 28, 2024
• Size: 29.1 kB
• Tags: CPython 3.10, Windows x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/5.0.0 CPython/3.12.3

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp310-cp310-musllinux_1_2_x86_64.whl
• Upload date: Jan 21, 2025
• Size: 47.1 kB
• Tags: CPython 3.10, musllinux: musl 1.2+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/6.0.1 CPython/3.12.8

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp310-cp310-musllinux_1_1_x86_64.whl
• Upload date: Apr 28, 2024
• Size: 52.2 kB
• Tags: CPython 3.10, musllinux: musl 1.1+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/5.0.0 CPython/3.12.3

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
• Upload date: Apr 28, 2024
• Size: 48.0 kB
• Tags: CPython 3.10, manylinux: glibc 2.17+ x86-64, manylinux: glibc 2.5+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/5.0.0 CPython/3.12.3

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp310-cp310-macosx_10_9_x86_64.whl
• Upload date: Apr 28, 2024
• Size: 26.4 kB
• Tags: CPython 3.10, macOS 10.9+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/5.0.0 CPython/3.12.3

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp39-cp39-win_amd64.whl
• Upload date: Apr 28, 2024
• Size: 29.2 kB
• Tags: CPython 3.9, Windows x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/5.0.0 CPython/3.12.3

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp39-cp39-musllinux_1_2_x86_64.whl
• Upload date: Jan 21, 2025
• Size: 48.2 kB
• Tags: CPython 3.9, musllinux: musl 1.2+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/6.0.1 CPython/3.12.8

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp39-cp39-musllinux_1_1_x86_64.whl
• Upload date: Apr 28, 2024
• Size: 53.6 kB
• Tags: CPython 3.9, musllinux: musl 1.1+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/5.0.0 CPython/3.12.3

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
• Upload date: Apr 28, 2024
• Size: 49.2 kB
• Tags: CPython 3.9, manylinux: glibc 2.17+ x86-64, manylinux: glibc 2.5+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/5.0.0 CPython/3.12.3

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp39-cp39-macosx_10_9_x86_64.whl
• Upload date: Apr 28, 2024
• Size: 26.7 kB
• Tags: CPython 3.9, macOS 10.9+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/5.0.0 CPython/3.12.3

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp38-cp38-win_amd64.whl
• Upload date: Apr 28, 2024
• Size: 29.2 kB
• Tags: CPython 3.8, Windows x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/5.0.0 CPython/3.12.3

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp38-cp38-musllinux_1_2_x86_64.whl
• Upload date: Jan 21, 2025
• Size: 49.1 kB
• Tags: CPython 3.8, musllinux: musl 1.2+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/6.0.1 CPython/3.12.8

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp38-cp38-musllinux_1_1_x86_64.whl
• Upload date: Apr 28, 2024
• Size: 55.5 kB
• Tags: CPython 3.8, musllinux: musl 1.1+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/5.0.0 CPython/3.12.3

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
• Upload date: Apr 28, 2024
• Size: 51.2 kB
• Tags: CPython 3.8, manylinux: glibc 2.17+ x86-64, manylinux: glibc 2.5+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/5.0.0 CPython/3.12.3

See more details on using hashes here.

• Download URL:aiocsv-1.3.2-cp38-cp38-macosx_10_9_x86_64.whl
• Upload date: Apr 28, 2024
• Size: 26.7 kB
• Tags: CPython 3.8, macOS 10.9+ x86-64
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/5.0.0 CPython/3.12.3

See more details on using hashes here.