`DAVClient` – A simple DAV client#

Sync CalDAV client using niquests or requests library.

This module provides the traditional synchronous API with protocol layer for XML building and response parsing.

For async code, use: from caldav import aio

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, features=None, enable_rfc6764=True, require_tls=True, rate_limit_handle=None, rate_limit_default_sleep=None, rate_limit_max_sleep=None)[source][source]#

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)[source][source]#

Build authentication object for the requests/niquests library.

Uses shared auth type selection logic from BaseDAVClient, then creates the appropriate auth object for this HTTP library.

Return type:: None
Parameters:: auth_types – List of acceptable auth types from server.

calendar(**kwargs)[source][source]#

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().get_calendars()

check_cdav_support()[source][source]#

Legacy method. Use supports_caldav() for new code.

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

Return type:: bool

check_dav_support()[source][source]#

Legacy method. Use supports_dav() for new code.

Does a probe towards the server and returns the DAV header if it says it supports RFC4918 / DAV, or None otherwise.

Return type:: str | None

check_scheduling_support()[source][source]#

Legacy method. Use supports_scheduling() for new code.

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

Return type:: bool

close()[source][source]#

Closes the DAVClient’s session object.

Return type:: None

delete(url)[source][source]#

Send a delete request.

Return type:: DAVResponse

get_calendars(principal=None)[source][source]#

Get all calendars for the given principal.

This method fetches calendars from the principal’s calendar-home-set and returns a list of Calendar objects.

Return type:: list[Calendar]
Parameters:: principal – Principal object (if None, fetches principal first)
Returns:: List of Calendar objects.

Example

principal = client.get_principal() calendars = client.get_calendars(principal) for cal in calendars:

print(f”Calendar: {cal.get_display_name()}”)

get_principal()[source][source]#

Get the principal (user) for this CalDAV connection.

This is the recommended method for new code. It provides API consistency between sync and async clients.

Return type:: Principal
Returns:: Principal object for the authenticated user.

Example:

principal = client.get_principal()
calendars = principal.get_calendars()

mkcalendar(url, body='', dummy=None)[source][source]#

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)[source][source]#

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)[source][source]#

Send an options request.

Return type:: DAVResponse

post(url, body, headers=None)[source][source]#

Send a POST request.

Return type:: DAVResponse

principal(*largs, **kwargs)[source][source]#

Legacy method. Use get_principal() for new code.

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)[source][source]#

Deprecated. Use search_principals() instead.

This method searches for principals on the server.

propfind(url=None, props=None, depth=0)[source][source]#

Send a propfind request.

Return type:

DAVResponse

Parameters:

url (URL) – url for the root of the propfind.
props (str or List[str]) – XML body string (old interface) or list of property names (new interface).
depth (int) – maximum recursion depth

Return type:

DAVResponse

proppatch(url, body, dummy=None)[source][source]#

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)[source][source]#

Send a put request.

Return type:: DAVResponse

report(url, query='', depth=0)[source][source]#

Send a report request.

Return type:

DAVResponse

Parameters:

url – url for the root of the propfind.
query – XML request
depth – maximum recursion depth. None means don’t send Depth header (required for calendar-multiget per RFC 4791 section 7.9).

Returns: DAVResponse

request(url, method='GET', body='', headers=None, rate_limit_time_slept=0)[source][source]#

Send a generic HTTP request.

Uses the sync session directly for all operations.

Return type:

DAVResponse

Parameters:

url – The URL to request
method – HTTP method (GET, PUT, DELETE, etc.)
body – Request body
headers – Optional headers dict

Returns:

DAVResponse

search_calendar(calendar, event=False, todo=False, journal=False, start=None, end=None, include_completed=None, expand=False, **kwargs)[source][source]#

Search a calendar for events, todos, or journals.

This method provides a clean interface to calendar search.

Return type:

list[CalendarObjectResource]

Parameters:

calendar – Calendar to search
event – Search for events (VEVENT)
todo – Search for todos (VTODO)
journal – Search for journals (VJOURNAL)
start – Start of date range
end – End of date range
include_completed – Include completed todos (default: False for todos)
expand – Expand recurring events
**kwargs – Additional search parameters

Returns:

List of Event/Todo/Journal objects.

Example

# Get all events in January 2024 events = client.search_calendar(

calendar, event=True, start=datetime(2024, 1, 1), end=datetime(2024, 1, 31),

)

search_principals(name=None)[source][source]#

Search for principals on the server.

Instead of returning the current logged-in principal, this method attempts to query for all principals (or principals matching a name). This may or may not work depending on the permissions and implementation of the calendar server.

Parameters:: name – Optional name filter to search for specific principals
Returns:: List of Principal objects found on the server
Raises:: ReportError – If the server doesn’t support principal search

supports_caldav()[source][source]#

Check if the server supports CalDAV (RFC4791).

This is the recommended method for new code. It provides API consistency between sync and async clients.

Return type:: bool
Returns:: True if the server supports CalDAV, False otherwise.

Example:

if client.supports_caldav():
    calendars = client.get_calendars()

supports_dav()[source][source]#

Check if the server supports WebDAV (RFC4918).

This is the recommended method for new code. It provides API consistency between sync and async clients.

Return type:: str | None
Returns:: The DAV header value if supported, None otherwise.

Example:

if client.supports_dav():
    print("Server supports WebDAV")

supports_scheduling()[source][source]#

Check if the server supports CalDAV Scheduling (RFC6638).

This is the recommended method for new code. It provides API consistency between sync and async clients.

Return type:: bool
Returns:: True if the server supports CalDAV Scheduling, False otherwise.

Example:

if client.supports_scheduling():
    # Server supports free-busy lookups and scheduling
    pass

class caldav.davclient.DAVResponse(response, davclient=None)[source][source]#: 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

caldav.davclient.get_calendar(**kwargs)[source][source]#

Get a single calendar from a CalDAV server.

This is a convenience function for the common case where only one calendar is needed. Returns a CalendarResult that can be used as a context manager.

Return type:: CalendarResult

:param Same as get_calendars().:

Returns:: CalendarResult wrapping a Calendar object (or None if not found). Use as context manager to auto-close the connection.

Example:

from caldav import get_calendar

with get_calendar(calendar_name="Work", url="...", ...) as calendar:
    if calendar:
        events = calendar.date_search(start=..., end=...)

caldav.davclient.get_calendars(**kwargs)[source][source]#

Get calendars from CalDAV servers with configuration from multiple sources.

This is a convenience wrapper around caldav.base_client.get_calendars() that uses DAVClient.

Return type:

list[Calendar]

Parameters:

calendar_url – URL(s) or ID(s) of specific calendars to fetch.
calendar_name – Name(s) of specific calendars to fetch by display name.
check_config_file – Whether to look for config files (default: True).
config_file – Explicit path to config file.
config_section – Section name in config file.
testconfig – Whether to use test server configuration.
environment – Whether to read from environment variables (default: True).
name – Name of test server to use (for testconfig).
raise_errors – If True, raise exceptions on errors; if False, log and skip.
**config_data – Connection parameters (url, username, password, etc.)

Returns:

List of Calendar objects matching the criteria.

Example:

from caldav import get_calendars

# Get all calendars
calendars = get_calendars(url="https://...", username="...", password="...")

# Get specific calendar by name
calendars = get_calendars(calendar_name="Work", url="...", ...)

caldav.davclient.get_davclient(**kwargs)[source][source]#

Get a DAVClient instance with configuration from multiple sources.

See caldav.base_client.get_davclient() for full documentation.

Return type:: DAVClient | None
Returns:: DAVClient instance, or None if no configuration is found.

DAVClient – A simple DAV client#

This Page

`DAVClient` – A simple DAV client#