0
# Resource Management
1
2
Object-oriented interface for WebDAV resources providing intuitive methods for file and directory operations, metadata access, and content manipulation. The Resource class wraps individual WebDAV resources with convenient methods for common operations.
3
4
## Capabilities
5
6
### Resource Creation
7
8
Creates Resource objects representing specific remote paths for object-oriented operations.
9
10
```python { .api }
11
class Resource:
12
def __init__(self, client: Client, urn: str) -> None:
13
"""
14
Initialize Resource object for specific remote path.
15
16
Parameters:
17
- client: Client, WebDAV client instance
18
- urn: str, remote path or URN for the resource
19
"""
20
```
21
22
### Resource Information
23
24
Methods for getting information about resources and their properties.
25
26
```python { .api }
27
def __str__(self) -> str:
28
"""
29
String representation of resource path.
30
31
Returns:
32
- str: resource path
33
"""
34
35
def is_dir(self) -> bool:
36
"""
37
Check if resource is a directory.
38
39
Returns:
40
- bool: True if resource is directory, False if file
41
"""
42
43
def info(self, params=None) -> dict:
44
"""
45
Get metadata information about resource.
46
47
Parameters:
48
- params: dict, optional parameters for info request
49
50
Returns:
51
- dict: metadata including size, modification time, content type
52
53
Raises:
54
- RemoteResourceNotFound: if resource doesn't exist
55
- NotConnection: if connection to server fails
56
"""
57
58
def check(self) -> bool:
59
"""
60
Check if resource exists on server.
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 Operations
71
72
Methods for manipulating and organizing resources on the server.
73
74
```python { .api }
75
def rename(self, new_name: str) -> None:
76
"""
77
Rename resource to new name in same directory.
78
79
Parameters:
80
- new_name: str, new filename or directory name
81
82
Raises:
83
- RemoteResourceNotFound: if resource doesn't exist
84
- RemoteParentNotFound: if parent directory doesn't exist
85
- NotConnection: if connection to server fails
86
"""
87
88
def move(self, remote_path: str) -> None:
89
"""
90
Move resource to new remote path.
91
92
Parameters:
93
- remote_path: str, destination path for resource
94
95
Raises:
96
- RemoteResourceNotFound: if resource doesn't exist
97
- RemoteParentNotFound: if destination parent doesn't exist
98
- NotConnection: if connection to server fails
99
"""
100
101
def copy(self, remote_path: str) -> Resource:
102
"""
103
Copy resource to new remote path.
104
105
Parameters:
106
- remote_path: str, destination path for copy
107
108
Returns:
109
- Resource: new resource object for the copied resource
110
111
Raises:
112
- RemoteResourceNotFound: if resource doesn't exist
113
- RemoteParentNotFound: if destination parent doesn't exist
114
- NotConnection: if connection to server fails
115
- NotEnoughSpace: if insufficient space on server
116
"""
117
118
def clean(self) -> None:
119
"""
120
Delete resource from server.
121
122
Raises:
123
- RemoteResourceNotFound: if resource doesn't exist
124
- NotConnection: if connection to server fails
125
"""
126
```
127
128
### Content Operations
129
130
Methods for reading and writing resource content.
131
132
```python { .api }
133
def read_from(self, buff) -> None:
134
"""
135
Read resource content into buffer.
136
137
Parameters:
138
- buff: buffer object to write content to
139
140
Raises:
141
- RemoteResourceNotFound: if resource doesn't exist
142
- NotConnection: if connection to server fails
143
"""
144
145
def read(self, local_path: str) -> None:
146
"""
147
Download resource content to local file.
148
149
Parameters:
150
- local_path: str, local file path for download
151
152
Raises:
153
- RemoteResourceNotFound: if resource doesn't exist
154
- LocalResourceNotFound: if local parent directory doesn't exist
155
- NotConnection: if connection to server fails
156
"""
157
158
def read_async(self, local_path: str, callback=None) -> None:
159
"""
160
Asynchronously download resource content.
161
162
Parameters:
163
- local_path: str, local file path for download
164
- callback: callable, completion callback function
165
166
Note: Operation runs in background thread
167
"""
168
169
def write_to(self, buff) -> None:
170
"""
171
Write buffer content to resource.
172
173
Parameters:
174
- buff: buffer object containing data to upload
175
176
Raises:
177
- RemoteParentNotFound: if parent directory doesn't exist
178
- NotConnection: if connection to server fails
179
- NotEnoughSpace: if insufficient space on server
180
"""
181
182
def write(self, local_path: str) -> None:
183
"""
184
Upload local file content to resource.
185
186
Parameters:
187
- local_path: str, path to local file to upload
188
189
Raises:
190
- LocalResourceNotFound: if local file doesn't exist
191
- RemoteParentNotFound: if parent directory doesn't exist
192
- NotConnection: if connection to server fails
193
- NotEnoughSpace: if insufficient space on server
194
"""
195
196
def write_async(self, local_path: str, callback=None) -> None:
197
"""
198
Asynchronously upload local file content.
199
200
Parameters:
201
- local_path: str, path to local file to upload
202
- callback: callable, completion callback function
203
204
Note: Operation runs in background thread
205
"""
206
```
207
208
### Publishing Operations
209
210
Methods for controlling public access to resources.
211
212
```python { .api }
213
def publish(self) -> str:
214
"""
215
Publish resource and get public URL.
216
217
Returns:
218
- str: public URL for accessing the resource
219
220
Raises:
221
- RemoteResourceNotFound: if resource doesn't exist
222
- MethodNotSupported: if server doesn't support publishing
223
- NotConnection: if connection to server fails
224
"""
225
226
def unpublish(self) -> None:
227
"""
228
Remove public access from resource.
229
230
Raises:
231
- RemoteResourceNotFound: if resource doesn't exist
232
- MethodNotSupported: if server doesn't support unpublishing
233
- NotConnection: if connection to server fails
234
"""
235
```
236
237
### Property Management
238
239
Methods for getting and setting WebDAV properties on resources.
240
241
```python { .api }
242
@property
243
def property(self, option: dict):
244
"""
245
Get WebDAV property from resource.
246
247
Parameters:
248
- option: dict, property specification
249
250
Returns:
251
- Property value based on option specification
252
253
Raises:
254
- RemoteResourceNotFound: if resource doesn't exist
255
- NotConnection: if connection to server fails
256
"""
257
258
@property.setter
259
def property(self, option: dict, value) -> None:
260
"""
261
Set WebDAV property on resource.
262
263
Parameters:
264
- option: dict, property specification
265
- value: property value to set
266
267
Raises:
268
- RemoteResourceNotFound: if resource doesn't exist
269
- NotConnection: if connection to server fails
270
"""
271
```
272
273
## Usage Examples
274
275
### Basic Resource Operations
276
277
```python
278
import webdav.client as wc
279
280
client = wc.Client({
281
'webdav_hostname': "https://webdav.server.com",
282
'webdav_login': "username",
283
'webdav_password': "password"
284
})
285
286
# Get resource object
287
document = client.resource("documents/report.pdf")
288
289
# Check if resource exists and get info
290
if document.check():
291
info = document.info()
292
print(f"File size: {info['size']} bytes")
293
print(f"Is directory: {document.is_dir()}")
294
295
# Rename file
296
document.rename("annual_report.pdf")
297
```
298
299
### File Content Operations
300
301
```python
302
# Create resource for text file
303
config_file = client.resource("config/settings.json")
304
305
# Download file content
306
config_file.read("~/Downloads/settings.json")
307
308
# Upload new content
309
config_file.write("~/Documents/new_settings.json")
310
311
# Work with buffers
312
from io import BytesIO
313
314
# Read to buffer
315
buffer = BytesIO()
316
config_file.read_from(buffer)
317
buffer.seek(0)
318
content = buffer.read().decode('utf-8')
319
print(f"Config content: {content}")
320
321
# Write from buffer
322
new_data = '{"theme": "dark", "language": "en"}'
323
upload_buffer = BytesIO(new_data.encode('utf-8'))
324
config_file.write_to(upload_buffer)
325
```
326
327
### Resource Management
328
329
```python
330
# Create resource objects
331
source_doc = client.resource("drafts/proposal.docx")
332
backup_doc = client.resource("backup/proposal_backup.docx")
333
final_doc = client.resource("final/proposal.docx")
334
335
# Copy document to backup
336
source_doc.copy("backup/proposal_backup.docx")
337
338
# Move to final location
339
source_doc.move("final/proposal.docx")
340
341
# Publish for sharing
342
public_url = final_doc.publish()
343
print(f"Document available at: {public_url}")
344
345
# Later, remove public access
346
final_doc.unpublish()
347
```
348
349
### Asynchronous Operations with Callbacks
350
351
```python
352
def upload_callback(success, error=None):
353
if success:
354
print("Upload completed successfully")
355
else:
356
print(f"Upload failed: {error}")
357
358
def download_callback(success, error=None):
359
if success:
360
print("Download completed successfully")
361
else:
362
print(f"Download failed: {error}")
363
364
# Async upload and download
365
video_resource = client.resource("media/presentation.mp4")
366
video_resource.write_async("~/Videos/presentation.mp4", callback=upload_callback)
367
368
image_resource = client.resource("images/chart.png")
369
image_resource.read_async("~/Downloads/chart.png", callback=download_callback)
370
```
371
372
### Resource Property Management
373
374
```python
375
# Get resource with properties
376
document = client.resource("documents/metadata_example.pdf")
377
378
# Get custom property
379
metadata_option = {
380
'name': 'custom:author',
381
'namespace': 'http://example.com/metadata'
382
}
383
author = document.property[metadata_option]
384
print(f"Author: {author}")
385
386
# Set custom property
387
document.property[metadata_option] = "John Doe"
388
389
# Get standard WebDAV properties
390
size_option = {'name': 'getcontentlength'}
391
file_size = document.property[size_option]
392
print(f"File size: {file_size}")
393
```
394
395
### Directory Resource Operations
396
397
```python
398
# Work with directory resources
399
project_dir = client.resource("projects/webapp/")
400
401
# Check if it's a directory
402
if project_dir.is_dir():
403
# Get directory info
404
dir_info = project_dir.info()
405
print(f"Directory created: {dir_info.get('creation_date')}")
406
407
# Create backup copy
408
project_dir.copy("backup/webapp_backup/")
409
410
# Rename directory
411
project_dir.rename("webapp_v2")
412
```