aiofile

aiofile provides genuinely asynchronous file I/O for Python’s asyncio, rather than simply delegating blocking calls to a thread pool the way most alternatives do. Built on the caio library, it automatically selects the best available backend for the running system: Linux io_uring, the classic libaio kernel interface, a C thread-pool implementation for POSIX platforms, or a pure-Python fallback.

The package offers both a low-level AIOFile object with explicit offset-based reads and writes, and a high-level async_open helper that mimics Python’s familiar file objects with awaitable methods, line iteration, and chunked readers. This makes it a practical drop-in for high-throughput services that need to read and write files without stalling the event loop.

What You Get

• An AIOFile primitive with explicit offset and chunk-size control for precise, pointerless file access
• A high-level async_open helper that mirrors Python’s built-in file objects with awaitable read, write, seek, and readline
• Reader, Writer, and LineReader helpers for streaming files in chunks or line by line
• Automatic backend selection across io_uring, libaio, C thread pools, and a pure-Python fallback
• Full type hints via a bundled py.typed marker

Common Use Cases

• Serving or ingesting large files in an asyncio web service without blocking the event loop
• Streaming file contents chunk by chunk in data pipelines and log processors
• Reading and writing files concurrently alongside network I/O in high-throughput async applications

Under The Hood

Architecture - aiofile is a thin, focused wrapper over the caio library. The core aiofile/aio.py defines the AIOFile class, which holds no internal file pointer and delegates every read/write to a caio AsyncioContext bound to the running event loop; parse_mode reconstructs CPython’s fileio flag logic to translate mode strings into open flags. Higher-level ergonomics live in aiofile/utils.py, which builds Reader, Writer, LineReader, and the async_open factory on top of that primitive, layering buffering and line-splitting over pointerless offset-based operations.

Tech Stack - Pure Python (3.11+), with a single runtime dependency on caio (~=0.9.0) that supplies the native io_uring, libaio, and C thread-pool backends. Packaging is managed through pyproject.toml with a uv.lock, and the dev toolchain uses ruff, pytest, pytest-cov, aiomisc-pytest, and ty for type checking.

Code Quality - The codebase is compact (~800 lines across four modules), fully type-hinted with a bundled py.typed marker, and marked Development Status Production/Stable. A dedicated tests directory (test_aio.py plus conftest and impl helpers) exercises the API, and README examples are executed as documentation tests via markdown-pytest. Naming follows CPython file-object conventions, easing adoption.

API Design - The public surface is deliberately small and familiar: async_open returns an object whose await-able read/write/seek/readline methods mirror Python’s built-in files, so migrating synchronous code is mostly a matter of adding await. The lower-level AIOFile plus Reader/Writer helpers give power users explicit offset control, and the README documents both tiers with runnable examples, keeping the learning curve low.