caldav_tasks_api package

Subpackages

Submodules

caldav_tasks_api.caldav_tasks_api module

class caldav_tasks_api.caldav_tasks_api.TasksAPI(url: str | None = None, username: str | None = None, password: str | None = None, nextcloud_mode: bool = True, debug: bool = False, target_lists: List[str] | None = None, read_only: bool = False, ssl_verify_cert: bool = True)[source]

Bases: object

__init__(url: str | None = None, username: str | None = None, password: str | None = None, nextcloud_mode: bool = True, debug: bool = False, target_lists: List[str] | None = None, read_only: bool = False, ssl_verify_cert: bool = True)[source]

Initializes the TasksAPI and connects to the CalDAV server.

Parameters:

  • url – The base URL of the CalDAV server. If None, reads from CALDAV_TASKS_API_URL environment variable.

  • username – The username for authentication. If None, reads from CALDAV_TASKS_API_USERNAME environment variable.

  • password – The password for authentication. If None, reads from CALDAV_TASKS_API_PASSWORD environment variable.

  • nextcloud_mode – If True, adjusts URL for Nextcloud’s specific path.

  • debug – If True, enables PDB post-mortem debugging on specific errors.

  • target_lists – Optional list of calendar names or UIDs to filter by.

  • read_only – If True, API operates in read-only mode, preventing modifications.

  • ssl_verify_cert – If True, verifies SSL certificates. Set to False for self-signed certs.

Raises:

ValueError – If required credentials cannot be determined from arguments or environment variables.

add_task(task_data: TaskData, list_uid: str | None = None) → TaskData[source]

Adds a new task to the specified task list on the server.

The list UID can be determined in the following order of precedence: 1. The list_uid argument provided to this method. 2. The task_data.list_uid attribute if list_uid argument is not provided. 3. The CALDAV_TASKS_API_DEFAULT_LIST_UID environment variable if neither of the above is set.

If no priority is set on the task (priority <= 0), a default priority will be applied from the CALDAV_TASKS_API_DEFAULT_PRIORITY environment variable. If this environment variable is not set, the default priority value of 3 will be used.

Parameters:

  • task_data – The TaskData object representing the task to add.

  • list_uid – Optional. The UID of the task list to add the task to. If not provided, task_data.list_uid or the environment variable will be used.

Returns:

The TaskData object representing the added task, updated with server information.

Raises:

  • PermissionError – If the API is in read-only mode.

  • ValueError – If the task list UID cannot be determined or the specified list is not found.

delete_task_by_id(task_uid: str, list_uid: str | None = None) → bool[source]

Deletes a task from the specified task list on the server.

Parameters:

  • task_uid – The UID of the task to delete.

  • list_uid – The UID of the task list. If None, uses CALDAV_TASKS_API_DEFAULT_LIST_UID environment variable.

Returns:

True if deletion was successful.

Raises:

  • PermissionError – If the API is in read-only mode.

  • ValueError – If list_uid cannot be determined or the specified list is not found.

get_task_by_global_uid(task_uid: str) → TaskData | None[source]

Retrieves a loaded task by its UID across all task lists.

get_task_list_by_uid(list_uid: str) → TaskListData | None[source]

Retrieves a loaded task list by its UID.

get_tasks_by_list_uid(list_uid: str) → list[TaskData][source]

Retrieves all loaded tasks belonging to a specific list UID.

load_remote_data() → None[source]

Loads all task lists and tasks from the remote CalDAV server into memory. This will overwrite any existing local data in self.task_lists

update_task(task_data: TaskData) → TaskData[source]

Updates an existing task on the server. The provided task_data object should have its fields already modified. Its changed_at timestamp will be updated before sending.

VERSION: str = '1.3.0'

Module contents

Caldav Tasks API Package.

This package provides the TasksAPI client for interacting with CalDAV task servers, and the data structures TaskListData and TaskData for representing task lists and tasks.

class caldav_tasks_api.TaskData(attachments: 'list[str]' = <factory>, completed: 'bool' = False, changed_at: 'str' = '', created_at: 'str' = '', deleted: 'bool' = False, due_date: 'str' = '', list_uid: 'str' = '', notes: 'str' = '', notified: 'bool' = False, parent: 'str' = '', percent_complete: 'int' = 0, priority: 'int' = 0, rrule: 'str' = '', start_date: 'str' = '', synced: 'bool' = False, tags: 'list[str]' = <factory>, text: 'str' = '', trash: 'bool' = False, uid: 'str' = '', x_properties: 'XProperties' = <factory>, _api_reference: "Optional['TasksAPI']" = None)[source]

Bases: object

static from_ical(ical: str | bytes, list_uid: str) → TaskData[source]

Build TaskData from a VTODO iCal string.

delete() → bool[source]

Deletes this task from the server using the API reference.

Returns:

True if deletion was successful, False otherwise.

Raises:

  • RuntimeError – If no API reference is available.

  • PermissionError – If the API is in read-only mode.

  • ValueError – If the task list or task is not found.

to_dict() → Dict[source]

Converts the TaskData instance to a dictionary.

to_ical() → str[source]

Build VTODO iCal component string from TaskData properties.

attachments: list[str]
changed_at: str = ''
property child_tasks: list[TaskData]

Returns a list of child TaskData objects, if this task has children and an API reference to search for them. Searches for tasks whose ‘parent’ field matches this task’s UID.

completed: bool = False
created_at: str = ''
deleted: bool = False
due_date: str = ''
list_uid: str = ''
notes: str = ''
notified: bool = False
parent: str = ''
property parent_task: TaskData | None

Returns the parent TaskData object, if this task has a parent UID and an API reference to search for it.

percent_complete: int = 0
priority: int = 0
rrule: str = ''
start_date: str = ''
synced: bool = False
tags: list[str]
text: str = ''
trash: bool = False
uid: str = ''
x_properties: XProperties
class caldav_tasks_api.TaskListData(color: 'str' = '', deleted: 'bool' = False, name: 'str' = '', synced: 'bool' = False, uid: 'str' = '', tasks: 'list[TaskData]' = <factory>)[source]

Bases: object

to_dict() → Dict[source]

Converts the TaskListData instance to a dictionary.

color: str = ''
deleted: bool = False
name: str = ''
synced: bool = False
tasks: list[TaskData]
uid: str = ''
class caldav_tasks_api.TasksAPI(url: str | None = None, username: str | None = None, password: str | None = None, nextcloud_mode: bool = True, debug: bool = False, target_lists: List[str] | None = None, read_only: bool = False, ssl_verify_cert: bool = True)[source]

Bases: object

__init__(url: str | None = None, username: str | None = None, password: str | None = None, nextcloud_mode: bool = True, debug: bool = False, target_lists: List[str] | None = None, read_only: bool = False, ssl_verify_cert: bool = True)[source]

Initializes the TasksAPI and connects to the CalDAV server.

Parameters:

  • url – The base URL of the CalDAV server. If None, reads from CALDAV_TASKS_API_URL environment variable.

  • username – The username for authentication. If None, reads from CALDAV_TASKS_API_USERNAME environment variable.

  • password – The password for authentication. If None, reads from CALDAV_TASKS_API_PASSWORD environment variable.

  • nextcloud_mode – If True, adjusts URL for Nextcloud’s specific path.

  • debug – If True, enables PDB post-mortem debugging on specific errors.

  • target_lists – Optional list of calendar names or UIDs to filter by.

  • read_only – If True, API operates in read-only mode, preventing modifications.

  • ssl_verify_cert – If True, verifies SSL certificates. Set to False for self-signed certs.

Raises:

ValueError – If required credentials cannot be determined from arguments or environment variables.

add_task(task_data: TaskData, list_uid: str | None = None) → TaskData[source]

Adds a new task to the specified task list on the server.

The list UID can be determined in the following order of precedence: 1. The list_uid argument provided to this method. 2. The task_data.list_uid attribute if list_uid argument is not provided. 3. The CALDAV_TASKS_API_DEFAULT_LIST_UID environment variable if neither of the above is set.

If no priority is set on the task (priority <= 0), a default priority will be applied from the CALDAV_TASKS_API_DEFAULT_PRIORITY environment variable. If this environment variable is not set, the default priority value of 3 will be used.

Parameters:

  • task_data – The TaskData object representing the task to add.

  • list_uid – Optional. The UID of the task list to add the task to. If not provided, task_data.list_uid or the environment variable will be used.

Returns:

The TaskData object representing the added task, updated with server information.

Raises:

  • PermissionError – If the API is in read-only mode.

  • ValueError – If the task list UID cannot be determined or the specified list is not found.

delete_task_by_id(task_uid: str, list_uid: str | None = None) → bool[source]

Deletes a task from the specified task list on the server.

Parameters:

  • task_uid – The UID of the task to delete.

  • list_uid – The UID of the task list. If None, uses CALDAV_TASKS_API_DEFAULT_LIST_UID environment variable.

Returns:

True if deletion was successful.

Raises:

  • PermissionError – If the API is in read-only mode.

  • ValueError – If list_uid cannot be determined or the specified list is not found.

get_task_by_global_uid(task_uid: str) → TaskData | None[source]

Retrieves a loaded task by its UID across all task lists.

get_task_list_by_uid(list_uid: str) → TaskListData | None[source]

Retrieves a loaded task list by its UID.

get_tasks_by_list_uid(list_uid: str) → list[TaskData][source]

Retrieves all loaded tasks belonging to a specific list UID.

load_remote_data() → None[source]

Loads all task lists and tasks from the remote CalDAV server into memory. This will overwrite any existing local data in self.task_lists

update_task(task_data: TaskData) → TaskData[source]

Updates an existing task on the server. The provided task_data object should have its fields already modified. Its changed_at timestamp will be updated before sending.

VERSION: str = '1.3.0'
client: DAVClient | None
principal: Principal | None
raw_calendars: list[Calendar]
task_lists: list[TaskListData]