dida365-api 0.2.1

Python client for Dida365/TickTick API

dida365-api

An unofficial Python client library for the Dida365/TickTick API, supporting both the Chinese (Dida365) and international (TickTick) versions of the service. Built with modern async Python and robust error handling.

Forked from Cyfine/TickTick-Dida365-API-Client — thanks to Carter Yifeng Cheng (@cyfine) for the original project.

This is a community package created to facilitate task management automation. It is not affiliated with or endorsed by Dida365 or TickTick.

Installation

This fork is not published on PyPI. Install directly from GitHub:

pip install git+https://github.com/Konano/dida365-api.git

Quick Start

import asyncio
from dida365 import Dida365Client, ServiceType, TaskCreate, TaskPriority

async def main():
    # Credentials can be passed via constructor, .env file, or environment variables
    client = Dida365Client(
        client_id="your_client_id",
        client_secret="your_client_secret",
        service_type=ServiceType.TICKTICK,  # or ServiceType.DIDA365
        redirect_uri="http://localhost:8080/callback",
        save_to_env=True,  # automatically save credentials & tokens to .env
        # access_token="your_access_token",  # If you already have an access_token, pass it directly to skip OAuth
    )

    # First-time authentication (opens browser, starts local callback server)
    if not client.auth.token:
        await client.authenticate()

    # Create a task
    task = await client.create_task(
        TaskCreate(
            project_id="your_project_id",
            title="My new task",
            content="Task description",
            priority=TaskPriority.HIGH,
        )
    )
    print(f"Created task: {task.title}")

if __name__ == "__main__":
    asyncio.run(main())

Configuration

Credentials can be provided in three ways (checked in this order):

1. Constructor parameters — directly pass client_id, client_secret, access_token, etc.
2. .env file — create a .env in your working directory
3. Environment variables

Example .env file:

DIDA365_CLIENT_ID=your_client_id
DIDA365_CLIENT_SECRET=your_client_secret
DIDA365_REDIRECT_URI=http://localhost:8080/callback
DIDA365_SERVICE_TYPE=ticktick  # or dida365
DIDA365_ACCESS_TOKEN=your_token  # optional: set to skip OAuth flow

OAuth2 Setup

1. Get your credentials:
   • TickTick: https://developer.ticktick.com/manage
   • Dida365: https://developer.dida365.com/manage
   • Click New App, then note your Client ID and Client Secret.
2. In your app's settings, add the redirect URL: http://localhost:8080/callback

API Reference

Official documentation:

• Dida365 API: https://developer.dida365.com/api#/openapi
• TickTick API: https://developer.ticktick.com/docs#/openapi

Usage

Tasks

from dida365 import TaskCreate, TaskUpdate, TaskPriority, TaskStatus

# Create
task = await client.create_task(
    TaskCreate(
        project_id="project_id",
        title="Complete documentation",
        priority=TaskPriority.HIGH,
    )
)

# Read
task = await client.get_task(project_id="project_id", task_id=task.id)

# Update
task = await client.update_task(
    TaskUpdate(
        id=task.id,
        project_id=task.project_id,
        title="Updated title",
    )
)

# Complete
await client.complete_task(project_id=task.project_id, task_id=task.id)

# Delete
await client.delete_task(project_id=task.project_id, task_id=task.id)

# Filter tasks
tasks = await client.filter_tasks(
    project_ids=["project_id"],
    priority=[TaskPriority.HIGH],
    status=[TaskStatus.NORMAL],
)

Projects

from dida365 import ProjectCreate, ProjectUpdate, ViewMode

# Create
project = await client.create_project(
    ProjectCreate(name="My Project", color="#FF0000", view_mode=ViewMode.KANBAN)
)

# List all
projects = await client.get_projects()

# Get with tasks & columns
data = await client.get_project_with_data(project_id=project.id)

# Update
project = await client.update_project(
    ProjectUpdate(id=project.id, name="Renamed Project")
)

# Delete
await client.delete_project(project_id=project.id)

Tags

from dida365 import TagCreate

# List tags
tags = await client.get_tags()

# Create a tag
tag = await client.create_tag(TagCreate(name="urgent", label="urgent"))

Habits

from dida365 import HabitCreate, HabitUpdate

# List all habits
habits = await client.get_all_habits()

# Create a habit
habit = await client.create_habit(
    HabitCreate(name="Morning run", color="#00FF00", sort_order=0)
)

# Update a habit
habit = await client.update_habit(habit_id=habit.id, habit=HabitUpdate(name="Evening run"))

# Get habit checkins
checkins = await client.get_habit_checkins(
    habit_ids=habit.id, from_stamp=20240101, to_stamp=20240131
)

Focus

from datetime import datetime, timezone, timedelta
from dida365 import FocusCreate, FocusType

# Get focus sessions
sessions = await client.get_focuses(
    from_date="2024-01-01T00:00:00+0800",
    to_date="2024-01-31T00:00:00+0800",
    focus_type=FocusType.POMODORO,
)

# Create a focus session
focus = await client.create_focus(
    FocusCreate(
        type=FocusType.POMODORO,
        start_time=datetime(2024, 1, 1, 9, 0, 0, tzinfo=timezone(timedelta(hours=8))),
        end_time=datetime(2024, 1, 1, 9, 25, 0, tzinfo=timezone(timedelta(hours=8))),
        duration=1500,
    )
)

Countdown

# List all countdowns
countdowns = await client.get_countdowns()

Requirements

• Python 3.10 or higher

Contributing

Contributions are welcome! Feel free to submit a Pull Request.

License

This project is licensed under the MIT License — see the LICENSE file for details.

Author

Original project by Carter Yifeng Cheng (@cyfine).
This fork maintained by Konano.