DAVClient – A simple DAV client

class caldav.davclient.DAVClient(url, proxy=None, username=None, password=None, auth=None, auth_type=None, timeout=None, ssl_verify_cert=True, ssl_cert=None, headers=None, huge_tree=False)

Basic client for webdav, uses the niquests lib; gives access to low-level operations towards the caldav server.

Unless you have special needs, you should probably care most about the constructor (__init__), the principal method and the calendar method.

build_auth_object(auth_types=None)

Fixes self.auth. If self.auth_type is given, then insist on using this one. If not, then assume auth_types to be a list of acceptable auth types and choose the most appropriate one (prefer digest or basic if username is given, and bearer if password is given).

Parameters:

auth_types (auth_types - A list/tuple of acceptable)

calendar(**kwargs)

Returns a calendar object.

Typically, a URL should be given as a named parameter (url)

No network traffic will be initiated by this method.

If you don’t know the URL of the calendar, use client.principal().calendar(…) instead, or client.principal().calendars()

check_cdav_support()

Does a probe towards the server and returns True if it says it supports RFC4791 / CalDAV

Return type:

bool

check_dav_support()

Does a probe towards the server and returns True if it says it supports RFC4918 / DAV

Return type:

Optional[str]

check_scheduling_support()

Does a probe towards the server and returns True if it says it supports RFC6833 / CalDAV Scheduling

Return type:

bool

close()

Closes the DAVClient’s session object

Return type:

None

delete(url)

Send a delete request.

Return type:

DAVResponse

extract_auth_types(header)

This is probably meant for internal usage. It takes the headers it got from the server and figures out what authentication types the server supports

mkcalendar(url, body='', dummy=None)

Send a mkcalendar request.

Return type:

DAVResponse

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.

MKCOL is basically not used with caldav, one should use MKCALENDAR instead. However, some calendar servers MAY allow “subcollections” to be made in a calendar, by using the MKCOL query. As for 2020-05, this method is not exercised by test code or referenced anywhere else in the caldav library, it’s included just for the sake of completeness. And, perhaps this DAVClient class can be used for vCards and other WebDAV purposes.

Return type:

DAVResponse

Parameters:

• url – url for the root of the mkcol

• body – XML request

• dummy – compatibility parameter

Returns:

DAVResponse

options(url)

Send an options request.

Return type:

DAVResponse

post(url, body, headers=None)

Send a POST request.

Return type:

DAVResponse

principal(*largs, **kwargs)

Convenience method, it gives a bit more object-oriented feel to write client.principal() than Principal(client).

This method returns a caldav.Principal object, with higher-level methods for dealing with the principals calendars.

principals(name=None)

Instead of returning the current logged-in principal, it attempts to query for all principals. This may or may not work dependent on the permissions and implementation of the calendar server.

propfind(url=None, props='', depth=0)

Send a propfind request.

Return type:

DAVResponse

Parameters:

• url (URL) – url for the root of the propfind.

• props (xml) – properties we want

• depth (int) – maximum recursion depth

Return type:

DAVResponse

proppatch(url, body, dummy=None)

Send a proppatch request.

Return type:

DAVResponse

Parameters:

• url – url for the root of the propfind.

• body – XML propertyupdate request

• dummy – compatibility parameter

Returns:

DAVResponse

put(url, body, headers=None)

Send a put request.

Return type:

DAVResponse

report(url, query='', depth=0)

Send a report request.

Return type:

DAVResponse

Parameters:

• url – url for the root of the propfind.

• query – XML request

• depth – maximum recursion depth

Returns

DAVResponse

request(url, method='GET', body='', headers=None)

Actually sends the request, and does the authentication

Return type:

DAVResponse

class caldav.davclient.DAVResponse(response, davclient=None)

This class is a response from a DAV request. It is instantiated from the DAVClient class. End users of the library should not need to know anything about this class. Since we often get XML responses, it tries to parse it into self.tree

expand_simple_props(props=None, multi_value_props=None, xpath=None)

The find_objects_and_props() will stop at the xml element below the prop tag. This method will expand those props into text.

Executes find_objects_and_props if not run already, then modifies and returns self.objects.

Return type:

Dict[str, Dict[str, str]]

find_objects_and_props()

Check the response from the server, check that it is on an expected format, find hrefs and props from it and check statuses delivered.

The parsed data will be put into self.objects, a dict {href: {proptag: prop_element}}. Further parsing of the prop_element has to be done by the caller.

self.sync_token will be populated if found, self.objects will be populated.

Return type:

Dict[str, Dict[str, _Element]]

validate_status(status)

status is a string like “HTTP/1.1 404 Not Found”. 200, 207 and 404 are considered good statuses. The SOGo caldav server even returns “201 created” when doing a sync-report, to indicate that a resource was created after the last sync-token. This makes sense to me, but I’ve only seen it from SOGo, and it’s not in accordance with the examples in rfc6578.

Return type:

None

caldav.davclient.auto_calendar(*largs, **kwargs)

Alternative to auto_calendars - in most use cases, one calendar suffices

Return type:

Iterable[Calendar]

caldav.davclient.auto_calendars(config_file=None, config_section='default', testconfig=False, environment=True, config_data=None, config_name=None)

This will replace plann.lib.findcalendars()

Return type:

Iterable[Calendar]

caldav.davclient.auto_conn(*largs, config_data=None, **kwargs)

A quite stubbed verison of get_davclient was included in the v1.5-release as auto_conn, but renamed a few days later. Probably nobody except my caldav tester project uses auto_conn, but as a thumb of rule anything released should stay “deprecated” for at least one major release before being removed.

TODO: remove in version 3.0

caldav.davclient.get_davclient(check_config_file=True, config_file=None, config_section=None, testconfig=False, environment=True, name=None, **config_data)

This function will yield a DAVClient object. It will not try to connect (see auto_calendars for that). It will read configuration from various sources, dependent on the parameters given, in this order:

• Data from the parameters given

• Environment variables prepended with CALDAV_, like CALDAV_URL, CALDAV_USERNAME, CALDAV_PASSWORD.

• Environment variables PYTHON_CALDAV_USE_TEST_SERVER and CALDAV_CONFIG_FILE will be honored if environment is set

• Data from ./tests/conf.py or ./conf.py (this includes the possibility to spin up a test server)

• Configuration file. Documented in the plann project as for now. (TODO - move it)

Return type:

DAVClient