0
# File I/O Operations
1

2
Comprehensive file input/output capabilities with support for text and binary modes, streaming operations, and cloud-specific optimizations. All file operations automatically handle cloud storage specifics like authentication, caching, and efficient data transfer.
3

4
## Capabilities
5

6
### File Opening
7

8
Open cloud files with familiar Python file I/O patterns.
9

10
```python { .api }
11
def open(
12
    self,
13
    mode: str = "r",
14
    buffering: int = -1,
15
    encoding: typing.Optional[str] = None,
16
    errors: typing.Optional[str] = None,
17
    newline: typing.Optional[str] = None,
18
    force_overwrite_from_cloud: typing.Optional[bool] = None,
19
    force_overwrite_to_cloud: typing.Optional[bool] = None
20
) -> typing.IO:
21
    """
22
    Open cloud file for reading or writing.
23
    
24
    Args:
25
        mode: File mode ('r', 'w', 'a', 'rb', 'wb', 'ab')
26
        buffering: Buffer size (-1 for default)
27
        encoding: Text encoding (for text modes)
28
        errors: Error handling strategy
29
        newline: Newline handling
30
        force_overwrite_from_cloud: Force refresh from cloud storage
31
        force_overwrite_to_cloud: Force upload to cloud storage
32
        
33
    Returns:
34
        File object compatible with built-in open()
35
    """
36
```
37

38
### Text File Operations
39

40
Read and write text content with automatic encoding handling.
41

42
```python { .api }
43
def read_text(
44
    self,
45
    encoding: str = None,
46
    errors: str = None
47
) -> str:
48
    """
49
    Read entire file as text.
50
    
51
    Args:
52
        encoding: Text encoding (default: utf-8)
53
        errors: Error handling ('strict', 'ignore', 'replace')
54
        
55
    Returns:
56
        File contents as string
57
    """
58

59
def write_text(
60
    self,
61
    data: str,
62
    encoding: str = None,
63
    errors: str = None,
64
    newline: str = None
65
) -> int:
66
    """
67
    Write text data to file.
68
    
69
    Args:
70
        data: Text content to write
71
        encoding: Text encoding (default: utf-8)
72
        errors: Error handling strategy
73
        newline: Newline handling
74
        
75
    Returns:
76
        Number of characters written
77
    """
78
```
79

80
### Binary File Operations
81

82
Handle binary data with efficient streaming and memory management.
83

84
```python { .api }
85
def read_bytes(self) -> bytes:
86
    """
87
    Read entire file as bytes.
88
    
89
    Returns:
90
        File contents as bytes
91
    """
92

93
def write_bytes(self, data: bytes) -> int:
94
    """
95
    Write binary data to file.
96
    
97
    Args:
98
        data: Binary content to write
99
        
100
    Returns:
101
        Number of bytes written
102
    """
103
```
104

105
### File Metadata
106

107
Access file information and properties.
108

109
```python { .api }
110
def stat(self) -> "os.stat_result":
111
    """
112
    Get file statistics.
113
    
114
    Returns:
115
        os.stat_result object with file metadata
116
        Fields include: st_size, st_mtime, st_mode
117
    """
118

119
def touch(self, exist_ok: bool = True) -> None:
120
    """
121
    Create file or update timestamp.
122
    
123
    Args:
124
        exist_ok: Don't raise error if file exists
125
    """
126
```
127

128
## Usage Examples
129

130
### Basic File Reading
131

132
```python
133
from cloudpathlib import CloudPath
134

135
path = CloudPath("s3://my-bucket/data.txt")
136

137
# Read entire file as text
138
content = path.read_text()
139
print(content)
140

141
# Read with specific encoding
142
content = path.read_text(encoding='utf-8')
143

144
# Read binary data
145
binary_data = path.read_bytes()
146
```
147

148
### Basic File Writing
149

150
```python
151
path = CloudPath("s3://my-bucket/output.txt")
152

153
# Write text
154
path.write_text("Hello, cloud storage!")
155

156
# Write with specific encoding
157
path.write_text("Hello, world! 🌍", encoding='utf-8')
158

159
# Write binary data
160
path.write_bytes(b"Binary content")
161
```
162

163
### Streaming File Operations
164

165
```python
166
# Stream reading for large files
167
path = CloudPath("s3://my-bucket/large-file.txt")
168

169
with path.open('r') as f:
170
    for line in f:
171
        process_line(line)
172

173
# Stream writing
174
path = CloudPath("s3://my-bucket/output.txt")
175

176
with path.open('w') as f:
177
    f.write("Line 1\n")
178
    f.write("Line 2\n")
179
    f.flush()  # Force upload
180
```
181

182
### Binary File Handling
183

184
```python
185
# Read binary file in chunks
186
path = CloudPath("s3://my-bucket/image.jpg")
187

188
with path.open('rb') as f:
189
    while True:
190
        chunk = f.read(8192)  # 8KB chunks
191
        if not chunk:
192
            break
193
        process_chunk(chunk)
194

195
# Write binary data
196
path = CloudPath("s3://my-bucket/data.bin")
197

198
with path.open('wb') as f:
199
    f.write(b'\x00\x01\x02\x03')
200
```
201

202
### File Modes and Options
203

204
```python
205
path = CloudPath("s3://my-bucket/file.txt")
206

207
# Different file modes
208
with path.open('r') as f:      # Read text
209
    content = f.read()
210

211
with path.open('rb') as f:     # Read binary
212
    data = f.read()
213

214
with path.open('w') as f:      # Write text (overwrites)
215
    f.write("New content")
216

217
with path.open('a') as f:      # Append text
218
    f.write("Additional content")
219

220
with path.open('wb') as f:     # Write binary
221
    f.write(b"Binary data")
222
```
223

224
### Advanced File Operations
225

226
```python
227
# Check file properties
228
path = CloudPath("s3://my-bucket/file.txt")
229

230
if path.exists():
231
    # Get file statistics
232
    stats = path.stat()
233
    print(f"Size: {stats.st_size} bytes")
234
    print(f"Modified: {stats.st_mtime}")
235
    
236
    # Create/update file timestamp
237
    path.touch()
238
```
239

240
### Error Handling
241

242
```python
243
from cloudpathlib import CloudPathFileNotFoundError
244

245
path = CloudPath("s3://my-bucket/nonexistent.txt")
246

247
try:
248
    content = path.read_text()
249
except CloudPathFileNotFoundError:
250
    print("File not found")
251
except PermissionError:
252
    print("Access denied")
253

254
# Safe file operations
255
if path.exists():
256
    content = path.read_text()
257
else:
258
    print("File does not exist")
259
```
260

261
### Working with Different Encodings
262

263
```python
264
# UTF-8 text (default)
265
path = CloudPath("s3://my-bucket/utf8.txt")
266
path.write_text("Hello 世界", encoding='utf-8')
267
content = path.read_text(encoding='utf-8')
268

269
# Other encodings
270
path = CloudPath("s3://my-bucket/latin1.txt")
271
path.write_text("Café", encoding='latin-1')
272
content = path.read_text(encoding='latin-1')
273

274
# Handle encoding errors
275
try:
276
    content = path.read_text(encoding='ascii', errors='strict')
277
except UnicodeDecodeError:
278
    content = path.read_text(encoding='ascii', errors='ignore')
279
```
280

281
### Context Manager Usage
282

283
```python
284
# Automatic resource cleanup
285
path = CloudPath("s3://my-bucket/data.txt")
286

287
# Text operations
288
with path.open('w', encoding='utf-8') as f:
289
    f.write("Content is automatically uploaded when context exits")
290

291
# Binary operations
292
with path.open('rb') as f:
293
    data = f.read(1024)  # Read first 1KB
294

295
# Multiple operations
296
with path.open('a') as f:
297
    f.write("Line 1\n")
298
    f.write("Line 2\n")
299
    # File is automatically closed and uploaded
300
```