0
# rclone-python
1

2
A comprehensive Python wrapper for the rclone command-line tool that enables programmatic access to cloud storage operations. It provides a rich, Python-native interface for copying, moving, syncing files across 70+ cloud storage providers with progress tracking, authentication management, and comprehensive error handling.
3

4
## Package Information
5

6
- **Package Name**: rclone-python
7
- **Language**: Python
8
- **Installation**: `pip install rclone-python`
9
- **Prerequisites**: rclone must be installed on the system
10

11
## Core Imports
12

13
```python
14
from rclone_python import rclone
15
```
16

17
For hash types and remote types:
18

19
```python
20
from rclone_python.hash_types import HashTypes
21
from rclone_python.remote_types import RemoteTypes
22
```
23

24
For exceptions:
25

26
```python
27
from rclone_python.utils import RcloneException
28
```
29

30
## Basic Usage
31

32
```python
33
from rclone_python import rclone
34
from rclone_python.remote_types import RemoteTypes
35

36
# Check if rclone is installed
37
if rclone.is_installed():
38
    # Create a new remote for OneDrive
39
    rclone.create_remote('onedrive', RemoteTypes.onedrive)
40
    
41
    # Copy files from OneDrive to local directory
42
    rclone.copy('onedrive:data', 'local_data', show_progress=True)
43
    
44
    # List files in a remote directory
45
    files = rclone.ls('onedrive:data', max_depth=1, files_only=True)
46
    
47
    # Sync local directory to remote
48
    rclone.sync('local_data', 'onedrive:backup')
49
```
50

51
## Architecture
52

53
The rclone-python wrapper is built around several key components:
54

55
- **Main rclone module**: Core functions for all file operations, remote management, and system interaction
56
- **Type definitions**: Enums for hash algorithms (HashTypes) and cloud providers (RemoteTypes)
57
- **Progress tracking**: Rich-based progress bars with real-time transfer statistics and file-level detail
58
- **Configuration management**: Singleton pattern for custom config file paths and logging levels
59
- **Error handling**: Custom RcloneException with detailed error information
60

61
The wrapper maintains compatibility with all rclone command-line options while providing Python-native interfaces, progress callbacks, and structured return values.
62

63
## Capabilities
64

65
### File Transfer Operations
66

67
Core transfer functionality including copy, move, and sync operations with progress tracking, custom progress bars, and event listeners for real-time transfer monitoring.
68

69
```python { .api }
70
def copy(in_path: str, out_path: str, ignore_existing=False, show_progress=True, 
71
         listener: Callable[[Dict], None] = None, args=None, pbar=None): ...
72
def move(in_path: str, out_path: str, ignore_existing=False, show_progress=True,
73
         listener: Callable[[Dict], None] = None, args=None, pbar=None): ...
74
def sync(src_path: str, dest_path: str, show_progress=True,
75
         listener: Callable[[Dict], None] = None, args=None, pbar=None): ...
76
```
77

78
[File Transfer Operations](./file-transfer.md)
79

80
### Remote Management
81

82
Functions for creating, configuring, and managing cloud storage remotes with OAuth authentication support and comprehensive remote validation.
83

84
```python { .api }
85
def create_remote(remote_name: str, remote_type: Union[str, RemoteTypes], 
86
                  client_id: Union[str, None] = None, client_secret: Union[str, None] = None, **kwargs): ...
87
def get_remotes() -> List[str]: ...
88
def check_remote_existing(remote_name: str) -> bool: ...
89
```
90

91
[Remote Management](./remote-management.md)
92

93
### File Listing and Information
94

95
Comprehensive file system operations including directory listing, file metadata, storage quotas, and tree-style directory visualization.
96

97
```python { .api }
98
def ls(path: str, max_depth: Union[int, None] = None, dirs_only=False, 
99
       files_only=False, args=None) -> List[Dict[str, Union[int, str]]]: ...
100
def about(path: str) -> Dict: ...
101
def size(path: str, args: List[str] = None) -> Dict: ...
102
def tree(path: str, args: List[str] = None) -> str: ...
103
```
104

105
[File Listing and Information](./file-listing.md)
106

107
### File Management Operations
108

109
Essential file management functions including directory creation, file deletion, content output, and batch operations with comprehensive argument support.
110

111
```python { .api }
112
def mkdir(path: str, args=None): ...
113
def delete(path: str, args=None): ...
114
def purge(path: str, args=None): ...
115
def cat(path: str, count: Optional[int] = None, head: Optional[int] = None, 
116
        offset: Optional[int] = None, tail: Optional[int] = None, args=None) -> str: ...
117
```
118

119
[File Management](./file-management.md)
120

121
### Hash Operations and Verification
122

123
Data integrity operations including hash generation, validation, and file comparison with support for multiple hash algorithms and checksum verification.
124

125
```python { .api }
126
def hash(hash: Union[str, HashTypes], path: str, download=False, 
127
         checkfile: Optional[str] = None, output_file: Optional[str] = None,
128
         args: List[str] = None) -> Union[None, str, bool, Dict[str, str], Dict[str, bool]]: ...
129
def check(source: str, dest: str, combined: str = None, size_only: bool = False,
130
          download: bool = False, one_way: bool = False, args: List[str] = None
131
          ) -> Tuple[bool, List[Tuple[str, str]]]: ...
132
```
133

134
[Hash Operations](./hash-operations.md)
135

136
### Public Link Management
137

138
Functions for generating, managing, and removing public links to files and directories with expiration support where available.
139

140
```python { .api }
141
def link(path: str, expire: Union[str, None] = None, unlink=False, args=None) -> str: ...
142
```
143

144
[Public Links](./public-links.md)
145

146
### Configuration and System
147

148
System-level operations including installation checking, version management, configuration file handling, and logging control.
149

150
```python { .api }
151
def is_installed() -> bool: ...
152
def version(check=False, args: List[str] = None) -> Union[str, Tuple[str]]: ...
153
def set_config_file(config_file: str): ...
154
def set_log_level(level: int): ...
155
```
156

157
[Configuration and System](./configuration.md)
158

159
## Types
160

161
### Core Types
162

163
```python { .api }
164
from typing import Dict, List, Union, Optional, Callable, Tuple
165

166
# Progress listener callback type
167
ProgressListener = Callable[[Dict], None]
168

169
# Transfer operation parameters
170
TransferArgs = Optional[List[str]]
171
```
172

173
### Hash Types
174

175
```python { .api }
176
from enum import Enum
177

178
class HashTypes(Enum):
179
    crc32 = "crc32"
180
    dropbox = "dropbox" 
181
    hidrive = "hidrive"
182
    mailru = "mailru"
183
    md5 = "md5"
184
    quickxor = "quickxor"
185
    sha1 = "sha1"
186
    sha256 = "sha256"
187
    sha512 = "sha512"
188
    whirlpool = "whirlpool"
189
```
190

191
### Remote Types
192

193
```python { .api }
194
from enum import Enum
195

196
class RemoteTypes(Enum):
197
    # Major cloud providers
198
    onedrive = "onedrive"
199
    drive = "drive"  # Google Drive
200
    dropbox = "dropbox"
201
    box = "box"
202
    s3 = "s3"  # Amazon S3
203
    azureblob = "azureblob"
204
    
205
    # Storage systems (72 total providers supported)
206
    local = "local"
207
    sftp = "sftp"
208
    ftp = "ftp"
209
    webdav = "webdav"
210
    # ... and 65+ additional cloud storage providers
211
```
212

213
### Exception Types
214

215
```python { .api }
216
class RcloneException(ChildProcessError):
217
    def __init__(self, description: str, error_msg: str): ...
218
    
219
    # Properties
220
    description: str  # High-level error description
221
    error_msg: str    # Detailed error message from rclone
222
```