Package: nextcloud-tasks-api
Nextcloud Tasks APIThis library has been made available byHackitu.de.It is published under the terms of theGNU AGPL 3.0licence.Nextcloud tasks API and CLIThe defaultNextcloud Tasks Appallows to manage task lists in calendars, which can be synced across devices via iCal todos. The corresponding WebGUI can be inconvenient for some use-cases or might not be exposed/reachable, so a console client that can work with tunnels or in an SSH sessions could come in handy. A library-like interface to the Nextcloud Tasks WebDAV API allows to use the core functionality also in the context of other projects or for automation.As there seems to be no library specialized on Nextcloud tasks available yet, this project comes in three parts:API class for WebDAV XML operations on task lists and tasks from a Nextcloud calendarInteractive CLI client for browsing, managing, and editing tasks on a Nextcloud instance from the terminal (optional)Simple custom iCal todo parser to work with tasks (optional)Python Tasks API QuickstartAn API instance can be obtained by the convenience wrapperget_nextcloud_tasks_api. The following example snippet creates a new task and prints all tasks for all task lists found:api = get_nextcloud_tasks_api("https://my.nextcloud.com/", "username", "password")
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 = int(time.time())
    api.create(task_list, new_task.to_string())  # add (as completed) to task list

    for task in api.get_list(task_list):  # get all tasks in the list
        print(Task(task.content).summary)EndpointsThe following API operations are supported:get_lists() -> Iterator[TaskList]Find all available task lists.get_list(task_list: TaskList, completed: Optional[bool]) -> Iterator[TaskFile]Get all tasks of a task list, optionally filter remotely by completion state for performance reasons. Note that by default responses are streamed and parsed incrementally, so late exceptions can happen while iterating.update_list(task_list: TaskList)Update a list, i.e., with a new display name.delete_list(task_list: TaskList)Delete the given list.create_list(filename: str, name: Optional[str]) -> TaskListCreate a new list with the given (unverified) filename and display name.update(task: TaskFile) -> TaskFileUpdate a task with its updated content.delete(task: TaskFile)Delete a task.create(task_list: TaskList, task: str) -> TaskFileCreate a new task in the task list with the given iCal content.iCal Task ParserThe API itself transparently operates on unparsed content – i.e., vCalendar/vEvent/iCal strings via XML/WebDAV – so any parsing approach can be used.However, a simpleiCal parser/factory as well as aTaskclass is included that can optionally be used for working with basicVTODOproperties. More elaborate libraries withtodosupport already exist on PyPI, for exampleicaloriCal-library.Nextcloud Tasks Console ClientBased on the Nextcloud tasks API, an interactive CLI client for browsing, managing, and editing tasks is also included. This command-line client is optional, as its additional dependency (questionary) is only included when thecliextrais specified at installation time.On all found task lists, creating, (un-)completing, editing, and deleting tasks is supported, also for arbitrarily nested sub-tasks. In particular, guided by an interactive menu, you can:Choose a task list from all lists foundFilter tasks by completion statePer default, all tasks are fetched to build up a tree structure that hides fully completed subtrees. For performance reasons or other use-cases, this can be changed to fetch and show all or only (un-)completed tasks.See all tasks in a tree structure with a completed-indicator and their summaryToggle completed statesCreate a new task, possibly as child of an existing oneSee or edit a task’s summary (“title”) and descriptionMultiline descriptions are supported andmarkdown bullet listsare consistently wrapped according to their indentationDelete a taskCreate, rename, or delete an entire task listUsage and ConfigurationSimply runnextcloud-tasks-apiwith a configuration file:usage:nextcloud-tasks-api\[-h\]\[-cCONFIG\]InteractiveCLIclientformanagingtasksonaNextcloudinstance.

optionalarguments:-h,--helpshowthishelpmessageandexit-cCONFIGconfigurationfile,in.inior.jsonformat(default:./tasks\_config.ini)The config file consists of simple key/value pairs and will be read fromtasks_config.iniin the current directory if not specified otherwise. InINI format, it should contain a single (arbitrarily named) section with the following keys. Alternatively, a.jsonfile with a corresponding dictionary can be given.base_urlURL of the instance, gets the API calls appended, for example:https://my.nextcloud.com/usernameUsername to login with.passwordPassword to login with. Using anApp Passwordinstead of the main account password should be considered. Adding an App Password is also needed when the account has 2FA enabled.password_typeEitherplain(default) oropenssl-aes, the latter for an encrypted password which requires theopensslbinary. A compatibleencryptionstep is for example:echo -n "nextcloud-password" | openssl enc -e -aes-256-cbc -salt -pbkdf2 -base64This will prompt for a password that then needs to be given to the CLI at startup.verify_sslVerify the SSL certificate of an HTTPS API URL, enabled per default.