0
# aiofiles
1

2
File support for asyncio applications providing async/await compatible file operations. aiofiles wraps standard Python file I/O operations and delegates them to a thread pool executor, preventing blocking of the asyncio event loop during file operations.
3

4
## Package Information
5

6
- **Package Name**: aiofiles
7
- **Language**: Python
8
- **Installation**: `pip install aiofiles`
9

10
## Core Imports
11

12
```python
13
import aiofiles
14
```
15

16
For temporary file operations:
17

18
```python
19
import aiofiles.tempfile
20
```
21

22
For OS file system operations:
23

24
```python
25
import aiofiles.os
26
from aiofiles import ospath
27
```
28

29
## Basic Usage
30

31
```python
32
import asyncio
33
import aiofiles
34

35
async def main():
36
    # Basic file reading
37
    async with aiofiles.open('example.txt', mode='r') as f:
38
        contents = await f.read()
39
        print(contents)
40
    
41
    # Basic file writing
42
    async with aiofiles.open('output.txt', mode='w') as f:
43
        await f.write('Hello, async world!')
44
    
45
    # Line-by-line reading with async iteration
46
    async with aiofiles.open('data.txt', mode='r') as f:
47
        async for line in f:
48
            print(line.strip())
49

50
asyncio.run(main())
51
```
52

53
## Architecture
54

55
aiofiles uses a delegation pattern where all I/O operations are wrapped and executed in a thread pool executor:
56

57
- **AiofilesContextManager**: Async context manager that handles file opening and closing
58
- **AsyncBase classes**: Base wrappers that delegate operations to thread pool
59
- **File type wrappers**: Specific async wrappers for different file types (text, binary, etc.)
60
- **Standard streams**: Async access to stdin, stdout, stderr
61

62
This design ensures that file operations don't block the asyncio event loop while maintaining an API nearly identical to Python's built-in file operations.
63

64
## Capabilities
65

66
### Core File Operations
67

68
Basic file opening, reading, writing, and access to standard streams. These operations form the foundation of aiofiles functionality.
69

70
```python { .api }
71
def open(
72
    file,
73
    mode: str = "r", 
74
    buffering: int = -1,
75
    encoding: str = None,
76
    errors: str = None,
77
    newline: str = None,
78
    closefd: bool = True,
79
    opener = None,
80
    *,
81
    loop = None,
82
    executor = None
83
) -> AiofilesContextManager: ...
84

85
# Standard stream objects
86
stdin: AsyncTextIndirectIOWrapper
87
stdout: AsyncTextIndirectIOWrapper  
88
stderr: AsyncTextIndirectIOWrapper
89
stdin_bytes: AsyncIndirectBufferedIOBase
90
stdout_bytes: AsyncIndirectBufferedIOBase
91
stderr_bytes: AsyncIndirectBufferedIOBase
92
```
93

94
[Core File Operations](./core-file-operations.md)
95

96
### Temporary File Operations
97

98
Async interface to Python's tempfile module, providing temporary files and directories with automatic cleanup.
99

100
```python { .api }
101
def NamedTemporaryFile(
102
    mode: str = "w+b",
103
    buffering: int = -1, 
104
    encoding: str = None,
105
    newline: str = None,
106
    suffix: str = None,
107
    prefix: str = None,
108
    dir: str = None,
109
    delete: bool = True,
110
    delete_on_close: bool = True,  # Python 3.12+ only
111
    *,
112
    loop = None,
113
    executor = None
114
) -> AiofilesContextManager: ...
115

116
def TemporaryFile(
117
    mode: str = "w+b",
118
    buffering: int = -1,
119
    encoding: str = None, 
120
    newline: str = None,
121
    suffix: str = None,
122
    prefix: str = None,
123
    dir: str = None,
124
    *,
125
    loop = None,
126
    executor = None
127
) -> AiofilesContextManager: ...
128
```
129

130
[Temporary File Operations](./tempfile-operations.md)
131

132
### OS File System Operations
133

134
Async versions of os module functions for file system operations like renaming, removing, creating directories, and getting file statistics.
135

136
```python { .api }
137
async def stat(path: str, *, loop = None, executor = None): ...
138
async def rename(src: str, dst: str, *, loop = None, executor = None): ...
139
async def remove(path: str, *, loop = None, executor = None): ...
140
async def mkdir(path: str, mode: int = 0o777, *, loop = None, executor = None): ...
141
async def listdir(path: str = ".", *, loop = None, executor = None): ...
142
```
143

144
[OS File System Operations](./os-operations.md)
145

146
### OS Path Operations
147

148
Async versions of os.path module functions for path manipulation and information gathering.
149

150
```python { .api }
151
async def exists(path: str, *, loop = None, executor = None) -> bool: ...
152
async def isfile(path: str, *, loop = None, executor = None) -> bool: ...
153
async def isdir(path: str, *, loop = None, executor = None) -> bool: ...
154
async def getsize(path: str, *, loop = None, executor = None) -> int: ...
155
async def getmtime(path: str, *, loop = None, executor = None) -> float: ...
156
```
157

158
[OS Path Operations](./path-operations.md)
159

160
## Types
161

162
```python { .api }
163
class AiofilesContextManager:
164
    """Async context manager for aiofiles operations."""
165
    def __init__(self, coro): ...
166
    async def __aenter__(self): ...
167
    async def __aexit__(self, exc_type, exc_val, exc_tb): ...
168
    def __await__(self): ...
169

170
class AsyncBase:
171
    """Base class for async file wrappers."""
172
    def __init__(self, file, loop, executor): ...
173
    def __aiter__(self): ...
174
    async def __anext__(self): ...
175
```