Embed Size (px)
Citation preview
python-caldav DocumentationRelease 0.5.0
Cyril Robert
Mar 05, 2017
Contents
1 Contents 1
2 Python 3 7
3 Quickstart 9
4 More examples 11
5 Notable classes and workflow 13
6 Compatibility 15
7 Unit testing 17
8 Documentation 19
9 Indices and tables 21
Python Module Index 23
i
ii
CHAPTER 1
Contents
DAVClient – A simple DAV client
class caldav.davclient.DAVClient(url, proxy=None, username=None, password=None,auth=None, ssl_verify_cert=True)
Basic client for webdav, uses the requests lib; gives access to low-level operations towards the caldav server.
Unless you have special needs, you should probably care most about the __init__ and principal methods.
delete(url)Send a delete request.
mkcalendar(url, body=’‘, dummy=None)Send a mkcalendar request.
Parameters:
• url: url for the root of the mkcalendar
• body: XML request
• dummy: compatibility parameter
Returns
• DAVResponse
mkcol(url, body, dummy=None)Send a mkcol request.
Parameters:
• url: url for the root of the mkcol
• body: XML request
• dummy: compatibility parameter
Returns
1
python-caldav Documentation, Release 0.5.0
• DAVResponse
principal()Convenience method, it gives a bit more object-oriented feel to write client.principal() than Princi-pal(client).
This method returns a caldav.Principal object, with higher-level methods for dealing with the prin-cipals calendars.
propfind(url=None, props=’‘, depth=0)Send a propfind request.
Parameters:
• url: url for the root of the propfind.
• props = (xml request), properties we want
• depth: maximum recursion depth
Returns
• DAVResponse
proppatch(url, body, dummy=None)Send a proppatch request.
Parameters:
• url: url for the root of the propfind.
• body: XML propertyupdate request
• dummy: compatibility parameter
Returns
• DAVResponse
put(url, body, headers={})Send a put request.
report(url, query=’‘, depth=0)Send a report request.
Parameters:
• url: url for the root of the propfind.
• query: XML request
• depth: maximum recursion depth
Returns
• DAVResponse
request(url, method=’GET’, body=’‘, headers={})Actually sends the request
class caldav.davclient.DAVResponse(response)This class is a response from a DAV request. It is instantiated from the DAVClient class. End users of the libraryshould not need to know anything about this class. Since we often get XML responses, it tries to parse it intoself.tree
2 Chapter 1. Contents
python-caldav Documentation, Release 0.5.0
objects – Object definitions
A “DAV object” is anything we get from the caldav server or push into the caldav server, notably principal, calendarsand calendar events.
class caldav.objects.DAVObject(client=None, url=None, parent=None, name=None, id=None,**extra)
Base class for all DAV objects. Can be instantiated by a client and an absolute or relative URL, or from theparent object.
children(type=None)List children, using a propfind (resourcetype) on the parent object, at depth = 1.
delete()Delete the object.
get_properties(props=[], depth=0)Get properties (PROPFIND) for this object. Works only for properties, that don’t have complex types.
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=[])Set properties (PROPPATCH) for this object.
•props = [dav.DisplayName(‘name’), ...]
Returns:
• self
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.
calendar(name=None, cal_id=None)The calendar method will return a calendar object. It will not initiate any communication with the server.
calendars()Return the principials calendars
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 fordetails.
class caldav.objects.Calendar(client=None, url=None, parent=None, name=None, id=None, **ex-tra)
The Calendar object is used to represent a calendar collection. Refer to the RFC for details: http://www.ietf.org/rfc/rfc4791.txt
1.2. objects – Object definitions 3
python-caldav Documentation, Release 0.5.0
add_event(ical)Add a new event to the calendar, with the given ical.
Parameters:
• ical - ical object (text)
add_journal(ical)Add a new journal entry to the calendar, with the given ical.
Parameters:
• ical - ical object (text)
add_todo(ical)Add a new task to the calendar, with the given ical.
Parameters:
• ical - ical object (text)
date_search(start, end=None, compfilter=’VEVENT’)Search events by date in the calendar. Recurring events are expanded if they are occuring during thespecified 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.
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(), ...]
journals()List all journals from the calendar.
Returns:
• [Journal(), ...]
4 Chapter 1. Contents
python-caldav Documentation, Release 0.5.0
object_by_uid(uid, comp_filter=None)Get one event from the calendar.
Parameters:
• uid: the event uid
Returns:
• Event() or None
save()The save method for a calendar is only used to create it, for now. We know we have to create it when wedon’t have a url.
Returns:
• self
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. (‘prior-ity’,’due’)).
• include_completed: boolean - by default, only pending tasks are listed
• sort_key: DEPRECATED, for backwards compatibility with version 0.4.
class caldav.objects.Event(client=None, url=None, data=None, parent=None, id=None)The Event object is used to represent an event (VEVENT).
1.2. objects – Object definitions 5
python-caldav Documentation, Release 0.5.0
6 Chapter 1. Contents
CHAPTER 2
Python 3
The caldav library should work well both with python2 and python3.
7
python-caldav Documentation, Release 0.5.0
8 Chapter 2. Python 3
CHAPTER 3
Quickstart
from datetime import datetimeimport caldavfrom caldav.elements import dav, cdav
# Caldav urlurl = "https://user:pass@hostname/caldav.php/"
vcal = """BEGIN:VCALENDARVERSION:2.0PRODID:-//Example Corp.//CalDAV Client//ENBEGIN:VEVENTUID:1234567890DTSTAMP:20100510T182145ZDTSTART:20100512T170000ZDTEND:20100512T180000ZSUMMARY:This is an eventEND:VEVENTEND: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"
9
python-caldav Documentation, Release 0.5.0
results = calendar.date_search(datetime(2010, 5, 1), datetime(2010, 6, 1))
for event in results:print "Found", event
10 Chapter 3. Quickstart
CHAPTER 4
More examples
See the test code for more usage examples. Tobias Brox is also working on a command line interface built around thecaldav library.
11
python-caldav Documentation, Release 0.5.0
12 Chapter 4. More examples
CHAPTER 5
Notable classes and workflow
• You’d always start by initiating a caldav.davclient.DAVClient object, this object holds the authenti-cation details for the server.
• From the client object one can get hold of a caldav.objects.Principal object representing the loggedin principal.
• From the principal object one can fetch / generate caldav.objects.Calendar objects. Calendar objectscan 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 URLand the client object.
Note that those are also available as caldav.DAVClient, caldav.Principal, caldav.Calendar,caldav.Event and caldav.Todo.
13
python-caldav Documentation, Release 0.5.0
14 Chapter 5. Notable classes and workflow
CHAPTER 6
Compatibility
The test suite is regularly run against Baikal, DAViCal, Zimbra and Bedework. Some compatibility issues have beenfound, 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) maybehave a bit unexpectedly.
• How would you expect the result to be when doing date searches spanning multiple instances of a recurringevent? Would you expect one ical object for each occurrence (and maybe that’s why open-ended date searchestend 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.
15
python-caldav Documentation, Release 0.5.0
16 Chapter 6. Compatibility
CHAPTER 7
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 sametime. 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. Youmay 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)
17
python-caldav Documentation, Release 0.5.0
18 Chapter 7. Unit testing
CHAPTER 8
Documentation
To build the documentation, install sphinx and run:
$ python setup.py build_sphinx
19
python-caldav Documentation, Release 0.5.0
20 Chapter 8. Documentation
CHAPTER 9
Indices and tables
• genindex
• modindex
• search
21
python-caldav Documentation, Release 0.5.0
22 Chapter 9. Indices and tables
Python Module Index
ccaldav.davclient, 1caldav.objects, 3
23
python-caldav Documentation, Release 0.5.0
24 Python Module Index
Index
Aadd_event() (caldav.objects.Calendar method), 3add_journal() (caldav.objects.Calendar method), 4add_todo() (caldav.objects.Calendar method), 4
Ccaldav.davclient (module), 1caldav.objects (module), 3Calendar (class in caldav.objects), 3calendar() (caldav.objects.Principal method), 3calendars() (caldav.objects.Principal method), 3children() (caldav.objects.DAVObject method), 3
Ddate_search() (caldav.objects.Calendar method), 4DAVClient (class in caldav.davclient), 1DAVObject (class in caldav.objects), 3DAVResponse (class in caldav.davclient), 2delete() (caldav.davclient.DAVClient method), 1delete() (caldav.objects.DAVObject method), 3
EEvent (class in caldav.objects), 5event_by_url() (caldav.objects.Calendar method), 4events() (caldav.objects.Calendar method), 4
Ffreebusy_request() (caldav.objects.Calendar method), 4
Gget_properties() (caldav.objects.DAVObject method), 3
Jjournals() (caldav.objects.Calendar method), 4
Mmake_calendar() (caldav.objects.Principal method), 3mkcalendar() (caldav.davclient.DAVClient method), 1
mkcol() (caldav.davclient.DAVClient method), 1
Oobject_by_uid() (caldav.objects.Calendar method), 4
PPrincipal (class in caldav.objects), 3principal() (caldav.davclient.DAVClient method), 2propfind() (caldav.davclient.DAVClient method), 2proppatch() (caldav.davclient.DAVClient method), 2put() (caldav.davclient.DAVClient method), 2
Rreport() (caldav.davclient.DAVClient method), 2request() (caldav.davclient.DAVClient method), 2
Ssave() (caldav.objects.Calendar method), 5save() (caldav.objects.DAVObject method), 3set_properties() (caldav.objects.DAVObject method), 3
Ttodos() (caldav.objects.Calendar method), 5
25
