About this project

ticktick-py-v2 is a Python wrapper around TickTick's unofficial `api/v2` endpoint, the internal interface used by the web app and desktop clients. The author frames it as an alternative to TickTick's official OAuth API, which covers tasks and projects but exposes habits read-only and has no focus/pomodoro endpoints. What the library exposes, per the README: - Tasks and projects: read active tasks and project lists, create tasks, complete tasks, and enrich task objects with project properties such as project names. - Habits: read check-ins (e.g. after a given date stamp) and post check-ins, which the README suggests as a way to backfill habit history from another data source. - Focus/Pomodoro: read focus sessions over a day offset, check whether a session is currently running, and add focus records for historic sessions (start/end timestamps). - Calendar events: retrieve all events. Design notes from the README: - The API is exposed as plain functions rather than stateful client classes; each call accepts an optional `headers` argument, so auth headers can be fetched once via `get_authenticated_ticktick_headers()` and reused, or fetched fresh per call (cheap once the login is cached on disk). - Authentication uses the normal login session (cookies), not OAuth. Credentials can be supplied through `TICKTICK_EMAIL` and `TICKTICK_PASSWORD` environment variables, with a headless Selenium session handling login and caching cookies; alternatively cookies can be exported manually into a `.ticktick-cookies.json` file. - Return values are pydantic `BaseModel` instances, convertible with `.model_dump()` or `.model_dump(by_alias=True)` for TickTick's native camelCase field names. Installation is via `pip install ticktick-py-v2`; tests run with pytest against the included `tests/` directory. The repository is organised into `cookies_login.py`, `events.py`, `focus.py`, `habits.py`, `tasks.py`, plus `utils/` and `web/` internals. The README is explicit about the main tradeoff: this is an unofficial, reverse-engineered API that authenticates through a user's login session and can break if TickTick changes its internal endpoints. The contribution section invites issues and pull requests for uncovered endpoints such as recurring-task edge cases, subtasks and reminders, and asks for failing request/response details when an endpoint changes. Licensed under Apache 2.0.