Documentation: caldav 0.5.0

Python 3

The caldav library should work well both with python2 and python3.

Quickstart

from datetime import datetime
import caldav
from caldav.elements import dav, cdav

# Caldav url
url = "https://user:pass@hostname/caldav.php/"

vcal = """BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Client//EN
BEGIN:VEVENT
UID:1234567890
DTSTAMP:20100510T182145Z
DTSTART:20100512T170000Z
DTEND:20100512T180000Z
SUMMARY:This is an event
END:VEVENT
END:VCALENDAR
"""

client = caldav.DAVClient(url)
principal = client.principal()
calendars = principal.calendars()
if len(calendars) > 0:
    calendar = calendars[0]
    print "Using calendar", calendar

    print "Renaming"
    calendar.set_properties([dav.DisplayName("Test calendar"),])
    print calendar.get_properties([dav.DisplayName(),])

    event = calendar.add_event(vcal)
    print "Event", event, "created"

    print "Looking for events in 2010-05"
    results = calendar.date_search(
        datetime(2010, 5, 1), datetime(2010, 6, 1))

    for event in results:
        print "Found", event

More examples

See the test code for more usage examples. Tobias Brox is also working on a command line interface built around the caldav library.

Notable classes and workflow

  • You’d always start by initiating a caldav.davclient.DAVClient object, this object holds the authentication details for the server.
  • From the client object one can get hold of a caldav.objects.Principal object representing the logged in principal.
  • From the principal object one can fetch / generate caldav.objects.Calendar objects. Calendar objects can also be instantiated directly from an absolute or relative URL and the client object.
  • From the calendar object one can fetch / generate caldav.objects.Event objects and caldav.objects.Todo objects. Event objects can also be instantiated directly from an absolute or relative URL and the client object.

Note that those are also available as caldav.DAVClient, caldav.Principal, caldav.Calendar, caldav.Event and caldav.Todo.

Compatibility

The test suite is regularly run against Baikal, DAViCal, Zimbra and Bedework. Some compatibility issues have been found, search the test code for “COMPATIBILITY” for details. Notably;

  • You may want to avoid non-ASCII characters in the calendar name, or some servers (at least Zimbra) may behave a bit unexpectedly.
  • How would you expect the result to be when doing date searches spanning multiple instances of a recurring event? Would you expect one ical object for each occurrence (and maybe that’s why open-ended date searches tend to break at some implementations) or one recurring ical object? Different servers behave a bit differently (but more research is needed on this one).
  • Date search for future instances or recurring events does not seem to work in Bedework.
  • There are some special hacks both in the code and the tests to work around compatibility issues in Zimbra.
  • The Radicale caldav server seems to be too radical - lots and lots of tests fails towards it.
  • Bedework and Zimbra does not support journal entries (but who uses those anyway?).
  • Bedework is supposed to support todo-lists, but queries for “all non-completed tasks” does not work.
  • iCloud - we’ve managed read-only access to iCloud so far - see https://bitbucket.org/cyrilrbt/caldav/issue/40/icloud-not-fully-supported for details.

Unit testing

To start the tests code, run:

$ python setup.py nosetests

Note that there is a big bug in the functional tests; if the test suite is run in parallell towards the same servers/principals, some tests will fail or raise exceptions, and this may very well happen if multiple developers runs the tests at the same time. This hasn’t been a problem so far.

It will run some unit tests and some functional tests against some dedicated caldav servers hosted by Tobias Brox. You may add your own private servers into tests/conf_private.py, like this:

caldav_servers = [{
    "url": "https://myserver.example.com:80/caldav.php/",
    'username': 'testuser',
    'password': 'hunter2'}]
the dict may contain:
  • username and password (if not embedded in the URL)
  • principal_url (used to verify client.principal().url)
  • backwards_compatibility_url (deprecated - URLs that worked with caldav versions prior to 0.2 goes here)

Documentation

To build the documentation, install sphinx and run:

$ python setup.py build_sphinx

Indices and tables