Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lazeroffmichael/ticktick-py
Unofficial TickTick API
https://github.com/lazeroffmichael/ticktick-py
Last synced: 11 days 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 (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-03-21T06:40:21.000Z (8 months ago)
- Last Synced: 2024-10-01T02:58:23.902Z (about 1 month ago)
- Language: Python
- Homepage: https://lazeroffmichael.github.io/ticktick-py/
- Size: 4.36 MB
- Stars: 211
- Watchers: 11
- Forks: 30
- Open Issues: 31
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
![unit-tests](https://github.com/lazeroffmichael/ticktick-py/workflows/unit-tests/badge.svg)
[![documentation](https://img.shields.io/badge/docs-mkdocs%20material-blue.svg?style=flat)](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`**
![image](https://user-images.githubusercontent.com/56806733/121826787-7c5ef980-cc6e-11eb-8483-745df39e973b.png)
Most methods will return the object that was changed. Consult the [usage](docs/usage/api.md) documentation for more information on specific methods.
## InstallationNote: `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.![image](https://user-images.githubusercontent.com/56806733/121824548-c4c3ea80-cc61-11eb-8160-698b6ae5c9f6.png)
Register a new app by clicking the `+App Name` button.
![image](https://user-images.githubusercontent.com/56806733/121824646-87139180-cc62-11eb-9911-fc8bc4d6c3d6.png)
`Name` is the only required parameter here. Once created you should see the app and be able to edit it.
![image](https://user-images.githubusercontent.com/56806733/121825007-e377b080-cc64-11eb-957c-cedf3ef8f7fd.png)
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`.![image](https://user-images.githubusercontent.com/56806733/121825074-584aea80-cc65-11eb-8262-8dde4d9481a1.png)
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.![image](https://user-images.githubusercontent.com/56806733/121825203-e1fab800-cc65-11eb-9a2d-38d0787c5b1b.png)
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.![image](https://user-images.githubusercontent.com/56806733/121825814-479c7380-cc69-11eb-8b0d-a2ff6ef1e8bd.png)
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