0
# CalDAV
1

2
A comprehensive Python client library for the CalDAV protocol (RFC4791) that enables developers to interact with calendar servers. CalDAV provides complete functionality for calendar management including creating and modifying calendars, managing events, todos, and journal entries, and handling recurring events across popular CalDAV servers.
3

4
## Package Information
5

6
- **Package Name**: caldav
7
- **Language**: Python
8
- **Installation**: `pip install caldav`
9
- **Dependencies**: lxml, requests, recurring-ical-events, icalendar
10

11
## Core Imports
12

13
```python
14
import caldav
15
```
16

17
Main client class:
18

19
```python
20
from caldav import DAVClient
21
```
22

23
For backward compatibility, all classes can be imported directly:
24

25
```python
26
from caldav import Principal, Calendar, Event, Todo, Journal
27
```
28

29
## Basic Usage
30

31
```python
32
import caldav
33
from datetime import datetime
34

35
# Connect to CalDAV server
36
client = caldav.DAVClient(
37
    url="https://calendar.server.com/caldav/",
38
    username="user@example.com",
39
    password="password"
40
)
41

42
# Get the principal (user account)
43
principal = client.principal()
44

45
# Get all calendars
46
calendars = principal.calendars()
47
calendar = calendars[0]  # Use first calendar
48

49
# Create a new event
50
event_ical = """BEGIN:VCALENDAR
51
VERSION:2.0
52
PRODID:-//Example Corp//Example App//EN
53
BEGIN:VEVENT
54
UID:example-event-001
55
DTSTART:20250910T140000Z
56
DTEND:20250910T150000Z
57
SUMMARY:Important Meeting
58
DESCRIPTION:Discuss project milestones
59
END:VEVENT
60
END:VCALENDAR"""
61

62
# Save the event to the calendar
63
event = calendar.save_event(event_ical)
64
print(f"Created event: {event.id}")
65

66
# Search for events in date range
67
events = calendar.date_search(
68
    start=datetime(2025, 9, 1),
69
    end=datetime(2025, 9, 30)
70
)
71

72
for event in events:
73
    print(f"Event: {event.icalendar_component['SUMMARY']}")
74
```
75

76
## Architecture
77

78
CalDAV follows the WebDAV/CalDAV protocol hierarchy:
79

80
- **DAVClient**: HTTP client handling authentication and low-level CalDAV operations
81
- **Principal**: User account representation with access to calendar collections
82
- **CalendarSet**: Collection of calendars for organization and grouping
83
- **Calendar**: Individual calendar collection containing calendar objects
84
- **CalendarObjectResource**: Base class for calendar objects (events, todos, journals)
85
- **Event/Todo/Journal**: Specific calendar object types with specialized functionality
86

87
The library abstracts the complexity of the CalDAV protocol while providing full access to advanced features like recurring events, free/busy scheduling, and server-specific extensions.
88

89
## Capabilities
90

91
### Client Connection & Authentication
92

93
Core client functionality for connecting to CalDAV servers with various authentication methods including Basic, Digest, and Bearer token authentication.
94

95
```python { .api }
96
class DAVClient:
97
    def __init__(self, url, proxy=None, username=None, password=None, 
98
                 auth=None, timeout=None, headers=None, ssl_verify_cert=True, 
99
                 ssl_cert=None, huge_tree=False, auth_type='auto'): ...
100
    
101
    def principal(self, url=None): ...
102
```
103

104
```python { .api }
105
def get_davclient(check_config_file=True, config_file=None, config_section=None, 
106
                  testconfig=False, environment=True, name=None, **config_data): ...
107
```
108

109
[Client Connection & Authentication](./client-auth.md)
110

111
### Principal & Calendar Discovery
112

113
Principal management and calendar discovery functionality for finding and accessing user calendars and calendar collections.
114

115
```python { .api }
116
class Principal:
117
    def calendars(self): ...
118
    def make_calendar(self, name=None, cal_id=None, supported_calendar_component_set=None): ...
119
    def freebusy_request(self, start, end, attendees): ...
120

121
class CalendarSet:
122
    def calendars(self): ...
123
    def make_calendar(self, name=None, cal_id=None, supported_calendar_component_set=None): ...
124
```
125

126
[Principal & Calendar Discovery](./principal-calendar.md)
127

128
### Calendar Management
129

130
Calendar operations including creating, configuring, and managing calendar collections with support for different calendar component types.
131

132
```python { .api }
133
class Calendar:
134
    def events(self): ...
135
    def todos(self): ...
136
    def journals(self): ...
137
    def objects_by_sync_token(self, sync_token=None, load_objects=True): ...
138
    def search(self, xml_query=None, comp_filter=None, prop_filter=None, 
139
               text_match=None, start=None, end=None, expand=False, verify_expand=True): ...
140
    def date_search(self, start, end=None, compfilter=None, expand=False, verify_expand=True): ...
141
    def save_event(self, ical, no_overwrite=False, no_create=False): ...
142
    def save_todo(self, ical, no_overwrite=False, no_create=False): ...
143
    def save_journal(self, ical, no_overwrite=False, no_create=False): ...
144
```
145

146
[Calendar Management](./calendar-management.md)
147

148
### Event Operations
149

150
Comprehensive event management including creation, modification, deletion, and handling of recurring events with full iCalendar support.
151

152
```python { .api }
153
class Event(CalendarObjectResource):
154
    def get_dtstart(self): ...
155
    def get_dtend(self): ...
156
    def get_duration(self): ...
157
    def set_dtstart(self, dtstart): ...
158
    def set_dtend(self, dtend): ...
159
    def set_duration(self, duration): ...
160
```
161

162
[Event Operations](./event-operations.md)
163

164
### Task Management
165

166
Todo/task management functionality with support for due dates, completion tracking, and task hierarchies.
167

168
```python { .api }
169
class Todo(CalendarObjectResource):
170
    def complete(self, completion_timestamp=None, handle_rrule=True): ...
171
    def get_due(self): ...
172
    def get_dtstart(self): ...
173
    def set_due(self, due): ...
174
    def set_dtstart(self, dtstart): ...
175
```
176

177
[Task Management](./task-management.md)
178

179
### Journal & FreeBusy
180

181
Journal entry management and free/busy scheduling functionality for calendar coordination and availability management.
182

183
```python { .api }
184
class Journal(CalendarObjectResource): ...
185

186
class FreeBusy(CalendarObjectResource): ...
187
```
188

189
[Journal & FreeBusy](./journal-freebusy.md)
190

191
## Types
192

193
```python { .api }
194
class DAVObject:
195
    """Base class for all DAV objects with common DAV operations."""
196
    def __init__(self, client=None, url=None, parent=None, name=None, id=None, props=None): ...
197
    def propfind(self, props=None, depth="0"): ...
198
    def proppatch(self, body): ...
199
    def delete(self): ...
200
    def get_property(self, prop): ...
201
    def set_properties(self, props): ...
202

203
class CalendarObjectResource(DAVObject):
204
    """Base class for calendar objects (events, todos, journals, freebusy)."""
205
    def __init__(self, client=None, url=None, data=None, parent=None, id=None): ...
206
    def load(self): ...
207
    def save(self): ...
208
    def copy(self, new_parent): ...
209
    def move(self, new_parent): ...
210
    def expand(self, start, end): ...
211
    def change_uid(self, new_uid=None): ...
212
```
213

214
## Error Handling
215

216
```python { .api }
217
class DAVError(Exception): ...
218
class AuthorizationError(DAVError): ...
219
class PropsetError(DAVError): ...
220
class ProppatchError(DAVError): ...
221
class PropfindError(DAVError): ...
222
class ReportError(DAVError): ...
223
class MkcolError(DAVError): ...
224
class MkcalendarError(DAVError): ...
225
class PutError(DAVError): ...
226
class DeleteError(DAVError): ...
227
class NotFoundError(DAVError): ...
228
class ConsistencyError(DAVError): ...
229
class ResponseError(DAVError): ...
230
```
231

232
## Utility Functions
233

234
```python { .api }
235
def get_davclient(check_config_file=True, config_file=None, config_section=None, 
236
                  testconfig=False, environment=True, name=None, **config_data):
237
    """
238
    Factory function to create DAVClient from configuration.
239
    
240
    Parameters:
241
    - check_config_file: bool, whether to look for config files
242
    - config_file: str, specific config file path
243
    - config_section: str, section name in config file
244
    - testconfig: bool, use test configuration
245
    - environment: bool, read from environment variables
246
    - name: str, configuration name/profile
247
    - **config_data: additional configuration parameters
248
    
249
    Returns:
250
    DAVClient: Configured client instance
251
    """
252

253
def create_ical(ical_fragment=None, objtype=None, language="en_DK", **props):
254
    """
255
    Create iCalendar object from fragment or properties.
256
    
257
    Parameters:
258
    - ical_fragment: str, partial iCalendar data
259
    - objtype: str, object type ('VEVENT', 'VTODO', 'VJOURNAL')
260
    - language: str, language for the calendar
261
    - **props: additional iCalendar properties
262
    
263
    Returns:
264
    str: Complete iCalendar data
265
    """
266

267
def add_alarm(ical, alarm):
268
    """
269
    Add alarm/reminder to iCalendar object.
270
    
271
    Parameters:
272
    - ical: str, iCalendar data
273
    - alarm: dict or str, alarm configuration
274
    
275
    Returns:
276
    str: iCalendar data with alarm added
277
    """
278

279
def fix(event):
280
    """
281
    Fix common iCalendar issues and validate format.
282
    
283
    Parameters:
284
    - event: str, iCalendar data to fix
285
    
286
    Returns:
287
    str: Fixed iCalendar data
288
    """
289
```
290

291
## Synchronization Support
292

293
```python { .api }
294
class SynchronizableCalendarObjectCollection:
295
    """
296
    Cached collection with sync support for efficient calendar updates.
297
    """
298
    
299
    def __init__(self, calendar, objects, sync_token):
300
        """
301
        Initialize synchronized collection.
302
        
303
        Parameters:
304
        - calendar: Calendar, parent calendar
305
        - objects: list, initial objects
306
        - sync_token: str, synchronization token
307
        """
308
    
309
    def __iter__(self):
310
        """Iterator support for collection."""
311
    
312
    def __len__(self):
313
        """Length support for collection."""
314
    
315
    def objects_by_url(self):
316
        """
317
        Get objects mapped by URL.
318
        
319
        Returns:
320
        dict: URL to object mapping
321
        """
322
    
323
    def sync(self):
324
        """
325
        Synchronize collection with server.
326
        
327
        Returns:
328
        tuple: (updated_objects, new_sync_token)
329
        """
330
```
331

332
## URL and Namespace Utilities
333

334
```python { .api }
335
def make(url):
336
    """
337
    Create URL object from string.
338
    
339
    Parameters:
340
    - url: str, URL string
341
    
342
    Returns:
343
    URL: URL object with CalDAV-specific methods
344
    """
345

346
def ns(prefix, tag=None):
347
    """
348
    Create namespaced XML tag for CalDAV/WebDAV operations.
349
    
350
    Parameters:
351
    - prefix: str, namespace prefix ('dav', 'caldav', etc.)
352
    - tag: str, optional tag name
353
    
354
    Returns:
355
    str: Namespaced XML tag
356
    """
357
```
358

359
## String Utilities
360

361
```python { .api }
362
def to_wire(text):
363
    """
364
    Convert text to wire format for HTTP transmission.
365
    
366
    Parameters:
367
    - text: str, text to convert
368
    
369
    Returns:
370
    bytes: Wire-formatted text
371
    """
372

373
def to_local(text):
374
    """
375
    Convert text from wire format to local format.
376
    
377
    Parameters:
378
    - text: bytes, wire-formatted text
379
    
380
    Returns:
381
    str: Local text format
382
    """
383

384
def to_normal_str(text):
385
    """
386
    Convert text to normal string format.
387
    
388
    Parameters:
389
    - text: str or bytes, text to normalize
390
    
391
    Returns:
392
    str: Normalized string
393
    """
394

395
def to_unicode(text):
396
    """
397
    Convert text to unicode string.
398
    
399
    Parameters:
400
    - text: str or bytes, text to convert
401
    
402
    Returns:
403
    str: Unicode string
404
    """
405
```