0
# Principal & Calendar Discovery
1

2
Principal management and calendar discovery functionality for finding and accessing user calendars, calendar collections, and organizational structures within CalDAV servers.
3

4
## Capabilities
5

6
### Principal Operations
7

8
Represents a CalDAV principal (user account) with access to calendar collections and user-specific functionality including calendar creation and free/busy scheduling.
9

10
```python { .api }
11
class Principal(DAVObject):
12
    def calendars(self):
13
        """
14
        Get all calendars accessible to this principal.
15
        
16
        Returns:
17
        list[Calendar]: List of Calendar objects
18
        """
19
    
20
    
21
    def calendar_home_set(self):
22
        """
23
        Get the calendar home set URL for this principal.
24
        
25
        Returns:
26
        str: Calendar home set URL
27
        """
28
    
29
    def make_calendar(self, name=None, cal_id=None, supported_calendar_component_set=None):
30
        """
31
        Create a new calendar for this principal.
32
        
33
        Parameters:
34
        - name: str, display name for the calendar
35
        - cal_id: str, unique identifier for the calendar
36
        - supported_calendar_component_set: list, supported component types
37
          (e.g., ['VEVENT', 'VTODO', 'VJOURNAL'])
38
        
39
        Returns:
40
        Calendar: Newly created calendar object
41
        
42
        Raises:
43
        DAVError: If calendar creation fails
44
        """
45
    
46
    def freebusy_request(self, start, end, attendees):
47
        """
48
        Request free/busy information for specified time range and attendees.
49
        
50
        Parameters:
51
        - start: datetime, start of time range
52
        - end: datetime, end of time range  
53
        - attendees: list[str], list of attendee email addresses
54
        
55
        Returns:
56
        FreeBusy: Free/busy information object
57
        """
58
    
59
    def calendar(self, name=None, cal_id=None, cal_url=None):
60
        """
61
        Get specific calendar by name, ID, or URL.
62
        
63
        Parameters:
64
        - name: str, calendar display name
65
        - cal_id: str, calendar identifier
66
        - cal_url: str, calendar URL
67
        
68
        Returns:
69
        Calendar: Calendar object or None if not found
70
        """
71
    
72
    def get_vcal_address(self):
73
        """
74
        Get principal as vCalAddress object for attendee management.
75
        
76
        Returns:
77
        vCalAddress: Principal's calendar user address
78
        """
79
    
80
    def calendar_user_address_set(self):
81
        """
82
        Get set of calendar user addresses for this principal.
83
        
84
        Returns:
85
        list[str]: Calendar user addresses
86
        """
87
    
88
    def schedule_inbox(self):
89
        """
90
        Get the schedule inbox for receiving calendar invitations.
91
        
92
        Returns:
93
        ScheduleInbox: Schedule inbox object
94
        """
95
    
96
    def schedule_outbox(self):
97
        """
98
        Get the schedule outbox for sending calendar invitations.
99
        
100
        Returns:
101
        ScheduleOutbox: Schedule outbox object
102
        """
103
```
104

105
**Usage Examples:**
106

107
```python
108
import caldav
109
from datetime import datetime, timedelta
110

111
# Get principal from client
112
client = caldav.DAVClient(url="...", username="...", password="...")
113
principal = client.principal()
114

115
# List all calendars
116
calendars = principal.calendars()
117
print(f"Found {len(calendars)} calendars:")
118
for cal in calendars:
119
    print(f"  - {cal.name} ({cal.id})")
120

121
# Create a new calendar
122
new_calendar = principal.make_calendar(
123
    name="Project Calendar",
124
    cal_id="project-cal-001",
125
    supported_calendar_component_set=['VEVENT', 'VTODO']
126
)
127

128
# Request free/busy information
129
start_time = datetime.now()
130
end_time = start_time + timedelta(days=7)
131
freebusy = principal.freebusy_request(
132
    start=start_time,
133
    end=end_time,
134
    attendees=["colleague@example.com", "manager@example.com"]
135
)
136
```
137

138
### Calendar Set Operations
139

140
Manages collections of calendars, providing organizational structure and batch operations across multiple calendars.
141

142
```python { .api }
143
class CalendarSet(DAVObject):
144
    def calendars(self):
145
        """
146
        List all calendar collections in this set.
147
        
148
        Returns:
149
        list[Calendar]: List of calendars in this set
150
        """
151
    
152
    def make_calendar(self, name=None, cal_id=None, supported_calendar_component_set=None):
153
        """
154
        Create a new calendar within this calendar set.
155
        
156
        Parameters:
157
        - name: str, display name for the calendar
158
        - cal_id: str, unique identifier for the calendar  
159
        - supported_calendar_component_set: list, supported component types
160
        
161
        Returns:
162
        Calendar: Newly created calendar object
163
        """
164
```
165

166
**Usage Examples:**
167

168
```python
169
# Note: calendar_sets() method is not available in this version
170
# CalendarSet objects are typically accessed indirectly through calendar discovery
171
```
172

173
### Calendar Discovery
174

175
Discover and access calendar properties, capabilities, and metadata for proper client integration and feature detection.
176

177
```python { .api }
178
# Calendar property access methods inherited from DAVObject
179
def get_property(self, prop):
180
    """
181
    Get a single property value from the calendar.
182
    
183
    Parameters:
184
    - prop: str or BaseElement, property to retrieve
185
    
186
    Returns:
187
    str: Property value
188
    """
189

190
def get_properties(self, props):
191
    """
192
    Get multiple property values from the calendar.
193
    
194
    Parameters:
195
    - props: list, properties to retrieve
196
    
197
    Returns:
198
    dict: Property name/value pairs
199
    """
200

201
def set_properties(self, props):
202
    """
203
    Set multiple properties on the calendar.
204
    
205
    Parameters:
206
    - props: dict, property name/value pairs to set
207
    """
208
```
209

210
**Usage Examples:**
211

212
```python
213
# Discover calendar properties
214
calendar = calendars[0]
215

216
# Get display name
217
display_name = calendar.get_property("displayname")
218
print(f"Calendar name: {display_name}")
219

220
# Get multiple properties
221
properties = calendar.get_properties([
222
    "displayname",
223
    "getcontenttype", 
224
    "calendar-description",
225
    "supported-calendar-component-set"
226
])
227

228
# Check supported components
229
supported_components = properties.get("supported-calendar-component-set", [])
230
print(f"Supported components: {supported_components}")
231

232
# Set calendar properties
233
calendar.set_properties({
234
    "displayname": "Updated Calendar Name",
235
    "calendar-description": "My personal calendar for work events"  
236
})
237
```
238

239
### Server Capability Detection
240

241
Detect CalDAV server capabilities and extensions to enable appropriate client functionality and feature availability.
242

243
```python { .api }
244
# Common CalDAV server capabilities that can be detected
245
CALDAV_CAPABILITIES = [
246
    "calendar-access",           # Basic CalDAV support (RFC 4791)
247
    "calendar-schedule",         # CalDAV Scheduling (RFC 6638) 
248
    "calendar-auto-schedule",    # Automatic scheduling
249
    "calendar-availability",     # Availability information
250
    "extended-mkcol",           # Extended MKCOL support
251
    "calendar-proxy",           # Calendar delegation/proxy
252
]
253
```
254

255
**Usage Examples:**
256

257
```python
258
# Check server capabilities through OPTIONS request
259
response = client.request(calendar.url, method="OPTIONS")
260
server_capabilities = response.headers.get("DAV", "").split(",")
261

262
# Detect CalDAV scheduling support
263
has_scheduling = "calendar-schedule" in server_capabilities
264
if has_scheduling:
265
    print("Server supports CalDAV scheduling extensions")
266
    
267
# Check for specific calendar features
268
calendar_features = calendar.get_property("supported-calendar-component-set")
269
supports_todos = "VTODO" in calendar_features
270
supports_journals = "VJOURNAL" in calendar_features
271

272
print(f"Calendar supports todos: {supports_todos}")
273
print(f"Calendar supports journals: {supports_journals}")
274
```
275

276
## Calendar Creation Options
277

278
```python { .api }
279
# Calendar component types
280
CALENDAR_COMPONENT_TYPES = [
281
    "VEVENT",      # Events
282
    "VTODO",       # Tasks/todos  
283
    "VJOURNAL",    # Journal entries
284
    "VFREEBUSY",   # Free/busy information
285
    "VTIMEZONE",   # Timezone definitions
286
    "VALARM",      # Alarms/reminders
287
]
288

289
# Common calendar properties for creation
290
CALENDAR_PROPERTIES = {
291
    "displayname": "str",                    # Calendar display name
292
    "calendar-description": "str",           # Calendar description
293
    "calendar-color": "str",                # Calendar color (CSS color)
294
    "calendar-order": "int",                # Display order
295
    "supported-calendar-component-set": "list",  # Supported components
296
    "calendar-timezone": "str",             # Default timezone
297
}
298
```
299

300
## Error Handling
301

302
Calendar and principal operations may raise standard CalDAV exceptions:
303

304
```python { .api }
305
# Common errors for principal and calendar operations
306
class NotFoundError(DAVError):
307
    """Resource not found or inaccessible."""
308

309
class AuthorizationError(DAVError):
310
    """Insufficient privileges for requested operation."""
311

312
class MkcalendarError(DAVError):
313
    """Calendar creation failed."""
314

315
class PropfindError(DAVError):
316
    """Property retrieval failed."""
317
```