0
# AIOFile
1

2
Real asynchronous file operations with asyncio support. AIOFile provides comprehensive asynchronous file I/O capabilities with multiple backends for optimal performance across different platforms, featuring both low-level operations with explicit offset/chunk control and high-level file-like interfaces.
3

4
## Package Information
5

6
- **Package Name**: aiofile
7
- **Language**: Python
8
- **Installation**: `pip install aiofile`
9
- **Dependencies**: caio (~0.9.0)
10

11
## Core Imports
12

13
```python
14
import aiofile
15
```
16

17
Common imports for different usage patterns:
18

19
```python
20
# High-level file-like interface
21
from aiofile import async_open
22

23
# Low-level AIOFile class
24
from aiofile import AIOFile
25

26
# Streaming operations
27
from aiofile import Reader, Writer, LineReader
28

29
# File wrappers
30
from aiofile import BinaryFileWrapper, TextFileWrapper
31
```
32

33
## Basic Usage
34

35
### High-Level Usage (Recommended)
36

37
```python
38
import asyncio
39
from aiofile import async_open
40

41
async def main():
42
    # Read a text file
43
    async with async_open('data.txt', 'r') as file:
44
        content = await file.read()
45
        print(content)
46
    
47
    # Write to a binary file
48
    async with async_open('output.bin', 'wb') as file:
49
        await file.write(b'Hello, async world!')
50
        
51
    # Read file line by line
52
    async with async_open('large_file.txt', 'r') as file:
53
        async for line in file:
54
            print(line.strip())
55

56
asyncio.run(main())
57
```
58

59
### Low-Level Usage
60

61
```python
62
import asyncio
63
from aiofile import AIOFile
64

65
async def main():
66
    # Low-level operations with explicit offset
67
    async with AIOFile('data.txt', 'r') as aio_file:
68
        # Read 100 bytes from offset 0
69
        data = await aio_file.read(100, 0)
70
        
71
        # Read another chunk from offset 100
72
        more_data = await aio_file.read(100, 100)
73

74
asyncio.run(main())
75
```
76

77
## Architecture
78

79
AIOFile utilizes multiple backends for optimal performance across platforms:
80

81
- **Linux**: Uses libaio (Linux AIO) for maximum performance with kernel-level asynchronous operations
82
- **POSIX** (macOS): Uses threadpool-based implementation for compatibility
83
- **Fallback**: Pure Python thread-based implementation for other platforms
84
- **Automatic Selection**: Backend is chosen automatically based on system compatibility
85

86
The library provides three levels of abstraction:
87

88
1. **Low-Level**: Direct `AIOFile` operations with explicit offset and chunk size control
89
2. **High-Level**: File-like wrappers (`BinaryFileWrapper`, `TextFileWrapper`) accessible via `async_open`
90
3. **Streaming**: Async iterators (`Reader`, `Writer`, `LineReader`) for chunked operations
91

92
## Capabilities
93

94
### Core Low-Level File Operations
95

96
Direct asynchronous file operations with explicit offset and chunk size control. Provides maximum performance and flexibility for advanced use cases requiring precise control over file I/O operations.
97

98
```python { .api }
99
class AIOFile:
100
    def __init__(
101
        self, 
102
        filename: Union[str, Path], 
103
        mode: str = "r", 
104
        encoding: str = "utf-8",
105
        context: Optional[AsyncioContextBase] = None,
106
        executor: Optional[Executor] = None
107
    ): ...
108
    
109
    async def open(self) -> Optional[int]: ...
110
    async def close(self) -> None: ...
111
    async def read(self, size: int = -1, offset: int = 0) -> Union[bytes, str]: ...
112
    async def write(self, data: Union[str, bytes], offset: int = 0) -> int: ...
113
    async def fsync(self) -> None: ...
114
    async def fdsync(self) -> None: ...
115
```
116

117
[Core Operations](./core-operations.md)
118

119
### High-Level File Interface
120

121
Python file-like interface with asynchronous methods, providing familiar patterns for developers while maintaining async/await compatibility. Includes both text and binary file support with proper encoding handling.
122

123
```python { .api }
124
def async_open(
125
    file_specifier: Union[str, Path, FileIOType],
126
    mode: str = "r", 
127
    *args, 
128
    **kwargs
129
) -> Union[BinaryFileWrapper, TextFileWrapper]: ...
130

131
class BinaryFileWrapper:
132
    async def read(self, length: int = -1) -> bytes: ...
133
    async def write(self, data: bytes) -> int: ...
134
    async def readline(self, size: int = -1, newline: bytes = b"\n") -> bytes: ...
135

136
class TextFileWrapper:
137
    async def read(self, length: int = -1) -> str: ...
138
    async def write(self, data: str) -> int: ...
139
    async def readline(self, size: int = -1, newline: str = "\n") -> str: ...
140
```
141

142
[High-Level Interface](./high-level-interface.md)
143

144
### Streaming Operations
145

146
Async iterators for chunk-based reading and sequential writing operations. Provides efficient memory usage for large files and streaming data processing with configurable chunk sizes.
147

148
```python { .api }
149
class Reader:
150
    def __init__(
151
        self, 
152
        aio_file: AIOFile, 
153
        offset: int = 0, 
154
        chunk_size: int = 32768
155
    ): ...
156
    async def read_chunk(self) -> Union[str, bytes]: ...
157

158
class Writer:
159
    def __init__(self, aio_file: AIOFile, offset: int = 0): ...
160
    async def __call__(self, data: Union[str, bytes]) -> None: ...
161

162
class LineReader:
163
    def __init__(
164
        self, 
165
        aio_file: AIOFile, 
166
        offset: int = 0, 
167
        chunk_size: int = 4192, 
168
        line_sep: str = "\n"
169
    ): ...
170
    async def readline(self) -> Union[str, bytes]: ...
171
```
172

173
[Streaming Operations](./streaming-operations.md)
174

175
## Types
176

177
```python { .api }
178
FileIOType = Union[TextIO, BinaryIO]
179

180
class FileMode:
181
    readable: bool
182
    writable: bool
183
    plus: bool
184
    appending: bool
185
    created: bool
186
    flags: int
187
    binary: bool
188

189
def parse_mode(mode: str) -> FileMode: ...
190
```
191

192
## Version Information
193

194
```python { .api }
195
__version__: str
196
__author__: str
197
version_info: Tuple[int, ...]
198
author_info: List[Tuple[str, str]]
199
package_info: str
200
package_license: str
201
project_home: str
202
team_email: str
203
```
204

205
## Error Handling
206

207
AIOFile properly handles and propagates file system errors:
208

209
- **OSError**: For system-level file operation errors
210
- **ValueError**: For invalid parameters (negative size, wrong data types for binary/text mode)
211
- **UnicodeDecodeError**: For encoding issues in text mode (automatically retried with larger chunks)
212
- **asyncio.InvalidStateError**: For operations on closed files
213

214
## Context Management
215

216
All file objects support async context managers for automatic resource cleanup:
217

218
```python
219
async with AIOFile('file.txt', 'r') as aio_file:
220
    # File is automatically opened
221
    data = await aio_file.read()
222
# File is automatically closed and synced
223
```