aiofile

3.9.0 · active · verified Thu Apr 02

aiofile provides real asynchronous file operations for asyncio applications. It addresses the blocking nature of ordinary file I/O by delegating operations to a separate thread pool, ensuring that file operations do not block the asyncio event loop. The library is Apache2 licensed, currently at version 3.9.0, and maintains a stable development status.

Warnings

gotcha The low-level `aiofile.AIOFile` object does not maintain an internal file pointer. When using `AIOFile` directly, you must explicitly pass the `offset` argument for each `read` or `write` operation. For a more standard file-like behavior with an implicit pointer, use the `aiofile.async_open` helper.
Fix: Prefer `async with async_open(...) as f:` for typical file operations. If using `AIOFile`, ensure you manage `offset` for each read/write call.
gotcha The native Linux AIO implementation used by `aiofile` (via `caio`) cannot perform asynchronous operations on special file systems like `/proc/` or `/sys/`. Attempts to use `aiofile` on these file types may fail.
Fix: For operations on special file systems, you might need to configure `caio` to use its thread-based or pure Python implementations by setting the `CAIO_IMPL` environment variable (e.g., `CAIO_IMPL=thread`) or falling back to synchronous I/O if appropriate.
gotcha When reading files line by line, especially with many small lines, repeatedly calling `await file_obj.readline()` on an `async_open` object can be suboptimal. Since version 3.7.0, `__aiter__` on an `async_open` object returns a `LineReader`, which is more efficient for line-based iteration.
Fix: Use `async for line in file_obj:` (where `file_obj` is from `async_open`) for efficient line-by-line processing, leveraging the `LineReader`.
gotcha Using Python's built-in `open()` function or other synchronous file I/O operations directly within an `asyncio` application's event loop will block the entire loop, negating the benefits of asynchronous programming and potentially freezing your application.
Fix: Always use `aiofile.async_open` or other `aiofile` asynchronous primitives for file I/O within an `asyncio` context to ensure non-blocking operations.

Install

pip install aiofile Install latest version

Imports

async_open
```
from aiofile import async_open
```
Use this helper for a high-level, file-like interface similar to Python's built-in open().
AIOFile
```
from aiofile import AIOFile
```
This is a low-level interface; direct usage requires explicit offset management for read/write operations.

Quickstart

This quickstart demonstrates how to asynchronously write to and read from a file using `aiofile.async_open`, which provides a familiar file-like interface. It also shows asynchronous iteration for reading files line by line.

import asyncio
from aiofile import async_open

async def main():
    # Write to a file asynchronously
    async with async_open("hello.txt", mode="w+") as f:
        await f.write("Hello, aiofile!")
        await f.seek(0)
        content = await f.read()
        print(f"Read: {content}")

    # Read a file line by line asynchronously
    async with async_open("hello.txt", mode="r") as f:
        async for line in f:
            print(f"Line: {line.strip()}")

asyncio.run(main())

view raw JSON →