0
# File Management
1

2
Essential file and directory management operations including creation, deletion, content access, and batch operations. Provides comprehensive control over remote file systems with support for all rclone command options.
3

4
## Capabilities
5

6
### Directory Operations
7

8
Create and manage directories on local and remote file systems.
9

10
```python { .api }
11
def mkdir(path: str, args=None):
12
    """
13
    Creates directory if it doesn't already exist.
14
    
15
    Parameters:
16
    - path (str): Directory path to create ('remote:path' for remotes)
17
    - args (List[str]): Additional rclone mkdir flags
18
    
19
    Returns:
20
    None
21
    
22
    Raises:  
23
    RcloneException: If directory creation fails
24
    """
25
```
26

27
### File Deletion
28

29
Delete files while preserving directory structure, or remove directories and their contents completely.
30

31
```python { .api }
32
def delete(path: str, args=None):
33
    """
34
    Deletes files in a directory, preserving the directory structure itself.
35
    Removes all files in subdirectories but leaves empty directories.
36
    
37
    Parameters:
38
    - path (str): File or directory path to delete
39
    - args (List[str]): Additional rclone delete flags
40
    
41
    Returns:
42
    None
43
    
44
    Raises:
45
    RcloneException: If deletion fails
46
    """
47

48
def purge(path: str, args=None):
49
    """
50
    Completely removes directory and all its contents including subdirectories.
51
    Unlike delete, this removes the entire directory structure.
52
    
53
    Parameters:
54
    - path (str): Directory path to purge completely
55
    - args (List[str]): Additional rclone purge flags
56
    
57
    Returns:
58
    None
59
    
60
    Raises:
61
    RcloneException: If purge operation fails
62
    """
63
```
64

65
### File Content Access
66

67
Read and output file contents with flexible filtering and positioning options.
68

69
```python { .api }
70
def cat(path: str, count: Optional[int] = None, head: Optional[int] = None, 
71
        offset: Optional[int] = None, tail: Optional[int] = None, args=None) -> str:
72
    """
73
    Outputs contents of a single file with optional content filtering.
74
    
75
    Parameters:
76
    - path (str): File path to read ('remote:path' for remotes)
77
    - count (int, optional): Only output N characters total
78
    - head (int, optional): Only output first N characters  
79
    - offset (int, optional): Start output at character N (negative for end-relative)
80
    - tail (int, optional): Only output last N characters
81
    - args (List[str]): Additional rclone cat flags
82
    
83
    Returns:
84
    str: File contents as string
85
    
86
    Raises:
87
    RcloneException: If file read operation fails
88
    """
89
```
90

91
## Usage Examples
92

93
### Directory Management
94

95
```python
96
from rclone_python import rclone
97

98
# Create directory on remote
99
rclone.mkdir('onedrive:Projects/NewProject')
100

101
# Create nested directories
102
rclone.mkdir('dropbox:Archive/2024/Documents')
103

104
# Create with specific permissions (where supported)
105
rclone.mkdir('sftp_server:uploads', args=['--dir-perms', '0755'])
106
```
107

108
### File Deletion Operations
109

110
```python
111
from rclone_python import rclone
112

113
# Delete specific file
114
rclone.delete('box:old_document.txt')
115

116
# Delete all files in directory (preserves directory structure)
117
rclone.delete('onedrive:TempFiles')
118

119
# Completely remove directory and contents
120
rclone.purge('gdrive:OldProject')
121

122
# Delete with confirmation bypass
123
rclone.delete('backup:expired_files', args=['--dry-run'])  # Preview first
124
rclone.delete('backup:expired_files')  # Execute deletion
125
```
126

127
### File Content Operations
128

129
```python
130
from rclone_python import rclone
131

132
# Read entire file
133
file_content = rclone.cat('onedrive:config.txt')
134
print(file_content)
135

136
# Read first 1000 characters
137
header = rclone.cat('dropbox:large_file.log', head=1000)
138

139
# Read last 500 characters  
140
tail_content = rclone.cat('box:error.log', tail=500)
141

142
# Read specific section
143
middle_section = rclone.cat('gdrive:data.csv', offset=1000, count=500)
144

145
# Read from specific position to end
146
from_position = rclone.cat('remote:document.txt', offset=250)
147
```
148

149
### Batch Operations
150

151
```python
152
from rclone_python import rclone
153

154
# Create multiple directories
155
directories = ['Projects/Web', 'Projects/Mobile', 'Projects/Desktop']
156
for dir_path in directories:
157
    rclone.mkdir(f'onedrive:{dir_path}')
158

159
# Clean up temporary files
160
temp_patterns = ['*.tmp', '*.cache', '~*']
161
for pattern in temp_patterns:
162
    rclone.delete(f'workspace:temp/{pattern}', args=['--include', pattern])
163
```
164

165
### Safe Deletion with Verification
166

167
```python
168
from rclone_python import rclone
169

170
def safe_delete(path, confirm_size_mb=None):
171
    """Safely delete with size verification"""
172
    
173
    # Check what will be deleted
174
    try:
175
        size_info = rclone.size(path)
176
        total_size_mb = size_info['bytes'] / (1024 * 1024)
177
        
178
        print(f"Will delete {size_info['count']} files ({total_size_mb:.2f} MB)")
179
        
180
        # Confirm for large deletions
181
        if confirm_size_mb and total_size_mb > confirm_size_mb:
182
            confirm = input(f"Delete {total_size_mb:.2f} MB? (yes/no): ")
183
            if confirm.lower() != 'yes':
184
                print("Deletion cancelled")
185
                return
186
        
187
        # Perform deletion
188
        rclone.delete(path)
189
        print("Deletion completed successfully")
190
        
191
    except Exception as e:
192
        print(f"Deletion failed: {e}")
193

194
# Use safe deletion
195
safe_delete('onedrive:old_backups', confirm_size_mb=100)
196
```
197

198
### Content Processing
199

200
```python
201
from rclone_python import rclone
202
import json
203

204
def read_config_file(remote_path):
205
    """Read and parse JSON config file"""
206
    try:
207
        content = rclone.cat(remote_path)
208
        return json.loads(content)
209
    except json.JSONDecodeError:
210
        print("Invalid JSON in config file")
211
        return None
212
    except Exception as e:
213
        print(f"Failed to read config: {e}")
214
        return None
215

216
# Read configuration from remote
217
config = read_config_file('onedrive:app/config.json')
218
if config:
219
    print(f"Loaded config with {len(config)} settings")
220
```
221

222
### Log File Analysis
223

224
```python
225
from rclone_python import rclone
226

227
def analyze_log_file(log_path, error_pattern="ERROR"):
228
    """Analyze log file for errors"""
229
    
230
    # Get file size first
231
    files = rclone.ls(log_path.rsplit(':', 1)[0], files_only=True)
232
    log_file = next((f for f in files if f['Name'] == log_path.split(':')[-1]), None)
233
    
234
    if not log_file:
235
        print("Log file not found")
236
        return
237
    
238
    file_size = log_file['Size']
239
    print(f"Analyzing log file: {file_size} bytes")
240
    
241
    # Read last 10KB for recent errors
242
    recent_content = rclone.cat(log_path, tail=10240)
243
    
244
    # Count error occurrences
245
    error_lines = [line for line in recent_content.split('\n') if error_pattern in line]
246
    
247
    print(f"Found {len(error_lines)} error lines in recent activity")
248
    if error_lines:
249
        print("Most recent errors:")
250
        for line in error_lines[-5:]:  # Show last 5 errors
251
            print(f"  {line.strip()}")
252

253
# Analyze remote log file
254
analyze_log_file('server:logs/application.log')
255
```
256

257
### Directory Cleanup Workflows
258

259
```python
260
from rclone_python import rclone
261
from datetime import datetime, timedelta
262

263
def cleanup_old_files(base_path, days_old=30):
264
    """Clean up files older than specified days"""
265
    
266
    # List all files
267
    all_files = rclone.ls(base_path, files_only=True)
268
    
269
    cutoff_date = datetime.now() - timedelta(days=days_old)
270
    old_files = []
271
    
272
    for file in all_files:
273
        # Parse modification time
274
        mod_time = datetime.fromisoformat(file['ModTime'].replace('Z', '+00:00'))
275
        if mod_time.replace(tzinfo=None) < cutoff_date:
276
            old_files.append(file)
277
    
278
    if old_files:
279
        total_size = sum(f['Size'] for f in old_files)
280
        print(f"Found {len(old_files)} old files ({total_size / (1024**2):.2f} MB)")
281
        
282
        # Delete old files individually for better control
283
        for file in old_files:
284
            file_path = f"{base_path}/{file['Name']}" if not base_path.endswith(':') else f"{base_path}{file['Name']}"
285
            try:
286
                rclone.delete(file_path)
287
                print(f"Deleted: {file['Name']}")
288
            except Exception as e:
289
                print(f"Failed to delete {file['Name']}: {e}")
290
    else:
291
        print("No old files found")
292

293
# Clean up files older than 30 days
294
cleanup_old_files('onedrive:TempStorage', days_old=30)
295
```
296

297
## Advanced File Management Patterns
298

299
### Atomic Operations
300

301
```python
302
from rclone_python import rclone
303
import tempfile
304
import os
305

306
def atomic_file_update(remote_path, new_content):
307
    """Update remote file atomically via temporary file"""
308
    
309
    # Create temporary local file
310
    with tempfile.NamedTemporaryFile(mode='w', delete=False) as temp_file:
311
        temp_file.write(new_content)
312
        temp_path = temp_file.name
313
    
314
    try:
315
        # Upload to temporary remote location
316
        temp_remote = f"{remote_path}.tmp"
317
        rclone.copy(temp_path, temp_remote)
318
        
319
        # Move to final location (atomic on most backends)
320
        rclone.moveto(temp_remote, remote_path)
321
        
322
        print(f"Atomically updated {remote_path}")
323
        
324
    finally:
325
        # Clean up local temporary file
326
        os.unlink(temp_path)
327

328
# Update configuration file atomically
329
new_config = '{"version": "2.0", "enabled": true}'
330
atomic_file_update('onedrive:app/config.json', new_config)
331
```
332

333
### Directory Synchronization Cleanup
334

335
```python
336
from rclone_python import rclone
337

338
def clean_sync_destination(src_path, dest_path):
339
    """Remove files from destination that don't exist in source"""
340
    
341
    # Get source files
342
    src_files = {f['Name'] for f in rclone.ls(src_path, files_only=True)}
343
    
344
    # Get destination files  
345
    dest_files = rclone.ls(dest_path, files_only=True)
346
    
347
    # Find files to remove
348
    to_remove = [f for f in dest_files if f['Name'] not in src_files]
349
    
350
    if to_remove:
351
        print(f"Removing {len(to_remove)} orphaned files from destination")
352
        for file in to_remove:
353
            file_path = f"{dest_path}/{file['Name']}"
354
            rclone.delete(file_path)
355
            print(f"Removed: {file['Name']}")
356
    else:
357
        print("No orphaned files found in destination")
358

359
# Clean destination to match source
360
clean_sync_destination('local:source_dir', 'onedrive:backup_dir')
361
```