https://github.com/lazeroffmichael/ticktick-py
Unofficial TickTick API
https://github.com/lazeroffmichael/ticktick-py
Last synced: 4 months ago
JSON representation
Unofficial TickTick API
- Host: GitHub
- URL: https://github.com/lazeroffmichael/ticktick-py
- Owner: lazeroffmichael
- License: mit
- Created: 2020-12-09T06:33:49.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-03-21T06:40:21.000Z (over 1 year ago)
- Last Synced: 2025-03-03T03:06:11.997Z (4 months ago)
- Language: Python
- Homepage: https://lazeroffmichael.github.io/ticktick-py/
- Size: 4.36 MB
- Stars: 229
- Watchers: 11
- Forks: 31
- Open Issues: 33
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://lazeroffmichael.github.io/ticktick-py/)
# ticktick-py
## Unofficial TickTick API Client for Python 3
## [Full Documentation](https://lazeroffmichael.github.io/ticktick-py/)
## Description
`ticktick-py` is an unofficial API library for interacting with [TickTick.com]().
It allows
users a way to interact with their [TickTick]() account
using [Python](https://www.python.org/).
## Features
The library automatically fetches all the tasks, tags, lists, and more linked to your profile and stores them in a
dictionary named [`state`](docs/usage/api.md).
- [Tasks](docs/usage/tasks.md)
- Create, Update, and Delete Tasks
- Acquire all your uncompleted tasks
- Move tasks easily between projects
- Acquire all completed tasks in a certain date range
- [Tags](docs/usage/tags.md)
- Batch create, update, and delete tags
- Create tags with parameters that are not usually allowed: `\\ / " # : * ? < > | Space`
- [Projects](docs/usage/projects.md)
- Batch create, update, and delete 'lists' (projects)
- Batch archive projects
### Example: Creating A Task
Lets create a task in our ```inbox``` titled "Get Groceries"
``` python
name = 'Get Groceries' # Task Name
local_task = client.task.builder(name) # Create a dictionary for the task
groceries = client.task.create(local_task) # Actually create the task
```
### Result
A simplified dictionary for the newly created task is returned.
```python
print(groceries)
{'id': '60c6a40b8f083f896c9444a0', 'projectId': 'inbox115781412', 'title': 'Get Groceries', 'timeZone': '',
'reminders': [], 'priority': 0, 'status': 0, 'sortOrder': -3298534883328, 'items': []}
```
You can retrieve the full dictionary with every parameter by using the `get_by_id` method.
```python
full_task = client.get_by_id(groceries['id'])
print(full_task)
{'id': '60c6a40b8f083f896c9444a0', 'projectId': 'inbox115781412', 'sortOrder': -3298534883328,
'title': 'Get Groceries', 'timeZone': '', 'isFloating': False, 'reminder': '', 'reminders': [],
'priority': 0, 'status': 0, 'items': [], 'modifiedTime': '2021-06-14T00:34:19.907+0000', 'etag': 't8xnwewi',
'deleted': 0, 'createdTime': '2021-06-14T00:34:19.907+0000', 'creator': 113581412, 'tags': [], 'kind': 'TEXT'}
```
**Created Task In `TickTick`**
Most methods will return the object that was changed. Consult the [usage](docs/usage/api.md) documentation for more information on specific methods.
## Installation
Note: `ticktick-py` requires [Python 3.6](https://www.python.org/downloads/) or above.
```md
pip install ticktick-py
```
## Get Started
### Register A New TickTick App
The library now uses TickTick's OpenAPI scheme when possible. This requires registering
a new app through TickTick's developer documentation.
[OpenAPI Documentation](https://developer.ticktick.com/docs#/openapi)
Click on `Manage Apps` in the top right corner. You will be prompted to login with your
normal TickTick credentials if you are not already logged in.
Register a new app by clicking the `+App Name` button.
`Name` is the only required parameter here. Once created you should see the app and be able to edit it.
There should now be a generated `Client ID` and `Client Secret` parameters. It is recommended you save these to your
environment, and make sure you do not share your actual `Client Secret`.
For `OAuth Redirect URL` enter any URL you would like to be redirected to upon giving permissions to your account.
It does not have to be an actually live URL - this local host URL is fine for most purposes. It is also recommended you
save this URL to your environment.
Once you have registered the app, you can now proceed with the rest of the setup.
### Required Imports
``` python
from ticktick.oauth2 import OAuth2 # OAuth2 Manager
from ticktick.api import TickTickClient # Main Interface
```
### Setup
``` python
auth_client = OAuth2(client_id=client_id,
client_secret=client_secret,
redirect_uri=uri)
client = TickTickClient(username, password, auth_client)
```
The first time the OAuth2 object runs, you will need to manually accept permissions. A webbrowser will automatically
open.
The default permissions are to Read and Write tasks (and are the only options right now). You can change the permissions
by specifying the `scope` parameter when creating your OAuth2 instance. More information can be found in the
[OAuth2 documention](docs/usage/oauth2.md).
In the console you will be prompted to enter the URL that you were redirected to. It will be your specified OAuth URL
with some added parameters.
```
Enter the URL you were redirected to:
>? http://127.0.0.1:8080/?code=RK3dSi&state=None
```
That is it! Your token information is cached in a file (default is `.token-oauth`) so you will only have to manually
allow access the first time, and whenever the token expires. As of now it seems tokens expire after about 6 months.
## Future Plans
- **General**
- Enhanced Team Support
- **Tasks**
- Get and Restore From Trash
- **Projects**
- Smart List Support
- Column Creation For Kanban View
- **Pomo and Focus**
- Getting the focus / pomo statistics for your profile
- Starting and stopping the focus / pomo timer
- **Habits**
- Get, create, archive, delete, and complete habits