0
# Core Low-Level File Operations
1
2
Direct asynchronous file operations with explicit offset and chunk size control. The AIOFile class provides the foundation for all file operations with maximum performance and flexibility for advanced use cases.
3
4
## Capabilities
5
6
### AIOFile Class
7
8
The core class providing low-level asynchronous file operations. Unlike traditional file objects, AIOFile has no internal pointer - you must specify offset and chunk_size for each operation.
9
10
```python { .api }
11
class AIOFile:
12
def __init__(
13
self,
14
filename: Union[str, Path],
15
mode: str = "r",
16
encoding: str = "utf-8",
17
context: Optional[AsyncioContextBase] = None,
18
executor: Optional[Executor] = None
19
):
20
"""
21
Initialize AIOFile instance.
22
23
Args:
24
filename: Path to file as string or Path object
25
mode: File mode ('r', 'w', 'a', 'x', 'b', '+' combinations)
26
encoding: Text encoding for non-binary modes (default: 'utf-8')
27
context: Optional caio AsyncioContext for custom backend configuration
28
executor: Optional executor for thread-based operations
29
"""
30
```
31
32
#### File Lifecycle
33
34
```python { .api }
35
async def open(self) -> Optional[int]:
36
"""
37
Open the file for operations.
38
39
Returns:
40
File descriptor number if newly opened, None if already open
41
42
Raises:
43
asyncio.InvalidStateError: If file was previously closed
44
"""
45
46
async def close(self) -> None:
47
"""
48
Close the file and sync data if writable.
49
50
Automatically calls fdsync() for writable files before closing.
51
"""
52
53
def fileno(self) -> int:
54
"""
55
Get the file descriptor number.
56
57
Returns:
58
File descriptor as integer
59
60
Raises:
61
asyncio.InvalidStateError: If file is not open
62
"""
63
```
64
65
#### Reading Operations
66
67
```python { .api }
68
async def read(self, size: int = -1, offset: int = 0) -> Union[bytes, str]:
69
"""
70
Read data from file at specified offset.
71
72
Args:
73
size: Number of bytes to read (-1 for entire file)
74
offset: Byte offset to start reading from
75
76
Returns:
77
bytes in binary mode, str in text mode
78
79
Raises:
80
ValueError: If size < -1
81
"""
82
83
async def read_bytes(self, size: int = -1, offset: int = 0) -> bytes:
84
"""
85
Read raw bytes from file at specified offset.
86
87
Args:
88
size: Number of bytes to read (-1 for entire file)
89
offset: Byte offset to start reading from
90
91
Returns:
92
Raw bytes data
93
94
Raises:
95
ValueError: If size < -1
96
"""
97
```
98
99
#### Writing Operations
100
101
```python { .api }
102
async def write(self, data: Union[str, bytes], offset: int = 0) -> int:
103
"""
104
Write data to file at specified offset.
105
106
Args:
107
data: Data to write (str for text mode, bytes for binary mode)
108
offset: Byte offset to start writing at
109
110
Returns:
111
Number of bytes written
112
113
Raises:
114
ValueError: If data type doesn't match file mode
115
"""
116
117
async def write_bytes(self, data: bytes, offset: int = 0) -> int:
118
"""
119
Write raw bytes to file at specified offset.
120
121
Handles partial writes by continuing until all data is written.
122
123
Args:
124
data: Raw bytes to write
125
offset: Byte offset to start writing at
126
127
Returns:
128
Number of bytes written
129
130
Raises:
131
RuntimeError: If write operation returns 0 (disk full, etc.)
132
OSError: For system-level write errors
133
"""
134
```
135
136
#### File Synchronization
137
138
```python { .api }
139
async def fsync(self) -> None:
140
"""
141
Sync file data and metadata to disk.
142
143
Forces all written data and metadata to be physically stored.
144
More comprehensive than fdsync() but potentially slower.
145
"""
146
147
async def fdsync(self) -> None:
148
"""
149
Sync file data to disk (without metadata).
150
151
Forces written data to be physically stored.
152
Faster than fsync() but doesn't guarantee metadata sync.
153
"""
154
155
async def truncate(self, length: int = 0) -> None:
156
"""
157
Truncate file to specified length.
158
159
Args:
160
length: New file length in bytes (default: 0)
161
"""
162
```
163
164
#### Text Encoding/Decoding
165
166
```python { .api }
167
def encode_bytes(self, data: str) -> bytes:
168
"""
169
Encode string to bytes using file's encoding.
170
171
Args:
172
data: String to encode
173
174
Returns:
175
Encoded bytes
176
"""
177
178
def decode_bytes(self, data: bytes) -> str:
179
"""
180
Decode bytes to string using file's encoding.
181
182
Args:
183
data: Bytes to decode
184
185
Returns:
186
Decoded string
187
"""
188
```
189
190
#### Class Methods
191
192
```python { .api }
193
@classmethod
194
def from_fp(cls, fp: FileIOType, **kwargs) -> "AIOFile":
195
"""
196
Create AIOFile from existing file pointer.
197
198
Args:
199
fp: Existing file object (TextIO or BinaryIO)
200
**kwargs: Additional arguments passed to constructor
201
202
Returns:
203
AIOFile instance wrapping the file pointer
204
"""
205
```
206
207
#### Properties
208
209
```python { .api }
210
@property
211
def name(self) -> str:
212
"""File name as string."""
213
214
@property
215
def loop(self) -> asyncio.AbstractEventLoop:
216
"""Associated event loop."""
217
218
@property
219
def encoding(self) -> str:
220
"""Text encoding for non-binary files."""
221
222
@property
223
def mode(self) -> FileMode:
224
"""Parsed file mode information."""
225
```
226
227
### Context Management Functions
228
229
Functions for managing the underlying caio contexts that handle the actual asynchronous I/O operations.
230
231
```python { .api }
232
def create_context(
233
max_requests: int = caio.AsyncioContext.MAX_REQUESTS_DEFAULT
234
) -> caio.AsyncioContext:
235
"""
236
Create a new caio AsyncioContext.
237
238
Args:
239
max_requests: Maximum concurrent I/O requests
240
241
Returns:
242
New AsyncioContext instance
243
"""
244
245
def get_default_context() -> caio.AsyncioContext:
246
"""
247
Get or create the default caio context for current event loop.
248
249
Returns:
250
Default AsyncioContext for the current event loop
251
"""
252
```
253
254
### File Mode Parsing
255
256
```python { .api }
257
def parse_mode(mode: str) -> FileMode:
258
"""
259
Parse file mode string into structured FileMode object.
260
261
Args:
262
mode: File mode string (e.g., 'r', 'wb', 'a+')
263
264
Returns:
265
FileMode namedtuple with parsed mode information
266
267
Raises:
268
Exception: For invalid mode combinations
269
"""
270
271
class FileMode:
272
"""
273
Structured file mode information.
274
"""
275
readable: bool # File is readable
276
writable: bool # File is writable
277
plus: bool # Mode includes '+'
278
appending: bool # File is in append mode
279
created: bool # File should be created (exclusive)
280
flags: int # OS-level file flags
281
binary: bool # File is in binary mode
282
```
283
284
## Usage Examples
285
286
### Basic File Operations
287
288
```python
289
import asyncio
290
from aiofile import AIOFile
291
292
async def basic_operations():
293
# Open file for reading
294
async with AIOFile('data.txt', 'r') as afile:
295
# Read first 100 characters
296
chunk1 = await afile.read(100, 0)
297
298
# Read next 100 characters
299
chunk2 = await afile.read(100, 100)
300
301
# Read entire file from beginning
302
entire_file = await afile.read(-1, 0)
303
304
asyncio.run(basic_operations())
305
```
306
307
### Writing with Explicit Offsets
308
309
```python
310
import asyncio
311
from aiofile import AIOFile
312
313
async def write_operations():
314
async with AIOFile('output.txt', 'w') as afile:
315
# Write at beginning
316
await afile.write("Hello, ", 0)
317
318
# Write at offset 7
319
await afile.write("World!", 7)
320
321
# Force sync to disk
322
await afile.fsync()
323
324
asyncio.run(write_operations())
325
```
326
327
### Binary File Operations
328
329
```python
330
import asyncio
331
from aiofile import AIOFile
332
333
async def binary_operations():
334
async with AIOFile('data.bin', 'wb') as afile:
335
# Write binary data
336
data = b'\x00\x01\x02\x03\x04'
337
bytes_written = await afile.write_bytes(data, 0)
338
print(f"Wrote {bytes_written} bytes")
339
340
# Sync data to disk
341
await afile.fdsync()
342
343
asyncio.run(binary_operations())
344
```
345
346
## Constants
347
348
```python { .api }
349
AIO_FILE_NOT_OPENED = -1 # File state: not opened
350
AIO_FILE_CLOSED = -2 # File state: closed
351
352
FileIOType = Union[TextIO, BinaryIO] # Type alias for file objects
353
```