objects – Object definitions

A “DAV object” is anything we get from the caldav server or push into the caldav server, notably principal, calendars and calendar events.

(This file has become huge and will be split up prior to the next release. I think it makes sense moving the CalendarObjectResource class hierarchy into a separate file)

class caldav.objects.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(ical, no_overwrite=False, no_create=False)

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

Parameters:
  • ical - ical object (text)
add_journal(ical, no_overwrite=False, no_create=False)

Add a new journal entry to the calendar, with the given ical.

Parameters:
  • ical - ical object (text)
add_todo(ical, no_overwrite=False, no_create=False)

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

Parameters:
  • ical - ical object (text)
build_date_search_query(start, end=None, compfilter='VEVENT', expand='maybe')

Split out from the date_search-method below. The idea is that maybe the generated query can be amended, i.e. to filter out by category etc. To be followed up in https://github.com/python-caldav/caldav/issues/16

calendar_multiget(event_urls)

get multiple events’ data @author mtorange@gmail.com @type events list of Event

Search events by date in the calendar. Recurring events are expanded if they are occuring during the specified time frame and if an end timestamp is given.

Parameters:
  • start = 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)
Returns:
  • [CalendarObjectResource(), …]
event_by_url(href, data=None)

Returns the event with the given URL

events()

List all events from the calendar.

Returns:
  • [Event(), …]
freebusy_request(start, end)

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

Parameters:
  • start = 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’])

journals()

List all journals from the calendar.

Returns:
  • [Journal(), …]
object_by_uid(uid, comp_filter=None)

Get one event from the calendar.

Parameters:
  • uid: the event uid
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 https://github.com/python-caldav/caldav/issues/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.

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 https://github.com/python-caldav/caldav/issues/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.

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(ical, no_overwrite=False, no_create=False)

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

Parameters:
  • ical - ical object (text)
save_journal(ical, no_overwrite=False, no_create=False)

Add a new journal entry to the calendar, with the given ical.

Parameters:
  • ical - ical object (text)
save_todo(ical, no_overwrite=False, no_create=False)

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

Parameters:
  • ical - ical object (text)
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.

search(xml, comp_class=None)

This method was partly written to approach https://github.com/python-caldav/caldav/issues/16 This is a result of some code refactoring, and after the next round of refactoring we’ve ended up with this:

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

fetches a list of todo events.

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.objects.CalendarObjectResource(client=None, url=None, data=None, parent=None, id=None, props=None)

Ref RFC 4791, section 4.1, a “Calendar Object Resource” can be an event, a todo-item, a journal entry, or a free/busy entry

add_attendee(attendee, no_default_parameters=False, **parameters)

For the current (event/todo/journal), add an attendee.

The attendee can be any of the following: * A principal * An email address prepended with “mailto:” * An email address without the “mailto:”-prefix * A two-item tuple containing a common name and an email address * (not supported, but planned: an ical text line starting with the word “ATTENDEE”)

Any number of attendee parameters can be given, those will be used as defaults unless no_default_parameters is set to True:

partstat=NEEDS-ACTION cutype=UNKNOWN (unless a principal object is given) rsvp=TRUE role=REQ-PARTICIPANT schedule-agent is not set

add_organizer()

goes via self.client, finds the principal, figures out the right attendee-format and adds an organizer line to the event

copy(keep_uid=False, new_parent=None)

Events, todos etc can be copied within the same calendar, to another calendar or even to another caldav server

data

vCal representation of the object

icalendar_instance

icalendar instance of the object

instance

vobject instance of the object

load()

Load the object from the caldav server.

save(no_overwrite=False, no_create=False, obj_type=None, if_schedule_tag_match=False)

Save the object, can be used for creation and update.

no_overwrite and no_create will check if the object exists. Those two are mutually exclusive. Some servers don’t support searching for an object uid without explicitly specifying what kind of object it should be, hence obj_type can be passed. obj_type is only used in conjunction with no_overwrite and no_create.

Returns:
  • self
vobject_instance

vobject instance of the object

class caldav.objects.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

Parameters:
  • name: return the calendar with this name
  • cal_id: return the calendar with this calendar id or URL
Returns:
  • Calendar(…)-object
calendars()

List all calendar collections in this set.

Returns:
  • [Calendar(), …]
make_calendar(name=None, cal_id=None, supported_calendar_component_set=None)

Utility method for creating a new calendar.

Parameters:
  • name: the 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.objects.DAVObject(client=None, url=None, parent=None, name=None, id=None, props=None, **extra)

Base class for all DAV objects. Can be instantiated by a client and an absolute or relative URL, or from the parent object.

children(type=None)

List children, using a propfind (resourcetype) on the parent object, at depth = 1.

delete()

Delete the object.

get_properties(props=None, depth=0, parse_response_xml=True, parse_props=True)

Get properties (PROPFIND) for this object.

With parse_response_xml and parse_props set to True a best-attempt will be done on decoding the XML we get from the server - but this works only for properties that don’t have complex types. With parse_response_xml set to False, a DAVResponse object will be returned, and it’s up to the caller to decode. With parse_props set to false but parse_response_xml set to true, xml elements will be returned rather than values.

Parameters:
  • props = [dav.ResourceType(), dav.DisplayName(), …]
Returns:
  • {proptag: value, …}
save()

Save the object. This is an abstract method, that all classes derived from DAVObject implement.

Returns:
  • self
set_properties(props=None)

Set properties (PROPPATCH) for this object.

  • props = [dav.DisplayName(‘name’), …]
Returns:
  • self
class caldav.objects.Event(client=None, url=None, data=None, parent=None, id=None, props=None)

The Event object is used to represent an event (VEVENT).

As of 2020-12 it adds nothing to the inheritated class. (I have frequently asked myself if we need those subclasses … perhaps not)

class caldav.objects.FreeBusy(parent, data, url=None, id=None)

The FreeBusy object is used to represent a freebusy response from the server. __init__ is overridden, as a FreeBusy response has no URL or ID. The inheritated methods .save and .load is moot and will probably throw errors (perhaps the class hierarchy should be rethought, to prevent the FreeBusy from inheritating moot methods)

Update: With RFC6638 a freebusy object can have an URL and an ID.

class caldav.objects.Journal(client=None, url=None, data=None, parent=None, id=None, props=None)

The Journal object is used to represent a journal entry (VJOURNAL).

As of 2020-12 it adds nothing to the inheritated class. (I have frequently asked myself if we need those subclasses … perhaps not)

class caldav.objects.Principal(client=None, url=None)

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)

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

calendar_user_address_set()

defined in RFC6638

calendars()

Return the principials calendars

get_vcal_address()

Returns the principal, as an icalendar.vCalAddress object

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.

class caldav.objects.ScheduleInbox(client=None, principal=None, url=None)
class caldav.objects.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.objects.ScheduleOutbox(client=None, principal=None, url=None)
class caldav.objects.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

class caldav.objects.Todo(client=None, url=None, data=None, parent=None, id=None, props=None)

The Todo object is used to represent a todo item (VTODO). A Todo-object can be completed.

complete(completion_timestamp=None)

Marks the task as completed.

This method probably will do the wrong thing if the task is a recurring task, in version 1.0 this will likely be changed - see https://github.com/python-caldav/caldav/issues/127 for details.

Parameters:
  • completion_timestamp - datetime object. Defaults to datetime.now().
caldav.objects.errmsg(r)

Utility for formatting a response xml tree to an error string