NextCloud tasks API

The default NextCloud Tasks App allows to manage task lists in calendars, which can be synced across devices via iCal “todos”. As the corresponding WebGUI can be inconvenient for some use-cases or might not be exposed, this NextCloud WebDAV API library allows to use the core functionality also in other contexts or for automation.

• API class for WebDAV XML operations on task lists and tasks from a NextCloud calendar
• Fully async requests and incremental response parsing, for minimal delay even on bigger task lists
• Support for ETag headers to detect collisions and inconsistencies
• Fully typed and extensible
• Simple custom iCal todo parser to work with tasks (optional)

This is the successor and async reimplementation of the initial API project, which comes with a bundled CLI and should be considered legacy by now.

Based on this library, a convenient and responsive terminal client for todo lists and tasks is provided by the console TUI project.

Quick Reference

An API instance can be obtained by the corresponding factory as convenience wrapper. The following example snippet creates a new task and prints all tasks for all task lists found:

async with await NextcloudTasksApiFactory("https://my.nextcloud.com/").create("username", "password") as api:
    async for task_list in api.get_lists():  # all task lists belonging to the authenticated user
        print(task_list.name)

        new_task = Task()  # empty iCal VTODO stub
        new_task.summary = "Test"
        new_task.completed = time.time()
        await api.create_task(task_list, new_task.to_string())  # add (as completed) to task list

        async for task in api.get_list(task_list):  # get all tasks in the list
            print(Task(task.content).summary)

API Configuration

base_url: str

Root URL of the NextCloud instance. Requests will be made to the remote.php/dav/ API endpoint below.

verify_ssl: bool = True

Disable to ignore certificate errors.

limit: int = 0

Limiting semaphore on pending requests. When enabled, can avoid database is locked errors on some installations under high load.

timeout: Optional[float] = None

Overall timeout for each request.

username: str

Username for HTTP Basic authentication.

password: str

Password to login with. Using an App Password instead of the main account’s password should be considered and is needed when 2FA is enabled.

API Endpoints

async def list_user_principal() -> AsyncIterator[str]:
    """Query current user principal endpoints. Useful to validate endpoint and authentication settings."""
async def get_lists() -> AsyncIterator[TaskList]:
    """Find all available task lists."""
async def get_list(task_list: TaskList, completed: Optional[bool] = None) -> AsyncIterator[TaskFile]:
    """Get all tasks of a task list, optionally filter remotely by completion state."""
async def create_list(name: str, color: str = "#0082c9", filename: Optional[str] = None) -> TaskList:
    """Create a new task list with the given displayname and (unverified) filename."""
async def update_list(task_list: TaskList) -> None:
    """Update a task list with its updated handle."""
async def delete_list(task_list: TaskList) -> None:
    """Delete the given task list."""
async def create_task(task_list: TaskList, task: str, filename: Optional[UUID] = None) -> TaskFile:
    """Create a new task in the task list with the given iCal content."""
async def update_task(task: TaskFile) -> TaskFile:
    """Update a task with new content."""
async def delete_task(task: TaskFile) -> None:
    """Delete a task. This does not recursively delete subtasks."""

iCal Task Parser

The API itself is only directly concerned with NextCloud-specific XML/WebDAV operations and transparently operates on unparsed content. So any parsing approach can be used on the returned vCalendar/vEvent/iCal strings.

However, a simple iCal parser and factory as well as a Task class is readily included that can optionally be used for working with typical VTODO properties. No additional requirements should thus be needed, but more elaborate libraries with todo support already exist on PyPI, for example ical or iCal-library.

While all iCal VTODO entries can be directly modified by the key/parameter/value datastructure, there are convenience task properties and setters for:

• Own and related_to UIDs for the tree of parent/subtask relations
• Task summary (title) and description (text, markdown)
• Timestamps for created, last_modified, and completed

Note that individual parameters are not parsed and taken into account by this implementation. This for example also applies to custom timezones, such that the timestamps are assumed to be in UTC.

Installation

The most easy way to (un-)install the nextcloud-tasks-api package is via pip. If not already present, a corresponding system package such as python3-pip should exist.

pip install .[lxml]
pip uninstall nextcloud-tasks-api

These commands are also the ones used by make install and make uninstall and include the optional lxml requirement as extra for improved parsing performance. The only hard requirement implicitly installed is aiohttp.

For trying out or local development, a virtual environment can be used. Wrapped by the Makefile, a make check will invoke type checker and linter.