Tasks¶
Tasks ¶
Tasks(auth: GoogleAuth, tasklist_id: str = DEFAULT_LIST)
High-level Google Tasks client.
Example
auth = GoogleAuth(scopes=Scopes.tasks()) auth.authenticate()
tasks = Tasks(auth)
for task in tasks.list_tasks(): print(task.title, task.due)
task = tasks.create_task("Pay rent", due=date(2026, 2, 1)) tasks.complete_task(task.id)
Task methods take an optional tasklist_id; it defaults to the user's
default list (@default).
list_tasklists ¶
list_tasklists(max_results: int | None = None) -> list[TaskList]
All task lists of the user.
get_tasklist ¶
get_tasklist(tasklist_id: str) -> TaskList | None
A task list by ID, or None if it doesn't exist.
rename_tasklist ¶
rename_tasklist(tasklist_id: str, title: str) -> TaskList
Change the title of a task list.
delete_tasklist ¶
delete_tasklist(tasklist_id: str) -> bool
Delete a task list and its tasks. False if it didn't exist.
iter_tasks ¶
iter_tasks(tasklist_id: str | None = None, show_completed: bool = True, show_hidden: bool = False, due_min: date | None = None, due_max: date | None = None, max_results: int | None = None) -> Iterator[Task]
Iterate over the tasks of a list, following pagination.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
show_completed
|
bool
|
Include completed tasks. |
True
|
show_hidden
|
bool
|
Include hidden tasks (completed and then cleared). |
False
|
due_min
|
date | None
|
Only tasks due on or after this day. |
None
|
due_max
|
date | None
|
Only tasks due on or before this day. |
None
|
list_tasks ¶
list_tasks(tasklist_id: str | None = None, **kwargs: Any) -> list[Task]
Tasks of a list (see iter_tasks for the filters).
get_task ¶
get_task(task_id: str, tasklist_id: str | None = None) -> Task | None
A task by ID, or None if it doesn't exist.
create_task ¶
create_task(title: str, notes: str | None = None, due: date | None = None, tasklist_id: str | None = None, parent: str | None = None, previous: str | None = None) -> Task
Create a task.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
due
|
date | None
|
Due day (the API ignores any time of day). |
None
|
parent
|
str | None
|
Create it as a subtask of this task. |
None
|
previous
|
str | None
|
Place it after this sibling (default: first position). |
None
|
update_task ¶
update_task(task_id: str, tasklist_id: str | None = None, title: str | None = None, notes: str | None = _UNSET, due: date | None = _UNSET) -> Task
Change fields of a task; only the given ones are sent.
notes=None / due=None clear the field (omit them to leave it).
complete_task ¶
complete_task(task_id: str, tasklist_id: str | None = None) -> Task
Mark a task as completed.
reopen_task ¶
reopen_task(task_id: str, tasklist_id: str | None = None) -> Task
Mark a completed task as pending again.
completed must be cleared too, or the API keeps the task done.
move_task ¶
move_task(task_id: str, tasklist_id: str | None = None, parent: str | None = None, previous: str | None = None) -> Task
Move a task: under parent (None = top level), after previous (None = first).
delete_task ¶
delete_task(task_id: str, tasklist_id: str | None = None) -> bool
Delete a task. False if it didn't exist.
clear_completed ¶
clear_completed(tasklist_id: str | None = None) -> None
Hide the completed tasks of a list (they stay readable with show_hidden).
Task
dataclass
¶
Task(id: str, title: str, tasklist_id: str, notes: str | None = None, status: str = 'needsAction', due: date | None = None, completed: datetime | None = None, updated: datetime | None = None, parent: str | None = None, position: str | None = None, deleted: bool = False, hidden: bool = False, web_view_link: str | None = None, raw: dict[str, Any] = dict())
A task in a task list.
due is a date: the Tasks API stores only the day and discards any time.
TaskList
dataclass
¶
TaskList(id: str, title: str, updated: datetime | None = None, raw: dict[str, Any] = dict())
A Google Tasks list.