0
# File Transfer
1

2
Upload and download operations with support for both synchronous and asynchronous execution, progress callbacks, and directory synchronization. These operations handle the transfer of files and directories between local filesystem and WebDAV servers.
3

4
## Capabilities
5

6
### Download Operations
7

8
Downloads files and directories from WebDAV server to local filesystem with various execution modes and progress tracking.
9

10
```python { .api }
11
def download_to(self, buff, remote_path: str) -> None:
12
    """
13
    Download remote file content to buffer.
14
    
15
    Parameters:
16
    - buff: buffer object to write content to
17
    - remote_path: str, path to remote file
18
    
19
    Raises:
20
    - RemoteResourceNotFound: if remote file doesn't exist
21
    - NotConnection: if connection to server fails
22
    """
23

24
def download(self, remote_path: str, local_path: str, progress=None) -> None:
25
    """
26
    Download file or directory with optional progress callback.
27
    
28
    Parameters:
29
    - remote_path: str, path to remote resource
30
    - local_path: str, local destination path
31
    - progress: callable, progress callback function
32
    
33
    Raises:
34
    - RemoteResourceNotFound: if remote resource doesn't exist
35
    - LocalResourceNotFound: if local parent directory doesn't exist
36
    - NotConnection: if connection to server fails
37
    """
38

39
def download_sync(self, remote_path: str, local_path: str, callback=None) -> None:
40
    """
41
    Synchronously download remote resource to local path.
42
    
43
    Parameters:
44
    - remote_path: str, path to remote resource
45
    - local_path: str, local destination path  
46
    - callback: callable, completion callback function
47
    
48
    Raises:
49
    - RemoteResourceNotFound: if remote resource doesn't exist
50
    - LocalResourceNotFound: if local parent directory doesn't exist
51
    - NotConnection: if connection to server fails
52
    """
53

54
def download_async(self, remote_path: str, local_path: str, callback=None) -> None:
55
    """
56
    Asynchronously download remote resource with callback.
57
    
58
    Parameters:
59
    - remote_path: str, path to remote resource
60
    - local_path: str, local destination path
61
    - callback: callable, completion callback function
62
    
63
    Note: Operation runs in background thread
64
    """
65

66
def download_directory(self, remote_path: str, local_path: str, progress=None) -> None:
67
    """
68
    Download entire directory recursively.
69
    
70
    Parameters:
71
    - remote_path: str, path to remote directory
72
    - local_path: str, local destination directory
73
    - progress: callable, progress callback for tracking
74
    
75
    Raises:
76
    - RemoteResourceNotFound: if remote directory doesn't exist
77
    - NotConnection: if connection to server fails
78
    """
79

80
def download_file(self, remote_path: str, local_path: str, progress=None) -> None:
81
    """
82
    Download single file with progress tracking.
83
    
84
    Parameters:
85
    - remote_path: str, path to remote file
86
    - local_path: str, local destination file path
87
    - progress: callable, progress callback function
88
    
89
    Raises:
90
    - RemoteResourceNotFound: if remote file doesn't exist
91
    - NotConnection: if connection to server fails
92
    """
93
```
94

95
### Upload Operations
96

97
Uploads files and directories from local filesystem to WebDAV server with various execution modes and progress tracking.
98

99
```python { .api }
100
def upload_from(self, buff, remote_path: str) -> None:
101
    """
102
    Upload buffer content to remote file.
103
    
104
    Parameters:
105
    - buff: buffer object containing data to upload
106
    - remote_path: str, destination path on remote server
107
    
108
    Raises:
109
    - RemoteParentNotFound: if remote parent directory doesn't exist
110
    - NotConnection: if connection to server fails
111
    - NotEnoughSpace: if insufficient space on server
112
    """
113

114
def upload(self, remote_path: str, local_path: str, progress=None) -> None:
115
    """
116
    Upload file or directory with optional progress callback.
117
    
118
    Parameters:
119
    - remote_path: str, destination path on remote server
120
    - local_path: str, path to local resource
121
    - progress: callable, progress callback function
122
    
123
    Raises:
124
    - LocalResourceNotFound: if local resource doesn't exist
125
    - RemoteParentNotFound: if remote parent directory doesn't exist
126
    - NotConnection: if connection to server fails
127
    - NotEnoughSpace: if insufficient space on server
128
    """
129

130
def upload_sync(self, remote_path: str, local_path: str, callback=None) -> None:
131
    """
132
    Synchronously upload local resource to remote path.
133
    
134
    Parameters:
135
    - remote_path: str, destination path on remote server
136
    - local_path: str, path to local resource
137
    - callback: callable, completion callback function
138
    
139
    Raises:
140
    - LocalResourceNotFound: if local resource doesn't exist
141
    - RemoteParentNotFound: if remote parent directory doesn't exist
142
    - NotConnection: if connection to server fails
143
    - NotEnoughSpace: if insufficient space on server
144
    """
145

146
def upload_async(self, remote_path: str, local_path: str, callback=None) -> None:
147
    """
148
    Asynchronously upload local resource with callback.
149
    
150
    Parameters:
151
    - remote_path: str, destination path on remote server
152
    - local_path: str, path to local resource  
153
    - callback: callable, completion callback function
154
    
155
    Note: Operation runs in background thread
156
    """
157

158
def upload_directory(self, remote_path: str, local_path: str, progress=None) -> None:
159
    """
160
    Upload entire directory recursively.
161
    
162
    Parameters:
163
    - remote_path: str, destination directory on remote server
164
    - local_path: str, path to local directory
165
    - progress: callable, progress callback for tracking
166
    
167
    Raises:
168
    - LocalResourceNotFound: if local directory doesn't exist
169
    - RemoteParentNotFound: if remote parent directory doesn't exist
170
    - NotConnection: if connection to server fails
171
    - NotEnoughSpace: if insufficient space on server
172
    """
173

174
def upload_file(self, remote_path: str, local_path: str, progress=None) -> None:
175
    """
176
    Upload single file with progress tracking.
177
    
178
    Parameters:
179
    - remote_path: str, destination file path on remote server
180
    - local_path: str, path to local file
181
    - progress: callable, progress callback function
182
    
183
    Raises:
184
    - LocalResourceNotFound: if local file doesn't exist
185
    - RemoteParentNotFound: if remote parent directory doesn't exist
186
    - NotConnection: if connection to server fails
187
    - NotEnoughSpace: if insufficient space on server
188
    """
189
```
190

191
## Usage Examples
192

193
### Simple File Download
194

195
```python
196
import webdav.client as wc
197

198
client = wc.Client({
199
    'webdav_hostname': "https://webdav.server.com",
200
    'webdav_login': "username",
201
    'webdav_password': "password"
202
})
203

204
# Download single file
205
client.download_sync("documents/report.pdf", "~/Downloads/report.pdf")
206

207
# Download with progress tracking
208
def show_progress(current, total):
209
    percentage = (current / total) * 100
210
    print(f"Download progress: {percentage:.1f}%")
211

212
client.download_file("documents/large_file.zip", "~/Downloads/large_file.zip", progress=show_progress)
213
```
214

215
### Directory Download
216

217
```python
218
# Download entire directory
219
client.download_directory("projects/webapp/", "~/Downloads/webapp/")
220

221
# Asynchronous download with callback
222
def download_complete(success, error=None):
223
    if success:
224
        print("Download completed successfully")
225
    else:
226
        print(f"Download failed: {error}")
227

228
client.download_async("backup/archive.tar.gz", "~/Downloads/archive.tar.gz", callback=download_complete)
229
```
230

231
### Simple File Upload
232

233
```python
234
# Upload single file
235
client.upload_sync("documents/new_report.pdf", "~/Documents/report.pdf")
236

237
# Upload with progress tracking
238
def upload_progress(current, total):
239
    percentage = (current / total) * 100
240
    print(f"Upload progress: {percentage:.1f}%")
241

242
client.upload_file("media/video.mp4", "~/Videos/presentation.mp4", progress=upload_progress)
243
```
244

245
### Directory Upload
246

247
```python
248
# Upload entire directory
249
client.upload_directory("projects/website/", "~/Development/website/")
250

251
# Asynchronous upload with callback
252
def upload_complete(success, error=None):
253
    if success:
254
        print("Upload completed successfully")
255
    else:
256
        print(f"Upload failed: {error}")
257

258
client.upload_async("backup/project.zip", "~/Projects/backup.zip", callback=upload_complete)
259
```
260

261
### Buffer Operations
262

263
```python
264
from io import BytesIO
265

266
# Download to buffer
267
buffer = BytesIO()
268
client.download_to(buffer, "data/config.json")
269
buffer.seek(0)
270
config_data = buffer.read()
271

272
# Upload from buffer
273
data = b"Hello, WebDAV!"
274
upload_buffer = BytesIO(data)
275
client.upload_from(upload_buffer, "messages/greeting.txt")
276
```
277

278
### Progress Callback Implementation
279

280
```python
281
import time
282

283
class ProgressTracker:
284
    def __init__(self, description):
285
        self.description = description
286
        self.start_time = time.time()
287
        
288
    def __call__(self, current, total):
289
        percentage = (current / total) * 100
290
        elapsed = time.time() - self.start_time
291
        speed = current / elapsed if elapsed > 0 else 0
292
        
293
        print(f"{self.description}: {percentage:.1f}% ({current}/{total} bytes) - {speed:.0f} B/s")
294

295
# Use progress tracker
296
tracker = ProgressTracker("Downloading report")
297
client.download_file("reports/annual_report.pdf", "~/Downloads/annual_report.pdf", progress=tracker)
298
```