0
# Configuration and System
1

2
System-level operations including installation checking, version management, configuration file handling, and logging control. Essential functions for environment setup and system integration.
3

4
## Capabilities
5

6
### Installation and Version Management
7

8
Check rclone installation status and retrieve version information with optional update checking.
9

10
```python { .api }
11
def is_installed() -> bool:
12
    """
13
    Checks if rclone is properly installed and accessible in system PATH.
14
    
15
    Returns:
16
    bool: True if rclone command is available, False otherwise
17
    """
18

19
def version(check=False, args: List[str] = None) -> Union[str, Tuple[str]]:
20
    """
21
    Retrieves rclone version information with optional update checking.
22
    
23
    Parameters:
24
    - check (bool): Perform online check for latest versions
25
    - args (List[str]): Additional rclone version flags
26
    
27
    Returns:
28
    - str: Current version string when check=False
29
    - Tuple[str, str, str]: (current, latest, beta) when check=True
30
      Returns (current, None, None) if online check fails
31
    
32
    Raises:
33
    RcloneException: If version command fails
34
    """
35
```
36

37
### Configuration Management
38

39
Control rclone configuration file location and logging behavior for the wrapper.
40

41
```python { .api }
42
def set_config_file(config_file: str):
43
    """
44
    Sets custom rclone configuration file path for all subsequent operations.
45
    
46
    Parameters:
47
    - config_file (str): Path to custom rclone config file
48
    
49
    Returns:
50
    None
51
    
52
    Note:
53
    Uses singleton pattern - setting persists for entire application session
54
    """
55

56
def set_log_level(level: int):
57
    """
58
    Sets logging level for the rclone-python wrapper.
59
    
60
    Parameters:
61
    - level (int): Python logging level (e.g., logging.DEBUG, logging.INFO)
62
    
63
    Returns:
64
    None
65
    """
66
```
67

68
## Usage Examples
69

70
### Installation Verification
71

72
```python
73
from rclone_python import rclone
74

75
# Check if rclone is installed
76
if rclone.is_installed():
77
    print("✓ rclone is installed and ready")
78
    
79
    # Get version information
80
    current_version = rclone.version()
81
    print(f"Current version: {current_version}")
82
else:
83
    print("✗ rclone is not installed")
84
    print("Please install rclone from: https://rclone.org/")
85
    exit(1)
86
```
87

88
### Version Management
89

90
```python
91
from rclone_python import rclone
92

93
# Get current version only
94
current = rclone.version()
95
print(f"Installed version: {current}")
96

97
# Check for updates (requires internet connection)
98
try:
99
    current, latest, beta = rclone.version(check=True)
100
    print(f"Current: {current}")
101
    print(f"Latest stable: {latest}")  
102
    print(f"Latest beta: {beta}")
103
    
104
    if latest and current != latest:
105
        print("🔄 Update available!")
106
    else:
107
        print("✓ Running latest version")
108
        
109
except Exception as e:
110
    print(f"Update check failed: {e}")
111
```
112

113
### Custom Configuration Setup
114

115
```python
116
from rclone_python import rclone
117
import os
118
from pathlib import Path
119

120
# Set up custom config directory
121
config_dir = Path.home() / '.config' / 'myapp' / 'rclone'
122
config_dir.mkdir(parents=True, exist_ok=True)
123
config_file = config_dir / 'rclone.conf'
124

125
# Use custom config file
126
rclone.set_config_file(str(config_file))
127
print(f"Using config file: {config_file}")
128

129
# Verify config is being used
130
remotes = rclone.get_remotes()
131
print(f"Configured remotes: {remotes}")
132

133
# Later operations will use this config file automatically
134
rclone.create_remote('myremote', rclone.RemoteTypes.onedrive)
135
```
136

137
### Logging Configuration
138

139
```python
140
from rclone_python import rclone
141
import logging
142

143
# Set up debug logging to see all rclone commands
144
rclone.set_log_level(logging.DEBUG)
145

146
# Test with a simple operation
147
print("Debug logging enabled - you'll see rclone commands:")
148
rclone.copy('local_file.txt', 'onedrive:backup/')
149

150
# Reduce logging for production
151
rclone.set_log_level(logging.WARNING)
152
print("Logging reduced to warnings and errors only")
153
```
154

155
### Environment Setup Automation
156

157
```python
158
from rclone_python import rclone
159
from rclone_python.remote_types import RemoteTypes
160
import logging
161
import sys
162
import os
163

164
def setup_rclone_environment(config_path=None, log_level=logging.INFO):
165
    """Complete rclone environment setup and validation"""
166
    
167
    print("Setting up rclone environment...")
168
    
169
    # 1. Check installation
170
    if not rclone.is_installed():
171
        print("✗ rclone not found in PATH")
172
        print("Install from: https://rclone.org/install/")
173
        return False
174
    
175
    print("✓ rclone installation found")
176
    
177
    # 2. Check version
178
    try:
179
        version = rclone.version()
180
        print(f"✓ rclone version: {version}")
181
        
182
        # Optionally check for updates
183
        if os.getenv('CHECK_UPDATES', '').lower() == 'true':
184
            current, latest, beta = rclone.version(check=True)
185
            if latest and current != latest:
186
                print(f"⚠ Update available: {current} → {latest}")
187
    
188
    except Exception as e:
189
        print(f"⚠ Version check failed: {e}")
190
    
191
    # 3. Set up logging
192
    rclone.set_log_level(log_level)
193
    print(f"✓ Logging level set to: {logging.getLevelName(log_level)}")
194
    
195
    # 4. Configure custom config file if provided
196
    if config_path:
197
        rclone.set_config_file(config_path)
198
        print(f"✓ Using config file: {config_path}")
199
    
200
    # 5. List available remotes
201
    try:
202
        remotes = rclone.get_remotes()
203
        if remotes:
204
            print(f"✓ Found {len(remotes)} configured remotes: {remotes}")
205
        else:
206
            print("ℹ No remotes configured yet")
207
    except Exception as e:
208
        print(f"⚠ Could not list remotes: {e}")
209
    
210
    print("✓ rclone environment setup complete")
211
    return True
212

213
# Set up environment
214
success = setup_rclone_environment(
215
    config_path=os.path.expanduser('~/.config/myapp/rclone.conf'),
216
    log_level=logging.INFO
217
)
218

219
if not success:
220
    sys.exit(1)
221
```
222

223
### Application Integration
224

225
```python
226
from rclone_python import rclone
227
import logging
228
import atexit
229
import tempfile
230
import shutil
231

232
class RcloneManager:
233
    """Manage rclone configuration for an application"""
234
    
235
    def __init__(self, app_name, debug=False):
236
        self.app_name = app_name
237
        self.temp_config = None
238
        
239
        # Set up logging
240
        log_level = logging.DEBUG if debug else logging.INFO
241
        rclone.set_log_level(log_level)
242
        
243
        # Verify rclone is available
244
        if not rclone.is_installed():
245
            raise RuntimeError("rclone is not installed")
246
        
247
        # Get version info
248
        self.version = rclone.version()
249
        print(f"Using rclone {self.version}")
250
    
251
    def use_temp_config(self):
252
        """Use a temporary config file (useful for testing)"""
253
        self.temp_config = tempfile.NamedTemporaryFile(
254
            mode='w', 
255
            suffix='.conf', 
256
            prefix=f'{self.app_name}_rclone_',
257
            delete=False
258
        )
259
        self.temp_config.close()
260
        
261
        rclone.set_config_file(self.temp_config.name)
262
        print(f"Using temporary config: {self.temp_config.name}")
263
        
264
        # Clean up on exit
265
        atexit.register(self.cleanup)
266
    
267
    def use_app_config(self, config_dir=None):
268
        """Use application-specific config directory"""
269
        if not config_dir:
270
            config_dir = Path.home() / '.config' / self.app_name
271
        
272
        config_dir = Path(config_dir)
273
        config_dir.mkdir(parents=True, exist_ok=True)
274
        
275
        config_file = config_dir / 'rclone.conf'
276
        rclone.set_config_file(str(config_file))
277
        print(f"Using app config: {config_file}")
278
    
279
    def health_check(self):
280
        """Perform basic health check"""
281
        try:
282
            # Test version command
283
            version = rclone.version()
284
            
285
            # Test listing remotes
286
            remotes = rclone.get_remotes()
287
            
288
            return {
289
                'status': 'healthy',
290
                'version': version,
291
                'remotes': len(remotes),
292
                'remote_list': remotes
293
            }
294
            
295
        except Exception as e:
296
            return {
297
                'status': 'unhealthy',
298
                'error': str(e)
299
            }
300
    
301
    def cleanup(self):
302
        """Clean up temporary resources"""
303
        if self.temp_config and os.path.exists(self.temp_config.name):
304
            os.unlink(self.temp_config.name)
305
            print(f"Cleaned up temporary config: {self.temp_config.name}")
306

307
# Usage example
308
manager = RcloneManager('myapp', debug=True)
309
manager.use_app_config()
310

311
# Perform health check
312
health = manager.health_check()
313
print(f"Health check: {health}")
314
```
315

316
### System Integration Patterns
317

318
```python
319
from rclone_python import rclone
320
import sys
321
import subprocess
322
import platform
323

324
def system_integration_check():
325
    """Comprehensive system integration verification"""
326
    
327
    print("Performing system integration check...")
328
    
329
    # 1. Check rclone installation
330
    if not rclone.is_installed():
331
        print("✗ rclone not found")
332
        return False
333
    
334
    # 2. Check system details
335
    system_info = {
336
        'platform': platform.system(),
337
        'architecture': platform.machine(),
338
        'python_version': sys.version.split()[0]
339
    }
340
    
341
    print(f"✓ System: {system_info['platform']} {system_info['architecture']}")
342
    print(f"✓ Python: {system_info['python_version']}")
343
    
344
    # 3. Check rclone details
345
    try:
346
        version = rclone.version()
347
        print(f"✓ rclone: {version}")
348
        
349
        # Check if it's in PATH
350
        rclone_path = subprocess.run(
351
            ['which', 'rclone'] if system_info['platform'] != 'Windows' else ['where', 'rclone'],
352
            capture_output=True, text=True
353
        )
354
        
355
        if rclone_path.returncode == 0:
356
            print(f"✓ rclone path: {rclone_path.stdout.strip()}")
357
    
358
    except Exception as e:
359
        print(f"⚠ rclone check failed: {e}")
360
        return False
361
    
362
    # 4. Test basic operations
363
    try:
364
        remotes = rclone.get_remotes()
365
        print(f"✓ Basic operations working (found {len(remotes)} remotes)")
366
    except Exception as e:
367
        print(f"⚠ Basic operations failed: {e}")
368
        return False
369
    
370
    print("✓ System integration check passed")
371
    return True
372

373
# Run integration check
374
if __name__ == "__main__":
375
    success = system_integration_check()
376
    sys.exit(0 if success else 1)
377
```
378

379
## Configuration File Management
380

381
The wrapper uses a singleton pattern for configuration management:
382

383
```python
384
from rclone_python import rclone
385
from rclone_python.utils import Config
386

387
# The Config class is a singleton
388
config1 = Config('/path/to/config1.conf')
389
config2 = Config('/path/to/config2.conf')  # This won't change the path
390

391
# config1 and config2 are the same instance
392
print(config1 is config2)  # True
393

394
# To change config, use the set_config_file function
395
rclone.set_config_file('/path/to/new_config.conf')
396
```
397

398
## Environment Variables
399

400
While not directly exposed by the wrapper, you can influence rclone behavior through environment variables:
401

402
```python
403
import os
404
from rclone_python import rclone
405

406
# Set rclone environment variables before operations
407
os.environ['RCLONE_CONFIG'] = '/custom/path/rclone.conf'
408
os.environ['RCLONE_CACHE_DIR'] = '/tmp/rclone_cache'
409
os.environ['RCLONE_VERBOSE'] = '1'
410

411
# These will affect rclone behavior
412
rclone.copy('source', 'dest')
413
```
414

415
## Error Handling and Diagnostics
416

417
```python
418
from rclone_python import rclone
419
from rclone_python.utils import RcloneException
420
import logging
421

422
def diagnose_rclone_issues():
423
    """Diagnose common rclone issues"""
424
    
425
    issues = []
426
    
427
    # Check installation
428
    if not rclone.is_installed():
429
        issues.append("rclone not found in PATH")
430
        return issues
431
    
432
    # Check version accessibility
433
    try:
434
        version = rclone.version()
435
    except RcloneException as e:
436
        issues.append(f"Version command failed: {e}")
437
        return issues
438
    
439
    # Check remote listing
440
    try:
441
        remotes = rclone.get_remotes()
442
    except RcloneException as e:
443
        issues.append(f"Cannot list remotes: {e}")
444
    
445
    # Check logging
446
    try:
447
        rclone.set_log_level(logging.DEBUG)
448
        rclone.set_log_level(logging.INFO)  # Reset
449
    except Exception as e:
450
        issues.append(f"Logging configuration failed: {e}")
451
    
452
    return issues
453

454
# Run diagnostics
455
problems = diagnose_rclone_issues()
456
if problems:
457
    print("Issues found:")
458
    for issue in problems:
459
        print(f"  - {issue}")
460
else:
461
    print("✓ No issues detected")
462
```