0
# Client Operations
1

2
Core WebDAV client functionality providing all essential operations for interacting with WebDAV servers. The Client class serves as the primary interface for WebDAV operations, handling connection management, authentication, and basic file operations.
3

4
## Capabilities
5

6
### Client Initialization
7

8
Creates a WebDAV client with configuration options for server connection, authentication, and proxy settings.
9

10
```python { .api }
11
def __init__(self, options: dict) -> None:
12
    """
13
    Initialize WebDAV client with configuration options.
14
    
15
    Parameters:
16
    - options: dict containing configuration keys:
17
        - webdav_hostname: str, WebDAV server URL (required)
18
        - webdav_login: str, username for authentication
19
        - webdav_password: str, password for authentication  
20
        - webdav_token: str, OAuth token for authentication
21
        - webdav_root: str, root directory path on server
22
        - cert_path: str, path to SSL certificate file
23
        - key_path: str, path to SSL private key file
24
        - recv_speed: int, download speed limit in bytes/second
25
        - send_speed: int, upload speed limit in bytes/second
26
        - verbose: bool, enable verbose logging
27
        - proxy_hostname: str, proxy server URL
28
        - proxy_login: str, proxy username
29
        - proxy_password: str, proxy password
30
    
31
    Raises:
32
    - OptionNotValid: if required options are missing or invalid
33
    """
34
```
35

36
### Connection Validation
37

38
Validates client configuration and tests server connectivity.
39

40
```python { .api }
41
def valid(self) -> bool:
42
    """
43
    Validate client configuration settings.
44
    
45
    Returns:
46
    - bool: True if configuration is valid, False otherwise
47
    """
48
```
49

50
### Resource Existence Check
51

52
Checks whether a remote resource (file or directory) exists on the WebDAV server.
53

54
```python { .api }
55
def check(self, remote_path: str = "/") -> bool:
56
    """
57
    Check if remote resource exists.
58
    
59
    Parameters:
60
    - remote_path: str, path to remote resource (defaults to root)
61
    
62
    Returns:
63
    - bool: True if resource exists, False otherwise
64
    
65
    Raises:
66
    - NotConnection: if connection to server fails
67
    """
68
```
69

70
### Resource Information
71

72
Retrieves metadata information about a remote resource.
73

74
```python { .api }
75
def info(self, remote_path: str = "/") -> dict:
76
    """
77
    Get metadata information about remote resource.
78
    
79
    Parameters:
80
    - remote_path: str, path to remote resource
81
    
82
    Returns:
83
    - dict: metadata information including size, modification time, content type
84
    
85
    Raises:
86
    - RemoteResourceNotFound: if resource doesn't exist
87
    - NotConnection: if connection to server fails
88
    """
89
```
90

91
### Directory Listing
92

93
Lists contents of a remote directory.
94

95
```python { .api }
96
def list(self, remote_path: str = "/") -> list:
97
    """
98
    List contents of remote directory.
99
    
100
    Parameters:
101
    - remote_path: str, path to remote directory
102
    
103
    Returns:
104
    - list: list of filenames and directory names in the specified path
105
    
106
    Raises:
107
    - RemoteResourceNotFound: if directory doesn't exist
108
    - NotConnection: if connection to server fails
109
    """
110
```
111

112
### Free Space Check
113

114
Gets available free space on the WebDAV server.
115

116
```python { .api }
117
def free(self) -> int:
118
    """
119
    Get available free space on WebDAV server.
120
    
121
    Returns:
122
    - int: available space in bytes
123
    
124
    Raises:
125
    - MethodNotSupported: if server doesn't support free space queries
126
    - NotConnection: if connection to server fails
127
    """
128
```
129

130
### Directory Creation
131

132
Creates a directory on the remote WebDAV server.
133

134
```python { .api }
135
def mkdir(self, remote_path: str) -> None:
136
    """
137
    Create directory on remote server.
138
    
139
    Parameters:
140
    - remote_path: str, path where directory should be created
141
    
142
    Raises:
143
    - RemoteParentNotFound: if parent directory doesn't exist
144
    - NotConnection: if connection to server fails
145
    - NotEnoughSpace: if insufficient space on server
146
    """
147
```
148

149
### Resource Deletion
150

151
Deletes a file or directory from the remote WebDAV server.
152

153
```python { .api }
154
def clean(self, remote_path: str) -> None:
155
    """
156
    Delete remote resource (file or directory).
157
    
158
    Parameters:
159
    - remote_path: str, path to resource to delete
160
    
161
    Raises:
162
    - RemoteResourceNotFound: if resource doesn't exist
163
    - NotConnection: if connection to server fails
164
    """
165
```
166

167
### Resource Copy
168

169
Copies a file or directory to a new location on the WebDAV server.
170

171
```python { .api }
172
def copy(self, remote_path_from: str, remote_path_to: str) -> None:
173
    """
174
    Copy remote resource to new location.
175
    
176
    Parameters:
177
    - remote_path_from: str, source path
178
    - remote_path_to: str, destination path
179
    
180
    Raises:
181
    - RemoteResourceNotFound: if source resource doesn't exist
182
    - RemoteParentNotFound: if destination parent doesn't exist
183
    - NotConnection: if connection to server fails
184
    - NotEnoughSpace: if insufficient space on server
185
    """
186
```
187

188
### Resource Move
189

190
Moves a file or directory to a new location on the WebDAV server.
191

192
```python { .api }
193
def move(self, remote_path_from: str, remote_path_to: str) -> None:
194
    """
195
    Move remote resource to new location.
196
    
197
    Parameters:
198
    - remote_path_from: str, source path
199
    - remote_path_to: str, destination path
200
    
201
    Raises:
202
    - RemoteResourceNotFound: if source resource doesn't exist
203
    - RemoteParentNotFound: if destination parent doesn't exist
204
    - NotConnection: if connection to server fails
205
    """
206
```
207

208
### Resource Publishing
209

210
Makes a resource publicly accessible and returns a public URL.
211

212
```python { .api }
213
def publish(self, remote_path: str) -> str:
214
    """
215
    Publish resource and get public URL.
216
    
217
    Parameters:
218
    - remote_path: str, path to resource to publish
219
    
220
    Returns:
221
    - str: public URL for accessing the resource
222
    
223
    Raises:
224
    - RemoteResourceNotFound: if resource doesn't exist
225
    - MethodNotSupported: if server doesn't support publishing
226
    - NotConnection: if connection to server fails
227
    """
228
```
229

230
### Resource Unpublishing
231

232
Removes public access from a previously published resource.
233

234
```python { .api }
235
def unpublish(self, remote_path: str) -> None:
236
    """
237
    Remove public access from resource.
238
    
239
    Parameters:
240
    - remote_path: str, path to resource to unpublish
241
    
242
    Raises:
243
    - RemoteResourceNotFound: if resource doesn't exist
244
    - MethodNotSupported: if server doesn't support unpublishing
245
    - NotConnection: if connection to server fails
246
    """
247
```
248

249
### Directory Type Check
250

251
Checks whether a remote resource is a directory or file.
252

253
```python { .api }
254
def is_dir(self, remote_path: str) -> bool:
255
    """
256
    Check if remote resource is a directory.
257
    
258
    Parameters:
259
    - remote_path: str, path to remote resource
260
    
261
    Returns:
262
    - bool: True if resource is directory, False if file
263
    
264
    Raises:
265
    - RemoteResourceNotFound: if resource doesn't exist
266
    - MethodNotSupported: if server doesn't support directory type queries
267
    - NotConnection: if connection to server fails
268
    """
269
```
270

271
### Resource Object Creation
272

273
Creates a Resource object for object-oriented operations on a specific remote path.
274

275
```python { .api }
276
def resource(self, remote_path: str) -> Resource:
277
    """
278
    Get Resource object for OOP-style operations.
279
    
280
    Parameters:
281
    - remote_path: str, path to remote resource
282
    
283
    Returns:
284
    - Resource: resource object for the specified path
285
    """
286
```
287

288
### Metadata Operations
289

290
Retrieves and sets WebDAV properties on remote resources.
291

292
```python { .api }
293
def get_property(self, remote_path: str, option: dict) -> str:
294
    """
295
    Get WebDAV property value for remote resource.
296
    
297
    Parameters:
298
    - remote_path: str, path to remote resource
299
    - option: dict, property specification containing namespace and name
300
    
301
    Returns:
302
    - str: property value
303
    
304
    Raises:
305
    - RemoteResourceNotFound: if resource doesn't exist
306
    - NotConnection: if connection to server fails
307
    """
308

309
def set_property(self, remote_path: str, option: dict) -> None:
310
    """
311
    Set WebDAV property on remote resource.
312
    
313
    Parameters:
314
    - remote_path: str, path to remote resource  
315
    - option: dict, property specification with namespace, name, and value
316
    
317
    Raises:
318
    - RemoteResourceNotFound: if resource doesn't exist
319
    - MethodNotSupported: if server doesn't support PROPPATCH
320
    - NotConnection: if connection to server fails
321
    """
322
```
323

324
### Buffer I/O Operations
325

326
Direct buffer-based upload and download operations for memory-efficient file transfers.
327

328
```python { .api }
329
def download_to(self, buff, remote_path: str) -> None:
330
    """
331
    Download remote resource content to buffer.
332
    
333
    Parameters:
334
    - buff: buffer object to write downloaded data
335
    - remote_path: str, path to remote resource
336
    
337
    Raises:
338
    - RemoteResourceNotFound: if resource doesn't exist
339
    - NotConnection: if connection to server fails
340
    """
341

342
def upload_from(self, buff, remote_path: str) -> None:
343
    """
344
    Upload buffer content to remote resource.
345
    
346
    Parameters:
347
    - buff: buffer object containing data to upload
348
    - remote_path: str, path to remote resource
349
    
350
    Raises:
351
    - RemoteParentNotFound: if parent directory doesn't exist
352
    - NotEnoughSpace: if insufficient space on server
353
    - NotConnection: if connection to server fails
354
    """
355
```
356

357
## Usage Examples
358

359
### Basic Client Setup
360

361
```python
362
import webdav.client as wc
363

364
# Basic authentication
365
options = {
366
    'webdav_hostname': "https://webdav.server.com",
367
    'webdav_login': "username",
368
    'webdav_password': "password"
369
}
370
client = wc.Client(options)
371

372
# OAuth token authentication
373
options = {
374
    'webdav_hostname': "https://webdav.server.com", 
375
    'webdav_token': "oauth_token_here"
376
}
377
client = wc.Client(options)
378
```
379

380
### Directory Operations
381

382
```python
383
# Check if directory exists
384
if client.check("documents/"):
385
    # List directory contents
386
    files = client.list("documents/")
387
    print(f"Found {len(files)} items")
388
    
389
    # Create subdirectory
390
    client.mkdir("documents/archive/")
391
    
392
    # Get directory info
393
    info = client.info("documents/")
394
    print(f"Directory size: {info.get('size', 'unknown')}")
395
    
396
    # Check if resource is directory
397
    is_directory = client.is_dir("documents/")
398
    print(f"Is directory: {is_directory}")
399
```
400

401
### File Operations
402

403
```python
404
# Check file existence and get info
405
if client.check("data/report.pdf"):
406
    info = client.info("data/report.pdf")
407
    print(f"File size: {info['size']} bytes")
408
    
409
    # Copy file
410
    client.copy("data/report.pdf", "backup/report_backup.pdf")
411
    
412
    # Move file
413
    client.move("temp/draft.pdf", "data/final.pdf")
414
    
415
    # Publish file for sharing
416
    public_url = client.publish("data/report.pdf")
417
    print(f"Public URL: {public_url}")
418
```