Typing Stubs for aiofiles

25.1.0.20251011 · active · verified Mon Apr 06

types-aiofiles provides type stubs for the aiofiles library, enabling static type checkers like MyPy and Pyright to verify code that uses aiofiles. It is part of the typeshed project and is regularly updated, with version 25.1.0.20251011 aiming for aiofiles==25.1.*.

Warnings

gotcha Stub versions are designed for specific runtime library versions (e.g., `types-aiofiles==25.1.0.20251011` for `aiofiles==25.1.*`). Mismatches can lead to incorrect type checking results or missed type errors.
Fix: Align the version of `types-aiofiles` with the version of `aiofiles` you are using. The `types-aiofiles` PyPI page usually specifies the target `aiofiles` version.
breaking This package provides *only* type stubs (`.pyi` files) for `aiofiles`, not the runtime library itself. You still need to install `aiofiles` (`pip install aiofiles`) to use its functionality. Attempting to run code with only `types-aiofiles` installed will result in `ModuleNotFoundError` for `aiofiles`.
Fix: Always install the `aiofiles` package in addition to `types-aiofiles` for runtime execution. `pip install aiofiles types-aiofiles`.
gotcha Do not attempt to import symbols directly from `types-aiofiles` in your runtime code. It is purely for static type checking; all runtime imports should come from the `aiofiles` package (e.g., `import aiofiles`, `import aiofiles.os`).
Fix: Ensure all `import` statements in your runnable code target the `aiofiles` package, not `types-aiofiles`.
gotcha A known issue in `typeshed` (and thus `types-aiofiles`) involved `aiofiles.tempfile.NamedTemporaryFile.name` being incorrectly typed as `FileDescriptorOrPath` instead of `str`. While potentially fixed in newer stub versions, verify with your type checker if you encounter issues when accessing the `.name` attribute.
Fix: Check the exact type revealed by your type checker (e.g., `reveal_type(f.name)` with MyPy). If incorrect, consider upgrading `types-aiofiles` and `aiofiles` to their latest compatible versions or casting the type if necessary.

Install

pip install types-aiofiles Install stubs
pip install aiofiles types-aiofiles Install runtime and stubs

Imports

open
```
import aiofiles
async with aiofiles.open('file.txt', mode='r') as f:
```
The `types-aiofiles` package provides type hints for the `aiofiles` library. You import from `aiofiles`, not `types-aiofiles`, at runtime.
os
```
import aiofiles.os
await aiofiles.os.stat('file.txt')
```
The `types-aiofiles` package provides type hints for the `aiofiles` library. You import from `aiofiles.os`, not `types-aiofiles.os`, at runtime.

Quickstart

This example demonstrates basic asynchronous file writing and reading using `aiofiles`. Ensure `aiofiles` is installed alongside `types-aiofiles` for runtime execution.

import asyncio
import aiofiles

async def main():
    # Write to a file asynchronously
    async with aiofiles.open('example.txt', mode='w') as f:
        await f.write('Hello, aiofiles!\n')
        await f.write('This is an async file operation.')
    print('Wrote to example.txt')

    # Read from a file asynchronously
    async with aiofiles.open('example.txt', mode='r') as f:
        contents = await f.read()
    print(f'Read from example.txt:\n{contents}')

    # Clean up (optional)
    import aiofiles.os
    await aiofiles.os.remove('example.txt')
    print('Cleaned up example.txt')

if __name__ == '__main__':
    asyncio.run(main())

view raw JSON →