{"library":"types-aiofiles","title":"Typing Stubs for aiofiles","description":"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.*.","status":"active","version":"25.1.0.20251011","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","asyncio","file-io","aiofiles","typeshed"],"install":[{"cmd":"pip install types-aiofiles","lang":"bash","label":"Install stubs"},{"cmd":"pip install aiofiles types-aiofiles","lang":"bash","label":"Install runtime and stubs"}],"dependencies":[{"reason":"This package provides typing stubs for the `aiofiles` runtime library. You must install `aiofiles` separately to use the actual asynchronous file I/O functionality.","package":"aiofiles","optional":false}],"imports":[{"note":"The `types-aiofiles` package provides type hints for the `aiofiles` library. You import from `aiofiles`, not `types-aiofiles`, at runtime.","symbol":"open","correct":"import aiofiles\nasync with aiofiles.open('file.txt', mode='r') as f:"},{"note":"The `types-aiofiles` package provides type hints for the `aiofiles` library. You import from `aiofiles.os`, not `types-aiofiles.os`, at runtime.","symbol":"os","correct":"import aiofiles.os\nawait aiofiles.os.stat('file.txt')"}],"quickstart":{"code":"import asyncio\nimport aiofiles\n\nasync def main():\n    # Write to a file asynchronously\n    async with aiofiles.open('example.txt', mode='w') as f:\n        await f.write('Hello, aiofiles!\\n')\n        await f.write('This is an async file operation.')\n    print('Wrote to example.txt')\n\n    # Read from a file asynchronously\n    async with aiofiles.open('example.txt', mode='r') as f:\n        contents = await f.read()\n    print(f'Read from example.txt:\\n{contents}')\n\n    # Clean up (optional)\n    import aiofiles.os\n    await aiofiles.os.remove('example.txt')\n    print('Cleaned up example.txt')\n\nif __name__ == '__main__':\n    asyncio.run(main())","lang":"python","description":"This example demonstrates basic asynchronous file writing and reading using `aiofiles`. Ensure `aiofiles` is installed alongside `types-aiofiles` for runtime execution."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, especially when `aiofiles` and `types-aiofiles` versions diverge significantly."},{"fix":"Always install the `aiofiles` package in addition to `types-aiofiles` for runtime execution. `pip install aiofiles types-aiofiles`.","message":"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`.","severity":"breaking","affected_versions":"All versions"},{"fix":"Ensure all `import` statements in your runnable code target the `aiofiles` package, not `types-aiofiles`.","message":"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`).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"Potentially older versions of `types-aiofiles` and/or specific `aiofiles` versions."}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-05T00:00:00.000Z"}