[](https://badge.fury.io/py/caldav-tasks-api)
*(Full documentation available at [caldavtasksapi.readthedocs.io](https://caldavtasksapi.readthedocs.io/en/latest/#))*
# CalDAV-Tasks-API
A Python library and command-line interface (CLI) for interacting with CalDAV task lists (VTODOs). This project provides tools to connect to a CalDAV server, fetch task lists and tasks, create new tasks, and delete existing ones.
## Table of Contents
- [Motivation and Purpose](#motivation-and-purpose)
- [Compatibility](#compatibility)
- [Features](#features)
- [Installation](#installation)
- [Contributing](#contributing)
- [Acknowledgements](#acknowledgements)
## Motivation and Purpose
This library was developed as a foundational component for integrating CalDAV task management with more advanced systems. The primary goal is to serve as a backbone for:
1. Synchronizing tasks from applications like the excellent [Tasks.org Android app](https://f-droid.org/packages/org.tasks/).
2. Enabling features such as smart task prioritization using ELO ranking, envisioned to work with a [Litoy-like setup](https://github.com/thiswillbeyourgithub/mini_LiTOY).
3. Making useful python objects with handy methods to manipulate caldav's tasks.
4. Making a CLI interface to manipulate tasks (secondary goal).
By providing a robust Python interface to CalDAV tasks, this project aims to bridge the gap between standard task management and custom, intelligent task processing workflows. The library is intentionally designed to be minimal, with few external dependencies, to ensure it is lightweight and easy to integrate.
## Compatibility
The API has been primarily tested with **Nextcloud Tasks**. However, it is designed to be compatible with any CalDAV server that supports VTODO components.
Testers and feedback for other CalDAV server implementations (e.g., Baïkal, Radicale, Synology Calendar) are highly welcome!
## Features
* Connect to CalDAV servers with optional Nextcloud-specific URL adjustments.
* Load task lists (calendars supporting VTODOs).
* Load tasks from specified lists, parsing standard iCalendar properties.
* Preserve and provide access to custom `X-` properties.
* Create, update, and delete tasks (VTODOs) on the server.
* Access parent and child task relationships (`TaskData.parent_task` and `TaskData.child_tasks`).
* Read-only mode for applications that need to prevent modifications.
* CLI with multiple commands: show summaries, list tasks, add tasks, and list available task lists.
* JSON output support for integration with other tools.
* Environment variable support for credentials and default settings.
## Installation
The CalDAV Tasks API can be installed directly from PyPI:
```bash
uv pip install caldav-tasks-api
```
Alternatively, you can install from source:
1. Clone the repository:
```bash
git clone <repository_url>
cd caldav-tasks-api
```
2. Install dependencies (ensure you have `python>=3.8`):
```bash
# Install the package and all dependencies:
uv pip install .
# For development with editable install:
uv pip install -e .
# For development with additional dev dependencies:
uv pip install -e ".[dev]"
```
## Configuration
The library supports configuration via environment variables:
- `CALDAV_TASKS_API_URL`: CalDAV server URL
- `CALDAV_TASKS_API_USERNAME`: CalDAV username
- `CALDAV_TASKS_API_PASSWORD`: CalDAV password
- `CALDAV_TASKS_API_DEFAULT_LIST_UID`: Default task list UID for operations
- `CALDAV_TASKS_API_DEFAULT_PRIORITY`: Default priority to use when creating tasks
- `CALDAV_TASKS_API_LOG_LEVEL`: Default log level, by default `WARNING`
## Usage
### Command Line Interface
The package provides several CLI commands:
```bash
# Show summary of all task lists and tasks
python -m caldav_tasks_api show-summary
# Show summary with JSON output
python -m caldav_tasks_api show-summary --json
# List available task lists
python -m caldav_tasks_api list-lists
# List latest tasks from a specific list
python -m caldav_tasks_api list-latest-tasks --list-uid <list-uid>
# Dump all the tasks of a list as VTODO format
python -m caldav_tasks_api dump-all-tasks --list-uid <list-uid>
# Add a new task
python -m caldav_tasks_api add-task --list-uid <list-uid> --summary "My new task"
# Add a task with additional properties
python -m caldav_tasks_api add-task \
--list-uid <list-uid> \
--summary "Important task" \
--notes "Task description" \
--priority 5 \
--due-date 20240315 \
--tag urgent --tag work
```
All commands support `--help` for detailed options.
### Python API
```python
from caldav_tasks_api import TasksAPI
from caldav_tasks_api.utils.data import TaskData
# Initialize API (credentials from environment or parameters)
api = TasksAPI(
url="https://your-server.com/remote.php/dav/",
username="your-username",
password="your-password"
)
# Load all task lists and tasks
api.load_remote_data()
# Access task lists
for task_list in api.task_lists:
print(f"List: {task_list.name} ({len(task_list.tasks)} tasks)")
for task in task_list.tasks:
print(f" - {task.text}")
# Create a new task
new_task = TaskData(
text="My new task",
list_uid="your-list-uid",
notes="Task description",
priority=5
)
created_task = api.add_task(new_task)
# Update a task
task = api.get_task_by_global_uid("task-uid")
if task:
task.text = "Updated task title"
api.update_task(task)
```
## Contributing
Contributions are welcome! If you'd like to contribute, please feel free to:
1. Open an issue to discuss a bug, feature request, or an idea.
2. Fork the repository and submit a pull request with your changes.
Please ensure your code follows the existing style and includes tests where appropriate.
## Acknowledgements
This project was developed with the assistance of [aider.chat](https://aider.chat), an AI pair programmer.
Raw data
{
"_id": null,
"home_page": "https://github.com/thiswillbeyourgithub/CaldavTasksAPI/",
"name": "caldav-tasks-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "caldav, tasks, vtodo, todo, cli, api, nextcloud, calendar, task management",
"author": "thiswillbeyourgithub",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/3b/f5/00d6f8b1045da7a406c789e3898b53e902f7baa73751a4777611e828ae05/caldav_tasks_api-1.3.0.tar.gz",
"platform": null,
"description": "[](https://badge.fury.io/py/caldav-tasks-api)\n\n*(Full documentation available at [caldavtasksapi.readthedocs.io](https://caldavtasksapi.readthedocs.io/en/latest/#))*\n\n# CalDAV-Tasks-API\n\nA Python library and command-line interface (CLI) for interacting with CalDAV task lists (VTODOs). This project provides tools to connect to a CalDAV server, fetch task lists and tasks, create new tasks, and delete existing ones.\n\n## Table of Contents\n\n- [Motivation and Purpose](#motivation-and-purpose)\n- [Compatibility](#compatibility)\n- [Features](#features)\n- [Installation](#installation)\n- [Contributing](#contributing)\n- [Acknowledgements](#acknowledgements)\n\n\n## Motivation and Purpose\n\nThis library was developed as a foundational component for integrating CalDAV task management with more advanced systems. The primary goal is to serve as a backbone for:\n\n1. Synchronizing tasks from applications like the excellent [Tasks.org Android app](https://f-droid.org/packages/org.tasks/).\n2. Enabling features such as smart task prioritization using ELO ranking, envisioned to work with a [Litoy-like setup](https://github.com/thiswillbeyourgithub/mini_LiTOY).\n3. Making useful python objects with handy methods to manipulate caldav's tasks.\n4. Making a CLI interface to manipulate tasks (secondary goal).\n\nBy providing a robust Python interface to CalDAV tasks, this project aims to bridge the gap between standard task management and custom, intelligent task processing workflows. The library is intentionally designed to be minimal, with few external dependencies, to ensure it is lightweight and easy to integrate.\n\n## Compatibility\n\nThe API has been primarily tested with **Nextcloud Tasks**. However, it is designed to be compatible with any CalDAV server that supports VTODO components.\n\nTesters and feedback for other CalDAV server implementations (e.g., Ba\u00efkal, Radicale, Synology Calendar) are highly welcome!\n\n## Features\n\n* Connect to CalDAV servers with optional Nextcloud-specific URL adjustments.\n* Load task lists (calendars supporting VTODOs).\n* Load tasks from specified lists, parsing standard iCalendar properties.\n* Preserve and provide access to custom `X-` properties.\n* Create, update, and delete tasks (VTODOs) on the server.\n* Access parent and child task relationships (`TaskData.parent_task` and `TaskData.child_tasks`).\n* Read-only mode for applications that need to prevent modifications.\n* CLI with multiple commands: show summaries, list tasks, add tasks, and list available task lists.\n* JSON output support for integration with other tools.\n* Environment variable support for credentials and default settings.\n\n## Installation\n\nThe CalDAV Tasks API can be installed directly from PyPI:\n\n```bash\nuv pip install caldav-tasks-api\n```\n\nAlternatively, you can install from source:\n\n1. Clone the repository:\n ```bash\n git clone <repository_url>\n cd caldav-tasks-api\n ```\n2. Install dependencies (ensure you have `python>=3.8`):\n ```bash\n # Install the package and all dependencies:\n uv pip install .\n \n # For development with editable install:\n uv pip install -e .\n \n # For development with additional dev dependencies:\n uv pip install -e \".[dev]\"\n ```\n\n## Configuration\n\nThe library supports configuration via environment variables:\n\n- `CALDAV_TASKS_API_URL`: CalDAV server URL\n- `CALDAV_TASKS_API_USERNAME`: CalDAV username\n- `CALDAV_TASKS_API_PASSWORD`: CalDAV password\n- `CALDAV_TASKS_API_DEFAULT_LIST_UID`: Default task list UID for operations\n- `CALDAV_TASKS_API_DEFAULT_PRIORITY`: Default priority to use when creating tasks\n- `CALDAV_TASKS_API_LOG_LEVEL`: Default log level, by default `WARNING`\n\n## Usage\n\n### Command Line Interface\n\nThe package provides several CLI commands:\n\n```bash\n# Show summary of all task lists and tasks\npython -m caldav_tasks_api show-summary\n\n# Show summary with JSON output\npython -m caldav_tasks_api show-summary --json\n\n# List available task lists\npython -m caldav_tasks_api list-lists\n\n# List latest tasks from a specific list\npython -m caldav_tasks_api list-latest-tasks --list-uid <list-uid>\n\n# Dump all the tasks of a list as VTODO format\npython -m caldav_tasks_api dump-all-tasks --list-uid <list-uid>\n\n# Add a new task\npython -m caldav_tasks_api add-task --list-uid <list-uid> --summary \"My new task\"\n\n# Add a task with additional properties\npython -m caldav_tasks_api add-task \\\n --list-uid <list-uid> \\\n --summary \"Important task\" \\\n --notes \"Task description\" \\\n --priority 5 \\\n --due-date 20240315 \\\n --tag urgent --tag work\n```\n\nAll commands support `--help` for detailed options.\n\n### Python API\n\n```python\nfrom caldav_tasks_api import TasksAPI\nfrom caldav_tasks_api.utils.data import TaskData\n\n# Initialize API (credentials from environment or parameters)\napi = TasksAPI(\n url=\"https://your-server.com/remote.php/dav/\",\n username=\"your-username\", \n password=\"your-password\"\n)\n\n# Load all task lists and tasks\napi.load_remote_data()\n\n# Access task lists\nfor task_list in api.task_lists:\n print(f\"List: {task_list.name} ({len(task_list.tasks)} tasks)\")\n \n for task in task_list.tasks:\n print(f\" - {task.text}\")\n\n# Create a new task\nnew_task = TaskData(\n text=\"My new task\",\n list_uid=\"your-list-uid\",\n notes=\"Task description\",\n priority=5\n)\ncreated_task = api.add_task(new_task)\n\n# Update a task\ntask = api.get_task_by_global_uid(\"task-uid\")\nif task:\n task.text = \"Updated task title\"\n api.update_task(task)\n```\n\n## Contributing\n\nContributions are welcome! If you'd like to contribute, please feel free to:\n\n1. Open an issue to discuss a bug, feature request, or an idea.\n2. Fork the repository and submit a pull request with your changes.\n\nPlease ensure your code follows the existing style and includes tests where appropriate.\n\n## Acknowledgements\n\nThis project was developed with the assistance of [aider.chat](https://aider.chat), an AI pair programmer.\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python client for CalDAV task servers, with a CLI.",
"version": "1.3.0",
"project_urls": {
"Homepage": "https://github.com/thiswillbeyourgithub/CaldavTasksAPI/"
},
"split_keywords": [
"caldav",
" tasks",
" vtodo",
" todo",
" cli",
" api",
" nextcloud",
" calendar",
" task management"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "04b86427b6d40a1a49228cc88b874b9ca902bd42f54bdf2bed8688f6bee959d4",
"md5": "2b06bdc6220aceafb58d00b8eb40a355",
"sha256": "4963a979176415c0c24bdc31fd8ed564e252b975856d22090ff69b9f33c6e81b"
},
"downloads": -1,
"filename": "caldav_tasks_api-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2b06bdc6220aceafb58d00b8eb40a355",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 40019,
"upload_time": "2025-07-16T16:20:18",
"upload_time_iso_8601": "2025-07-16T16:20:18.186678Z",
"url": "https://files.pythonhosted.org/packages/04/b8/6427b6d40a1a49228cc88b874b9ca902bd42f54bdf2bed8688f6bee959d4/caldav_tasks_api-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3bf500d6f8b1045da7a406c789e3898b53e902f7baa73751a4777611e828ae05",
"md5": "e6648d2e79bd44310e665f60d2844ec2",
"sha256": "e398f8765a380ef3d4c368c467dcb836eb32e5e61e00a3d1badc6e2f0b402343"
},
"downloads": -1,
"filename": "caldav_tasks_api-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "e6648d2e79bd44310e665f60d2844ec2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 47210,
"upload_time": "2025-07-16T16:20:20",
"upload_time_iso_8601": "2025-07-16T16:20:20.922695Z",
"url": "https://files.pythonhosted.org/packages/3b/f5/00d6f8b1045da7a406c789e3898b53e902f7baa73751a4777611e828ae05/caldav_tasks_api-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-16 16:20:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "thiswillbeyourgithub",
"github_project": "CaldavTasksAPI",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "caldav-tasks-api"
}
JSON
