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: https://tools.ietf.org/html/rfc4791#section-5.3.1

add_event(*largs, **kwargs)

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

Return type:

Event

add_journal(*largs, **kwargs)

Returns self.save_object(Journal, ...) - so see save_object

Return type:

Journal

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

Add a new event to the calendar, with the given ical.

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

• dt_start – properties to be inserted into the icalendar object

, dt_end: 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 alamrs is not complete. Refer to the RFC or the icalendar library for a full list of properties.

add_todo(*largs, **kwargs)

Returns self.save_object(Todo, ...) - so see save_object

Return type:

Todo

build_search_xml_query(comp_class=None, todo=None, ignore_completed1=None, ignore_completed2=None, ignore_completed3=None, event=None, journal=None, filters=None, expand=None, start=None, end=None, props=None, alarm_start=None, alarm_end=None, **kwargs)

This method will produce a caldav search query as an etree object.

It is primarily to be used from the search method. See the documentation for the search method for more information.

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. Use self.search() instead.

Search events by date in the calendar.

Return type:

Sequence[CalendarObjectResource]

Args

start : defaults to datetime.today(). end : same as above. compfilter : defaults to events only. Set to None to fetch all calendar components. expand : should recurrent events be expanded? (to preserve backward-compatibility the default “maybe” will be changed into True unless the date_search is open-ended) verify_expand : not in use anymore, but kept for backward compatibility

Returns:

• [CalendarObjectResource(), …]

Recurring events are expanded if they are occurring during the specified time frame and if an end timestamp is given.

Note that this is a deprecated method. The search method is nearly equivalent. Differences: default for compfilter is to search for all objects, default for expand is False, and it has a different default split_expanded=True.

event(uid)

Returns the event with the given uid (wraps around object_by_uid)

Return type:

CalendarObjectResource

event_by_uid(uid)

Returns the event with the given uid (wraps around object_by_uid)

Return type:

CalendarObjectResource

event_by_url(href, data=None)

Returns the event with the given URL

Return type:

Event

events()

List all events from the calendar.

Return type:

List[Event]

Returns:

• [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_supported_components()

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

Return type:

List[Any]

journal_by_uid(uid)

Returns the journal with the given uid (wraps around object_by_uid)

Return type:

CalendarObjectResource

journals()

List all journals from the calendar.

Return type:

List[Journal]

Returns:

• [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(uid, comp_filter=None, comp_class=None)

Get one event from the calendar.

Return type:

Event

Parameters:

• uid – the event uid

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

• comp_filter – for backward compatibility

Returns:

Event() or None

objects(sync_token=None, load_objects=False)

objects_by_sync_token aka 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.

Return type:

SynchronizableCalendarObjectCollection

objects_by_sync_token(sync_token=None, load_objects=False)

objects_by_sync_token aka 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.

Return type:

SynchronizableCalendarObjectCollection

save()

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.

Returns:

• self

save_event(*largs, **kwargs)

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

Return type:

Event

save_journal(*largs, **kwargs)

Returns self.save_object(Journal, ...) - so see save_object

Return type:

Journal

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

Add a new event to the calendar, with the given ical.

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

• dt_start – properties to be inserted into the icalendar object

, dt_end: 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 alamrs is not complete. Refer to the RFC or the icalendar library for a full list of properties.

save_todo(*largs, **kwargs)

Returns self.save_object(Todo, ...) - so see save_object

Return type:

Todo

save_with_invites(ical, attendees, **attendeeoptions)

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

Return type:

None

search(xml=None, comp_class=None, todo=None, include_completed=False, sort_keys=(), sort_reverse=False, expand=False, server_expand=False, split_expanded=True, props=None, **kwargs)

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

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)]

todo_by_uid(uid)

Returns the task with the given uid (wraps around object_by_uid)

Return type:

CalendarObjectResource

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

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

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.

class caldav.collection.CalendarSet(client=None, url=None, parent=None, name=None, id=None, props=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()

List all calendar collections in this set.

Return type:

List[Calendar]

Returns:

• [Calendar(), …]

make_calendar(name=None, cal_id=None, supported_calendar_component_set=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.

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[Optional[str]]

calendars()

Return the principials calendars

Return type:

List[Calendar]

freebusy_request(dtstart, dtend, attendees)

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

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)

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

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

Return type:

Tuple[Any, Any]