0
# File Transfer Operations
1

2
Core transfer functionality for copying, moving, and synchronizing files and directories between local and remote storage locations. All transfer operations support progress tracking, custom progress bars, event listeners, and comprehensive error handling.
3

4
## Capabilities
5

6
### Copy Operations
7

8
Copy files and directories from source to destination without removing the originals. Supports selective copying with ignore options and comprehensive progress monitoring.
9

10
```python { .api }
11
def copy(in_path: str, out_path: str, ignore_existing=False, show_progress=True, 
12
         listener: Callable[[Dict], None] = None, args=None, pbar=None):
13
    """
14
    Copies files or directories from source to destination path.
15
    
16
    Parameters:
17
    - in_path (str): Source path. Use 'remote_name:path_on_remote' for remotes
18
    - out_path (str): Destination path. Use 'remote_name:path_on_remote' for remotes  
19
    - ignore_existing (bool): If True, skip existing files without overwriting
20
    - show_progress (bool): Display progress bar during transfer
21
    - listener (Callable[[Dict], None]): Event callback for transfer progress updates
22
    - args (List[str]): Additional rclone command flags
23
    - pbar (rich.Progress): Custom progress bar instance
24
    
25
    Returns:
26
    None
27
    
28
    Raises:
29
    RcloneException: If the copy operation fails
30
    """
31

32
def copyto(in_path: str, out_path: str, ignore_existing=False, show_progress=True,
33
           listener: Callable[[Dict], None] = None, args=None, pbar=None):
34
    """
35
    Copies with renaming capability, typically used for single file operations.
36
    
37
    Parameters:
38
    - in_path (str): Source file path
39
    - out_path (str): Destination file path (may include new filename)
40
    - ignore_existing (bool): If True, skip if destination exists
41
    - show_progress (bool): Display progress bar during transfer
42
    - listener (Callable[[Dict], None]): Event callback for progress updates
43
    - args (List[str]): Additional rclone command flags
44
    - pbar (rich.Progress): Custom progress bar instance
45
    
46
    Returns:
47
    None
48
    
49
    Raises:
50
    RcloneException: If the copy operation fails
51
    """
52
```
53

54
### Move Operations
55

56
Move files and directories from source to destination, removing them from the source location. Like copy operations but with source cleanup.
57

58
```python { .api }
59
def move(in_path: str, out_path: str, ignore_existing=False, show_progress=True,
60
         listener: Callable[[Dict], None] = None, args=None, pbar=None):
61
    """
62
    Moves files or directories from source to destination, removing originals.
63
    
64
    Parameters:
65
    - in_path (str): Source path to move from
66
    - out_path (str): Destination path to move to
67
    - ignore_existing (bool): If True, skip existing files without overwriting
68
    - show_progress (bool): Display progress bar during transfer
69
    - listener (Callable[[Dict], None]): Event callback for progress updates
70
    - args (List[str]): Additional rclone command flags
71
    - pbar (rich.Progress): Custom progress bar instance
72
    
73
    Returns:
74
    None
75
    
76
    Raises:
77
    RcloneException: If the move operation fails
78
    """
79

80
def moveto(in_path: str, out_path: str, ignore_existing=False, show_progress=True,
81
           listener: Callable[[Dict], None] = None, args=None, pbar=None):
82
    """
83
    Moves with renaming capability for single file operations.
84
    
85
    Parameters:
86
    - in_path (str): Source file path
87
    - out_path (str): Destination file path (may include new filename)
88
    - ignore_existing (bool): If True, skip if destination exists
89
    - show_progress (bool): Display progress bar during transfer
90
    - listener (Callable[[Dict], None]): Event callback for progress updates
91
    - args (List[str]): Additional rclone command flags
92
    - pbar (rich.Progress): Custom progress bar instance
93
    
94
    Returns:
95
    None
96
    
97
    Raises:
98
    RcloneException: If the move operation fails
99
    """
100
```
101

102
### Sync Operations
103

104
Synchronize source to destination, making destination identical to source. Only transfers files that differ, optimizing for minimal data transfer.
105

106
```python { .api }
107
def sync(src_path: str, dest_path: str, show_progress=True,
108
         listener: Callable[[Dict], None] = None, args=None, pbar=None):
109
    """
110
    Synchronizes source to destination, changing destination only.
111
    Files identical in size and modification time or MD5SUM are not transferred.
112
    
113
    Parameters:
114
    - src_path (str): Source path to sync from
115
    - dest_path (str): Destination path to sync to
116
    - show_progress (bool): Display progress bar during sync
117
    - listener (Callable[[Dict], None]): Event callback for progress updates
118
    - args (List[str]): Additional rclone command flags
119
    - pbar (rich.Progress): Custom progress bar instance
120
    
121
    Returns:
122
    None
123
    
124
    Raises:
125
    RcloneException: If the sync operation fails
126
    """
127
```
128

129
## Usage Examples
130

131
### Basic File Copy
132

133
```python
134
from rclone_python import rclone
135

136
# Copy local directory to OneDrive
137
rclone.copy('local_folder', 'onedrive:backup_folder')
138

139
# Copy with existing file handling
140
rclone.copy('documents', 'box:documents', ignore_existing=True)
141
```
142

143
### Progress Monitoring
144

145
```python
146
from rclone_python import rclone
147

148
def progress_callback(update_dict):
149
    """Handle transfer progress updates"""
150
    total_progress = update_dict['progress'] * 100
151
    transfer_speed = update_dict['transfer_speed']
152
    print(f"Progress: {total_progress:.1f}% at {transfer_speed} bytes/sec")
153

154
# Copy with progress listener
155
rclone.copy('large_files', 'dropbox:backup', listener=progress_callback)
156
```
157

158
### Custom Progress Bar
159

160
```python
161
from rclone_python import rclone
162
from rich.progress import Progress, TextColumn, BarColumn, TransferSpeedColumn
163

164
# Create custom progress bar
165
with Progress(
166
    TextColumn("[progress.description]{task.description}"),
167
    BarColumn(),
168
    TransferSpeedColumn(),
169
) as progress:
170
    rclone.copy('data', 'remote:backup', pbar=progress)
171
```
172

173
### Sync with Additional Options
174

175
```python
176
from rclone_python import rclone
177

178
# Sync with additional rclone flags
179
rclone.sync(
180
    'local_data', 
181
    'onedrive:sync_backup',
182
    args=['--create-empty-src-dirs', '--delete-excluded']
183
)
184
```
185

186
## Progress Callback Data Structure
187

188
The listener callback receives a dictionary with the following structure:
189

190
```python
191
{
192
    "tasks": [
193
        {
194
            "name": str,              # Individual file name
195
            "total": int,             # File size in bytes
196
            "sent": int,              # Bytes transferred
197
            "progress": float,        # File progress (0.0-1.0)
198
            "transfer_speed": int     # File transfer speed (bytes/sec)
199
        }
200
    ],
201
    "total": int,                     # Total transfer size in bytes
202
    "sent": int,                      # Total bytes transferred
203
    "progress": float,                # Overall progress (0.0-1.0)
204
    "transfer_speed": int,            # Overall transfer speed (bytes/sec)
205
    "rclone_output": dict            # Raw rclone statistics
206
}
207
```