Principal & Calendar Discovery

class Principal(DAVObject):
    def calendars(self):
        """
        Get all calendars accessible to this principal.
        
        Returns:
        list[Calendar]: List of Calendar objects
        """
    
    
    def calendar_home_set(self):
        """
        Get the calendar home set URL for this principal.
        
        Returns:
        str: Calendar home set URL
        """
    
    def make_calendar(self, name=None, cal_id=None, supported_calendar_component_set=None):
        """
        Create a new calendar for this principal.
        
        Parameters:
        - name: str, display name for the calendar
        - cal_id: str, unique identifier for the calendar
        - supported_calendar_component_set: list, supported component types
          (e.g., ['VEVENT', 'VTODO', 'VJOURNAL'])
        
        Returns:
        Calendar: Newly created calendar object
        
        Raises:
        DAVError: If calendar creation fails
        """
    
    def freebusy_request(self, start, end, attendees):
        """
        Request free/busy information for specified time range and attendees.
        
        Parameters:
        - start: datetime, start of time range
        - end: datetime, end of time range  
        - attendees: list[str], list of attendee email addresses
        
        Returns:
        FreeBusy: Free/busy information object
        """
    
    def calendar(self, name=None, cal_id=None, cal_url=None):
        """
        Get specific calendar by name, ID, or URL.
        
        Parameters:
        - name: str, calendar display name
        - cal_id: str, calendar identifier
        - cal_url: str, calendar URL
        
        Returns:
        Calendar: Calendar object or None if not found
        """
    
    def get_vcal_address(self):
        """
        Get principal as vCalAddress object for attendee management.
        
        Returns:
        vCalAddress: Principal's calendar user address
        """
    
    def calendar_user_address_set(self):
        """
        Get set of calendar user addresses for this principal.
        
        Returns:
        list[str]: Calendar user addresses
        """
    
    def schedule_inbox(self):
        """
        Get the schedule inbox for receiving calendar invitations.
        
        Returns:
        ScheduleInbox: Schedule inbox object
        """
    
    def schedule_outbox(self):
        """
        Get the schedule outbox for sending calendar invitations.
        
        Returns:
        ScheduleOutbox: Schedule outbox object
        """

import caldav
from datetime import datetime, timedelta

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

# List all calendars
calendars = principal.calendars()
print(f"Found {len(calendars)} calendars:")
for cal in calendars:
    print(f"  - {cal.name} ({cal.id})")

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

# Request free/busy information
start_time = datetime.now()
end_time = start_time + timedelta(days=7)
freebusy = principal.freebusy_request(
    start=start_time,
    end=end_time,
    attendees=["colleague@example.com", "manager@example.com"]
)

class CalendarSet(DAVObject):
    def calendars(self):
        """
        List all calendar collections in this set.
        
        Returns:
        list[Calendar]: List of calendars in this set
        """
    
    def make_calendar(self, name=None, cal_id=None, supported_calendar_component_set=None):
        """
        Create a new calendar within this calendar set.
        
        Parameters:
        - name: str, display name for the calendar
        - cal_id: str, unique identifier for the calendar  
        - supported_calendar_component_set: list, supported component types
        
        Returns:
        Calendar: Newly created calendar object
        """

# Note: calendar_sets() method is not available in this version
# CalendarSet objects are typically accessed indirectly through calendar discovery

# Calendar property access methods inherited from DAVObject
def get_property(self, prop):
    """
    Get a single property value from the calendar.
    
    Parameters:
    - prop: str or BaseElement, property to retrieve
    
    Returns:
    str: Property value
    """

def get_properties(self, props):
    """
    Get multiple property values from the calendar.
    
    Parameters:
    - props: list, properties to retrieve
    
    Returns:
    dict: Property name/value pairs
    """

def set_properties(self, props):
    """
    Set multiple properties on the calendar.
    
    Parameters:
    - props: dict, property name/value pairs to set
    """

# Discover calendar properties
calendar = calendars[0]

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

# Get multiple properties
properties = calendar.get_properties([
    "displayname",
    "getcontenttype", 
    "calendar-description",
    "supported-calendar-component-set"
])

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

# Set calendar properties
calendar.set_properties({
    "displayname": "Updated Calendar Name",
    "calendar-description": "My personal calendar for work events"  
})

# Common CalDAV server capabilities that can be detected
CALDAV_CAPABILITIES = [
    "calendar-access",           # Basic CalDAV support (RFC 4791)
    "calendar-schedule",         # CalDAV Scheduling (RFC 6638) 
    "calendar-auto-schedule",    # Automatic scheduling
    "calendar-availability",     # Availability information
    "extended-mkcol",           # Extended MKCOL support
    "calendar-proxy",           # Calendar delegation/proxy
]

# Check server capabilities through OPTIONS request
response = client.request(calendar.url, method="OPTIONS")
server_capabilities = response.headers.get("DAV", "").split(",")

# Detect CalDAV scheduling support
has_scheduling = "calendar-schedule" in server_capabilities
if has_scheduling:
    print("Server supports CalDAV scheduling extensions")
    
# Check for specific calendar features
calendar_features = calendar.get_property("supported-calendar-component-set")
supports_todos = "VTODO" in calendar_features
supports_journals = "VJOURNAL" in calendar_features

print(f"Calendar supports todos: {supports_todos}")
print(f"Calendar supports journals: {supports_journals}")

# Calendar component types
CALENDAR_COMPONENT_TYPES = [
    "VEVENT",      # Events
    "VTODO",       # Tasks/todos  
    "VJOURNAL",    # Journal entries
    "VFREEBUSY",   # Free/busy information
    "VTIMEZONE",   # Timezone definitions
    "VALARM",      # Alarms/reminders
]

# Common calendar properties for creation
CALENDAR_PROPERTIES = {
    "displayname": "str",                    # Calendar display name
    "calendar-description": "str",           # Calendar description
    "calendar-color": "str",                # Calendar color (CSS color)
    "calendar-order": "int",                # Display order
    "supported-calendar-component-set": "list",  # Supported components
    "calendar-timezone": "str",             # Default timezone
}

# Common errors for principal and calendar operations
class NotFoundError(DAVError):
    """Resource not found or inaccessible."""

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

class MkcalendarError(DAVError):
    """Calendar creation failed."""

class PropfindError(DAVError):
    """Property retrieval failed."""