0
# WebDAV Client
1

2
A comprehensive Python library providing easy and convenient access to WebDAV servers including cloud storage services like Yandex.Drive, Dropbox, Google Drive, Box, 4shared, and others. The package offers three main components: a webdav API for programmatic access, a resource API using object-oriented concepts, and a cross-platform command-line utility (wdc).
3

4
## Package Information
5

6
- **Package Name**: webdavclient
7
- **Language**: Python
8
- **Installation**: `pip install webdavclient`
9
- **Version**: 1.0.8
10
- **Python Support**: 2.6-2.7, 3.0-3.4
11

12
## Core Imports
13

14
```python
15
import webdav.client as wc
16
```
17

18
For specific classes and exceptions:
19

20
```python
21
from webdav.client import Client, Resource
22
from webdav.exceptions import WebDavException
23
```
24

25
## Basic Usage
26

27
```python
28
import webdav.client as wc
29

30
# Configure client with WebDAV server credentials
31
options = {
32
    'webdav_hostname': "https://webdav.server.com",
33
    'webdav_login': "username", 
34
    'webdav_password': "password"
35
}
36
client = wc.Client(options)
37

38
# Basic file operations
39
client.check("remote/file.txt")  # Check if file exists
40
client.mkdir("remote/newfolder")  # Create directory
41
client.upload_sync("remote/file.txt", "local/file.txt")  # Upload file
42
client.download_sync("remote/file.txt", "local/file.txt")  # Download file
43

44
# Resource API for object-oriented operations
45
resource = client.resource("remote/file.txt")
46
resource.read("local/copy.txt")  # Download using resource
47
resource.write("local/upload.txt")  # Upload using resource
48
```
49

50
## Architecture
51

52
The webdavclient architecture consists of three main layers:
53

54
- **Client API**: Direct WebDAV operations with synchronous and asynchronous methods
55
- **Resource API**: Object-oriented wrapper providing intuitive resource manipulation
56
- **Connection Layer**: Configuration management with WebDAV and proxy settings
57
- **Utility Layer**: URI handling, exceptions, and supporting functions
58

59
## Capabilities
60

61
### Client Operations
62

63
Core WebDAV client functionality providing all essential operations for interacting with WebDAV servers. Includes connection management, basic file operations, and advanced synchronization features.
64

65
```python { .api }
66
class Client:
67
    def __init__(self, options: dict) -> None: ...
68
    def valid(self) -> bool: ...
69
    def check(self, remote_path: str = "/") -> bool: ...
70
    def list(self, remote_path: str = "/") -> list: ...
71
    def info(self, remote_path: str = "/") -> dict: ...
72
    def free(self) -> int: ...
73
    def mkdir(self, remote_path: str) -> None: ...
74
    def is_dir(self, remote_path: str) -> bool: ...
75
    def clean(self, remote_path: str) -> None: ...
76
    def copy(self, remote_path_from: str, remote_path_to: str) -> None: ...
77
    def move(self, remote_path_from: str, remote_path_to: str) -> None: ...
78
    def get_property(self, remote_path: str, option: dict) -> str: ...
79
    def set_property(self, remote_path: str, option: dict) -> None: ...
80
    def download_to(self, buff, remote_path: str) -> None: ...
81
    def upload_from(self, buff, remote_path: str) -> None: ...
82
    def publish(self, remote_path: str) -> str: ...
83
    def unpublish(self, remote_path: str) -> None: ...
84
    def resource(self, remote_path: str) -> Resource: ...
85
```
86

87
[Client Operations](./client-operations.md)
88

89
### File Transfer
90

91
Upload and download operations with support for both synchronous and asynchronous execution, progress callbacks, and directory synchronization.
92

93
```python { .api }
94
def download_sync(self, remote_path: str, local_path: str, callback=None) -> None: ...
95
def upload_sync(self, remote_path: str, local_path: str, callback=None) -> None: ...
96
def download_async(self, remote_path: str, local_path: str, callback=None) -> None: ...
97
def upload_async(self, remote_path: str, local_path: str, callback=None) -> None: ...
98
```
99

100
[File Transfer](./file-transfer.md)
101

102
### Resource Management
103

104
Object-oriented interface for WebDAV resources providing intuitive methods for file and directory operations, metadata access, and content manipulation.
105

106
```python { .api }
107
class Resource:
108
    def __init__(self, client: Client, urn: str) -> None: ...
109
    def is_dir(self) -> bool: ...
110
    def check(self) -> bool: ...
111
    def info(self, params=None) -> dict: ...
112
    def clean(self) -> None: ...
113
    def rename(self, new_name: str) -> None: ...
114
    def move(self, remote_path: str) -> None: ...
115
    def copy(self, remote_path: str) -> Resource: ...
116
    def read_from(self, buff) -> None: ...
117
    def read(self, local_path: str) -> None: ...
118
    def read_async(self, local_path: str, callback=None) -> None: ...
119
    def write_to(self, buff) -> None: ...
120
    def write(self, local_path: str) -> None: ...
121
    def write_async(self, local_path: str, callback=None) -> None: ...
122
    def publish(self) -> str: ...
123
    def unpublish(self) -> None: ...
124
    @property
125
    def property(self) -> str: ...  # Property getter
126
    @property.setter
127
    def property(self, value) -> None: ...  # Property setter
128
```
129

130
[Resource Management](./resource-management.md)
131

132
### Synchronization
133

134
Advanced directory synchronization capabilities for keeping local and remote directories in sync, with support for push, pull, and bidirectional synchronization.
135

136
```python { .api }
137
def push(self, remote_directory: str, local_directory: str) -> None: ...
138
def pull(self, remote_directory: str, local_directory: str) -> None: ...
139
def sync(self, remote_directory: str, local_directory: str) -> None: ...
140
```
141

142
[Synchronization](./synchronization.md)
143

144
### Metadata and Properties
145

146
WebDAV metadata and property operations for retrieving and setting custom properties on resources.
147

148
```python { .api }
149
def get_property(self, remote_path: str, option: dict) -> str: ...
150
def set_property(self, remote_path: str, option: dict) -> None: ...
151
```
152

153
### Configuration
154

155
WebDAV and proxy server configuration with comprehensive validation and SSL certificate support.
156

157
```python { .api }
158
class WebDAVSettings:
159
    keys = {'hostname', 'login', 'password', 'token', 'root', 'cert_path', 'key_path', 'recv_speed', 'send_speed', 'verbose'}
160
    def __init__(self, options: dict) -> None: ...
161
    def is_valid(self) -> None: ...
162

163
class ProxySettings:
164
    keys = {'hostname', 'login', 'password'}
165
    def __init__(self, options: dict) -> None: ...
166
```
167

168
[Configuration](./configuration.md)
169

170
## Constants
171

172
```python { .api }
173
# Module version
174
__version__ = "1.0.8"
175

176
# Client class constants  
177
class Client:
178
    root = '/'  # Default root directory
179
    large_size = 2 * 1024 * 1024 * 1024  # 2GB large file threshold
180
```
181

182
## Types
183

184
```python { .api }
185
# Exception hierarchy
186
class WebDavException(Exception): ...
187
class NotValid(WebDavException): ...
188
class OptionNotValid(NotValid): ...
189
class NotFound(WebDavException): ...
190
class LocalResourceNotFound(NotFound): ...
191
class RemoteResourceNotFound(NotFound): ...
192
class RemoteParentNotFound(NotFound): ...
193
class MethodNotSupported(WebDavException): ...
194
class NotConnection(WebDavException): ...
195
class NotEnoughSpace(WebDavException): ...
196
class CertificateNotValid(NotValid): ...
197

198
# Utility classes
199
class Urn:
200
    def __init__(self, path: str, directory: bool = False) -> None: ...
201
    def path(self) -> str: ...
202
    def quote(self) -> str: ...
203
    def filename(self) -> str: ...
204
    def parent(self) -> str: ...
205
    def nesting_level(self) -> int: ...
206
    def is_dir(self) -> bool: ...
207

208
# Module-level utility functions
209
def listdir(directory: str) -> list: ...  # Enhanced directory listing
210
def add_options(request, options: dict) -> None: ...  # Add pycurl options
211
def get_options(type, from_options: dict) -> dict: ...  # Extract typed options
212
```