collection – Calendars, calendar sets, mailboxes and principal

I’m trying to be consistent with the terminology in the RFCs:

CalendarSet is a collection of Calendars Calendar is a collection of CalendarObjectResources Principal is not a collection, but holds a CalendarSet.

There are also some Mailbox classes to deal with RFC6638.

A SynchronizableCalendarObjectCollection contains a local copy of objects from a calendar on the server.

class caldav.collection.Calendar(client=None, url=None, parent=None, name=None, id=None, props=None, **extra)

The Calendar object is used to represent a calendar collection. Refer to the RFC for details: RFC 4791 Section 5.3.1.

add_event(*largs, **kwargs)

Add an event to the calendar.

Returns self.add_object(Event, ...) - see add_object()

Return type:

Event

add_journal(*largs, **kwargs)

Add a journal entry to the calendar.

Returns self.add_object(Journal, ...) - see add_object()

Return type:

Journal

add_object(objclass, ical=None, no_overwrite=False, no_create=False, **ical_data)

Add a new calendar object (event, todo, journal) to the calendar.

This method is for adding new content to the calendar. To update an existing object, fetch it first and use object.save().

Return type:

CalendarResourceObject

Parameters:

• objclass – Event, Journal or Todo

• ical – ical object (text, icalendar or vobject instance)

• no_overwrite – existing calendar objects should not be overwritten

• no_create – don’t create a new object, existing calendar objects should be updated

• dtstart – properties to be inserted into the icalendar object

• dtend – properties to be inserted into the icalendar object

• summary – properties to be inserted into the icalendar object

• alarm_trigger – when given, one alarm will be added

• alarm_action – when given, one alarm will be added

• alarm_attach – when given, one alarm will be added

Note that the list of parameters going into the icalendar object and alarms is not complete. Refer to the RFC or the icalendar library for a full list of properties.

add_todo(*largs, **kwargs)

Add a todo/task to the calendar.

Returns self.add_object(Todo, ...) - see add_object()

Return type:

Todo

calendar_multiget(*largs, **kwargs)

get multiple events’ data @author mtorange@gmail.com (refactored by Tobias) This is for backward compatibility. It may be removed in 3.0 or later release.

date_search(start, end=None, compfilter='VEVENT', expand='maybe', verify_expand=False)

Deprecated since version 3.0: Use search() instead. This method will be removed in 4.0.

Search events by date in the calendar.

Return type:

Sequence[CalendarObjectResource]

Parameters:

• start – Start of the date range to search.

• end – End of the date range (optional for open-ended search).

• compfilter – Component type to search for. Defaults to “VEVENT”. Set to None to fetch all calendar components.

• expand – Should recurrent events be expanded? Default “maybe” becomes True unless the search is open-ended.

• verify_expand – Not in use anymore, kept for backward compatibility.

Returns:

List of CalendarObjectResource objects matching the search.

Example (migrate to search):

# Legacy (deprecated):
events = calendar.date_search(start, end, expand=True)

# Recommended:
events = calendar.search(start=start, end=end, event=True, expand=True)

delete()

Delete the calendar.

For async clients, returns a coroutine that must be awaited.

event(uid)

Deprecated: Use get_event_by_uid() instead.

This method is an alias kept for backwards compatibility.

Return type:

CalendarObjectResource

event_by_uid(uid)

Deprecated: Use get_event_by_uid() instead.

This method is an alias kept for backwards compatibility.

Return type:

CalendarObjectResource

event_by_url(href, data=None)

Returns the event with the given URL.

Return type:

Event

events()

Deprecated: Use get_events() instead.

This method is an alias kept for backwards compatibility.

Return type:

list[Event]

freebusy_request(start, end)

Search the calendar, but return only the free/busy information.

Return type:

FreeBusy

Parameters:

• start – defaults to datetime.today().

• end – same as above.

Returns:

[FreeBusy(), …]

get_event_by_uid(uid)

Get an event from the calendar by UID.

Returns the event with the given uid. See get_object_by_uid() for more details.

Return type:

CalendarObjectResource

get_events()

List all events from the calendar.

For sync clients, returns a list of Event objects directly. For async clients, returns a coroutine that must be awaited.

Return type:

list[Event]

Returns:

• [Event(), …]

Example (sync):

events = calendar.get_events()

Example (async):

events = await calendar.get_events()

get_journal_by_uid(uid)

Get a journal entry from the calendar by UID.

Returns the journal with the given uid. See get_object_by_uid() for more details.

Return type:

CalendarObjectResource

get_journals()

List all journals from the calendar.

Return type:

list[Journal]

Returns:

• [Journal(), …]

get_object_by_uid(uid, comp_filter=None, comp_class=None)

Get one calendar object from the calendar by UID.

Return type:

Event

Parameters:

• uid – the object uid

• comp_class – filter by component type (Event, Todo, Journal)

• comp_filter – for backward compatibility. Don’t use!

Returns:

CalendarObjectResource (Event, Todo, or Journal)

get_objects(sync_token=None, load_objects=False, disable_fallback=False)

get_objects_by_sync_token aka get_objects

Do a sync-collection report, ref RFC 6578 and python-caldav/caldav#87

This method will return all objects in the calendar if no sync_token is passed (the method should then be referred to as “objects”), or if the sync_token is unknown to the server. If a sync-token known by the server is passed, it will return objects that are added, deleted or modified since last time the sync-token was set.

If load_objects is set to True, the objects will be loaded - otherwise empty CalendarObjectResource objects will be returned.

This method will return a SynchronizableCalendarObjectCollection object, which is an iterable.

This method transparently falls back to retrieving all objects if the server doesn’t support sync tokens. The fallback behavior is identical from the user’s perspective, but less efficient as it transfers the entire calendar on each sync.

If disable_fallback is set to True, the method will raise an exception instead of falling back to retrieving all objects. This is useful for testing whether the server truly supports sync tokens.

Return type:

SynchronizableCalendarObjectCollection

get_objects_by_sync_token(sync_token=None, load_objects=False, disable_fallback=False)

get_objects_by_sync_token aka get_objects

Do a sync-collection report, ref RFC 6578 and python-caldav/caldav#87

This method will return all objects in the calendar if no sync_token is passed (the method should then be referred to as “objects”), or if the sync_token is unknown to the server. If a sync-token known by the server is passed, it will return objects that are added, deleted or modified since last time the sync-token was set.

If load_objects is set to True, the objects will be loaded - otherwise empty CalendarObjectResource objects will be returned.

This method will return a SynchronizableCalendarObjectCollection object, which is an iterable.

This method transparently falls back to retrieving all objects if the server doesn’t support sync tokens. The fallback behavior is identical from the user’s perspective, but less efficient as it transfers the entire calendar on each sync.

If disable_fallback is set to True, the method will raise an exception instead of falling back to retrieving all objects. This is useful for testing whether the server truly supports sync tokens.

Return type:

SynchronizableCalendarObjectCollection

get_supported_components()

returns a list of component types supported by the calendar, in string format (typically [‘VJOURNAL’, ‘VTODO’, ‘VEVENT’])

Return type:

list[Any]

get_todo_by_uid(uid)

Get a task/todo from the calendar by UID.

Returns the task with the given uid. See get_object_by_uid() for more details.

Return type:

CalendarObjectResource

get_todos(sort_keys=('due', 'priority'), include_completed=False, sort_key=None)

Fetches a list of todo items (this is a wrapper around search).

For sync clients, returns a list of Todo objects directly. For async clients, returns a coroutine that must be awaited.

Return type:

list[Todo]

Parameters:

• sort_keys – use this field in the VTODO for sorting (iterable of lower case string, i.e. (‘priority’,’due’)).

• include_completed – boolean - by default, only pending tasks are listed

• sort_key – DEPRECATED, for backwards compatibility with version 0.4.

Example (sync):

todos = calendar.get_todos()

Example (async):

todos = await calendar.get_todos()

journal_by_uid(uid)

Deprecated: Use get_journal_by_uid() instead.

This method is an alias kept for backwards compatibility.

Return type:

CalendarObjectResource

journals()

Deprecated: Use get_journals() instead.

This method is an alias kept for backwards compatibility.

Return type:

list[Journal]

multiget(event_urls, raise_notfound=False)

get multiple events’ data TODO: Does it overlap the _request_report_build_resultlist method? @author mtorange@gmail.com (refactored by Tobias)

Return type:

Iterable[TypeVar(_CC, bound= CalendarObjectResource)]

object_by_uid(*largs, **kwargs)

Deprecated: Use get_object_by_uid() instead.

This method is an alias kept for backwards compatibility.

Return type:

CalendarObjectResource

objects(*largs, **kwargs)

Deprecated: Use get_objects_by_sync_token() instead.

This method is an alias kept for backwards compatibility.

Return type:

SynchronizableCalendarObjectCollection

objects_by_sync_token(*largs, **kwargs)

Deprecated: Use get_objects_by_sync_token() instead.

This method is an alias kept for backwards compatibility.

Return type:

SynchronizableCalendarObjectCollection

save(method=None)

The save method for a calendar is only used to create it, for now. We know we have to create it when we don’t have a url.

For async clients, returns a coroutine that must be awaited.

Returns:

• self

save_event(*largs, **kwargs)

Deprecated: Use add_event() instead.

This method is an alias kept for backwards compatibility. See python-caldav/caldav#71

Return type:

Event

save_journal(*largs, **kwargs)

Deprecated: Use add_journal() instead.

This method is an alias kept for backwards compatibility. See python-caldav/caldav#71

Return type:

Journal

save_object(*largs, **kwargs)

Deprecated: Use add_object() instead.

This method is an alias kept for backwards compatibility. See python-caldav/caldav#71

Return type:

CalendarResourceObject

save_todo(*largs, **kwargs)

Deprecated: Use add_todo() instead.

This method is an alias kept for backwards compatibility. See python-caldav/caldav#71

Return type:

Todo

save_with_invites(ical, attendees, **attendeeoptions)

sends a schedule request to the server. Equivalent with add_event, add_todo, etc, but the attendees will be added to the ical object before sending it to the server.

Return type:

None

search(xml=None, server_expand=False, split_expanded=True, sort_reverse=False, props=None, filters=None, post_filter=None, _hacks=None, **searchargs)

Sends a search request towards the server, processes the results if needed and returns the objects found.

Refactoring 2025-11: a new class class:caldav.search.CalDAVSearcher has been made, and this method is sort of a wrapper for CalDAVSearcher.search, ensuring backward compatibility. The documentation may be slightly overlapping.

I believe that for simple tasks, this method will be easier to use than the new interface, hence there are no plans for the foreseeable future to deprecate it. This search method will continue working as it has been doing before for all foreseeable future. I believe that for simple tasks, this method will be easier to use than to construct a CalDAVSearcher object and do searches from there. The refactoring was made necessary because the parameter list to search was becoming unmanagable. Advanced searches should be done via the new interface.

Caveat: The searching is done on the server side, the RFC is not very crystal clear on many of the corner cases, and servers often behave differently when presented with a search request. There is planned work to work around server incompatibilities on the client side, but as for now complicated searches will give different results on different servers.

todo - searches explicitly for todo. Unless include_completed is specified, there is some special logic ensuring only pending tasks is returned.

There is corresponding event and journal bools to specify that the search should be only for events or journals. When neither are set, one should expect to get all objects returned - but quite some calendar servers will return nothing. This will be solved client-side in the future, as for 2.0 it’s recommended to search separately for tasks, events and journals to ensure consistent behaviour across different calendar servers and providers.

sort_keys refers to (case-insensitive) properties in the icalendar object, sort_reverse can also be given. The sorting will be done client-side.

Use start and end for time-range searches. Open-ended searches are supported (i.e. “everything in the future”), but it’s recommended to use closed ranges (i.e. have an “event horizon” of a year and ask for “everything from now and one year ahead”) and get the data expanded.

With the boolean expand set, you don’t have to think too much about recurrences - they will be expanded, and with the (default) split_expanded set, each recurrence will be returned as a separate list object (otherwise all recurrences will be put into one VCALENDAR and returned as one Event). This makes it safe to use the event.component property. The non-expanded resultset may include events where the timespan doesn’t match the date interval you searched for, as well as items with multiple components (“special” recurrences), meaning you may need logic on the client side to handle the recurrences. Only time range searches over closed time intervals may be expanded.

As for 2.0, the expand-logic is by default done on the client-side, for consistent results across various server incompabilities. However, you may force server-side expansion by setting server_expand=True

Text attribute search parameters can be given to query the “properties” in the calendar data: category, uid, summary, comment, description, location, status. According to the RFC, a substring search should be done.

You may use no_category, no_summary, etc to search for objects that are missing those attributes.

Negated text matches are not supported yet.

For power-users, those parameters are also supported:

• xml - use this search query, and ignore other filter parameters

• comp_class - alternative to the event, todo or journal booleans described above.

• filters - other kind of filters (in lxml tree format)

Return type:

list[TypeVar(_CC, bound= CalendarObjectResource)]

searcher(**searchargs)

Create a searcher object for building complex search queries.

This is the recommended way to perform advanced searches. The returned searcher can have filters added, and then be executed:

searcher = calendar.searcher(event=True, start=..., end=...)
searcher.add_property_filter("SUMMARY", "meeting")
results = searcher.search()

For simple searches, use search() directly instead.

Parameters:

searchargs – Search parameters (same as for search())

Return type:

CalDAVSearcher

Returns:

A CalDAVSearcher bound to this calendar

See caldav.search.CalDAVSearcher for available filter methods.

todo_by_uid(uid)

Deprecated: Use get_todo_by_uid() instead.

This method is an alias kept for backwards compatibility.

Return type:

CalendarObjectResource

todos(*largs, **kwargs)

Deprecated: Use get_todos() instead.

This method is an alias kept for backwards compatibility.

Return type:

list[Todo]

class caldav.collection.CalendarSet(client=None, url=None, parent=None, id=None, props=None, name=None, **extra)

A CalendarSet is a set of calendars.

calendar(name=None, cal_id=None)

The calendar method will return a calendar object. If it gets a cal_id but no name, it will not initiate any communication with the server

Return type:

Calendar

Parameters:

• name – return the calendar with this display name

• cal_id – return the calendar with this calendar id or URL

Returns:

Calendar(…)-object

calendars()

Deprecated: Use get_calendars() instead.

This method is an alias kept for backwards compatibility.

Return type:

list[Calendar]

get_calendars()

List all calendar collections in this set.

For sync clients, returns a list of Calendar objects directly. For async clients, returns a coroutine that must be awaited.

Return type:

list[Calendar]

Returns:

• [Calendar(), …]

Example (sync):

calendars = calendar_set.get_calendars()

Example (async):

calendars = await calendar_set.get_calendars()

make_calendar(name=None, cal_id=None, supported_calendar_component_set=None, method=None)

Utility method for creating a new calendar.

Return type:

Calendar

Parameters:

• name – the display name of the new calendar

• cal_id – the uuid of the new calendar

• supported_calendar_component_set – what kind of objects (EVENT, VTODO, VFREEBUSY, VJOURNAL) the calendar should handle. Should be set to [‘VTODO’] when creating a task list in Zimbra - in most other cases the default will be OK.

• method – ‘mkcalendar’ or ‘mkcol’ - usually auto-detected

For async clients, returns a coroutine that must be awaited.

Returns:

Calendar(…)-object

class caldav.collection.Principal(client=None, url=None, calendar_home_set=None, **kwargs)

This class represents a DAV Principal. It doesn’t do much, except keep track of the URLs for the calendar-home-set, etc.

A principal MUST have a non-empty DAV:displayname property (defined in Section 13.2 of [RFC2518]), and a DAV:resourcetype property (defined in Section 13.9 of [RFC2518]). Additionally, a principal MUST report the DAV:principal XML element in the value of the DAV:resourcetype property.

(TODO: the resourcetype is actually never checked, and the DisplayName is not stored anywhere)

calendar(name=None, cal_id=None, cal_url=None)

The calendar method will return a calendar object. It will not initiate any communication with the server.

Return type:

Calendar

calendar_user_address_set()

defined in RFC6638

Return type:

list[str | None]

calendars()

Deprecated: Use get_calendars() instead.

This method is an alias kept for backwards compatibility.

Return type:

list[Calendar]

async classmethod create(client, url=None, calendar_home_set=None)

Create a Principal, discovering URL if not provided.

This is the recommended way to create a Principal with async clients as it handles async URL discovery.

For sync clients, you can use the regular constructor: Principal(client)

Return type:

Principal

Parameters:

• client – A DAVClient or AsyncDAVClient instance

• url – The principal URL (if known)

• calendar_home_set – The calendar home set URL (if known)

Returns:

Principal with URL discovered if not provided

Example (async):

principal = await Principal.create(async_client)

freebusy_request(dtstart, dtend, attendees)

Sends a freebusy-request for some attendee to the server as per RFC6638.

get_calendars()

Return the principal’s calendars.

For sync clients, returns a list of Calendar objects directly. For async clients, returns a coroutine that must be awaited.

Return type:

list[Calendar]

Example (sync):

calendars = principal.get_calendars()

Example (async):

calendars = await principal.get_calendars()

get_vcal_address()

Returns the principal, as an icalendar.vCalAddress object.

Return type:

vCalAddress

make_calendar(name=None, cal_id=None, supported_calendar_component_set=None, method=None)

Convenience method, bypasses the self.calendar_home_set object. See CalendarSet.make_calendar for details.

For async clients, returns a coroutine that must be awaited.

Return type:

Calendar

schedule_inbox()

Returns the schedule inbox, as defined in RFC6638

Return type:

ScheduleInbox

schedule_outbox()

Returns the schedule outbox, as defined in RFC6638

Return type:

ScheduleOutbox

class caldav.collection.ScheduleInbox(client=None, principal=None, url=None)

class caldav.collection.ScheduleMailbox(client=None, principal=None, url=None)

RFC6638 defines an inbox and an outbox for handling event scheduling.

TODO: As ScheduleMailboxes works a bit like calendars, I’ve chosen to inheritate the Calendar class, but this is a bit incorrect, a ScheduleMailbox is a collection, but not really a calendar. We should create a common base class for ScheduleMailbox and Calendar eventually.

get_items()

TODO: work in progress TODO: perhaps this belongs to the super class?

class caldav.collection.ScheduleOutbox(client=None, principal=None, url=None)

class caldav.collection.SynchronizableCalendarObjectCollection(calendar, objects, sync_token)

This class may hold a cached snapshot of a calendar, and changes in the calendar can easily be copied over through the sync method.

To create a SynchronizableCalendarObjectCollection object, use calendar.objects(load_objects=True)

objects_by_url()

returns a dict of the contents of the SynchronizableCalendarObjectCollection, URLs -> objects.

sync()

This method will contact the caldav server, request all changes from it, and sync up the collection.

This method transparently falls back to comparing full calendar state if the server doesn’t support sync tokens.

Return type:

tuple[Any, Any]