### Get Auth Token Example

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/models.md

Example of how to obtain an access token using client credentials and an authorization code from an OAuth redirect.

```python
from todoist_api_python.authentication import get_auth_token

# After receiving auth code from OAuth redirect
auth_result = get_auth_token(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    code="auth_code_from_redirect",
)

api_token = auth_result.access_token
```

--------------------------------

### Create and Get Labels Example

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/models.md

Demonstrates how to create a new label with specified properties and how to retrieve all labels associated with the authenticated user. Requires an initialized TodoistAPI object.

```python
from todoist_api_python.api import TodoistAPI

api = TodoistAPI("TOKEN")

# Create label
label = api.add_label("work", color="blue", favorite=True)
print(f"Label ID: {label.id}")

# Get labels
for labels in api.get_labels():
    for label in labels:
        print(f"{label.name}: {label.color}")
```

--------------------------------

### Get Tasks Example

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-reference/TodoistAPIAsync.md

This example shows how to iterate through tasks within a specific project using the asynchronous `get_tasks` method and an async for loop.

```python
import asyncio
from todoist_api_python.api_async import TodoistAPIAsync

async def main():
    async with TodoistAPIAsync("YOUR_API_TOKEN") as api:
        async for tasks in api.get_tasks(project_id="project_id"):
            for task in tasks:
                print(f"Task: {task.content}")

asyncio.run(main())

```

--------------------------------

### Install todoist-api-python Package

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/INDEX.md

Install the library using pip, specifying a version range for compatibility.

```bash
pip install todoist-api-python>=4.0.0,<5
```

--------------------------------

### Install Todoist API Python SDK

Source: https://github.com/doist/todoist-api-python/blob/main/docs/index.md

Install the SDK using pip. Alternatively, add it as a dependency in your pyproject.toml file.

```bash
pip install todoist-api-python
```

```toml
dependencies = [
  "todoist-api-python>=3.1.0,<4",
]
```

--------------------------------

### Project Parameter Examples

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/REFERENCE.md

Examples of parameters for creating or updating projects. 'name' is the project title, 'color' is a color string, and 'view_style' can be 'list', 'board', or 'calendar'.

```python
"My Project"
```

```python
"blue"
```

```python
"board"
```

--------------------------------

### Get Task Example

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-reference/TodoistAPIAsync.md

Demonstrates fetching a single task by its ID and printing its content using the asynchronous API client within an async context manager.

```python
import asyncio
from todoist_api_python.api_async import TodoistAPIAsync

async def main():
    async with TodoistAPIAsync("YOUR_API_TOKEN") as api:
        task = await api.get_task("6X4Vw2Hfmg73Q2XR")
        print(f"Task: {task.content}")

asyncio.run(main())

```

--------------------------------

### Get Sections Example

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/models.md

Demonstrates how to retrieve all sections for a given project using the Todoist API Python client. Requires an initialized API object and a project ID.

```python
from todoist_api_python.api import TodoistAPI

api = TodoistAPI("TOKEN")
for sections in api.get_sections(project_id="project_id"):
    for section in sections:
        print(f"Section: {section.name}")
```

--------------------------------

### Install Todoist API Python Client

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/REFERENCE.md

Install the Todoist API Python client using pip. Ensure you are using Python 3.10 or later.

```bash
pip install todoist-api-python
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/doist/todoist-api-python/blob/main/README.md

Install pre-commit hooks for development. This ensures code quality and consistency before committing changes.

```sh
$ uv run pre-commit install
```

--------------------------------

### Task Parameter Examples

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/REFERENCE.md

Examples of parameters for creating or updating tasks. 'content' is the task description, 'priority' is an integer from 1-4, 'due_date' is an ISO date, 'due_string' is a natural language date, 'labels' are strings, 'duration' is an integer, and 'duration_unit' specifies the unit.

```python
"Buy milk"
```

```python
4
```

```python
date(2024, 1, 15)
```

```python
"tomorrow"
```

```python
["work", "urgent"]
```

```python
30
```

```python
"minute"
```

--------------------------------

### Add and Get Reminders Example

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/models.md

Shows how to add a new reminder to a specific task with relative timing and push notification, and how to retrieve reminders for a given task. Requires an initialized TodoistAPI object and a valid task ID.

```python
from todoist_api_python.api import TodoistAPI

api = TodoistAPI("TOKEN")

# Add reminder
reminder = api.add_reminder(
    "task_id",
    reminder_type="relative",
    minute_offset=30,
    service="push",
)

# Get reminders
for reminders in api.get_reminders(task_id="task_id"):
    for reminder in reminders:
        print(f"Reminder type: {reminder.type}")
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/doist/todoist-api-python/blob/main/README.md

Install Python dependencies for development using uv. This command synchronizes the project's dependencies.

```sh
$ uv sync
```

--------------------------------

### Reminder Parameter Examples

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/REFERENCE.md

Examples of parameters for setting reminders. 'reminder_type' can be 'relative' or 'absolute', 'minute_offset' is an integer for relative reminders, and 'service' can be 'email' or 'push'.

```python
"relative"
```

```python
30
```

```python
"push"
```

--------------------------------

### Get Task Due Date Example

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/models.md

Shows how to fetch a task and access its due date details, including the parsed date, original string, and recurrence information. Requires an initialized API object and a task ID.

```python
from todoist_api_python.api import TodoistAPI

api = TodoistAPI("TOKEN")
task = api.get_task("task_id")

if task.due:
    print(f"Due: {task.due.date}")
    print(f"Original string: {task.due.string}")
    print(f"Recurring: {task.due.is_recurring}")
```

--------------------------------

### Generate Auth URL and Obtain Access Token

Source: https://github.com/doist/todoist-api-python/blob/main/docs/authentication.md

Use these functions to guide users through the OAuth flow. First, generate an authorization URL, then handle the callback to get a code, and finally exchange the code for an access token. Ensure the state parameter is used for security and consistency.

```python
import uuid

from todoist_api_python.authentication import get_auth_token, get_authentication_url

# 1. Generate a random state
state = str(uuid.uuid4())

# 2. Build the authorization URL
url = get_authentication_url(
    client_id="YOUR_CLIENT_ID",
    scopes=["data:read", "task:add"],
    state=state,
)

# 3. Redirect the user to `url`
# 4. Handle the OAuth callback and obtain the auth code
code = "CODE_YOU_OBTAINED"

# 5. Exchange code for an access token
auth_result = get_auth_token(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    code=code,
)

# 6. Ensure state is consistent, and done!
assert auth_result.state == state
access_token = auth_result.access_token
```

--------------------------------

### Add Task with Duration Examples

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/types.md

Demonstrates how to add tasks with specified durations using 'minute' or 'day' as the unit.

```python
from todoist_api_python.api import TodoistAPI

api = TodoistAPI("TOKEN")

# Task with 30-minute duration
task = api.add_task(
    "Team standup",
    duration=30,
    duration_unit="minute",
)

# Task with 2-day duration
task = api.add_task(
    "Write proposal",
    duration=2,
    duration_unit="day",
)
```

--------------------------------

### Example: Retrieve and Display Project Information

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/models.md

Demonstrates how to instantiate the Todoist API client, fetch a project by its ID, and then print various details about the project, including its name, color, view style, sharing status, and URL.

```python
from todoist_api_python.api import TodoistAPI

api = TodoistAPI("TOKEN")
project = api.get_project("project_id")

print(f"Project: {project.name}")
print(f"Color: {project.color}")
print(f"View: {project.view_style}")
print(f"Shared: {project.is_shared}")
print(f"URL: {project.url}")
```

--------------------------------

### Filter Tasks Example

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-reference/TodoistAPIAsync.md

This example demonstrates filtering tasks using a query string like 'p1 | p2' and iterating through the results asynchronously.

```python
async def main():
    async with TodoistAPIAsync("YOUR_API_TOKEN") as api:
        async for tasks in api.filter_tasks(query="p1 | p2"):
            for task in tasks:
                print(f"High priority: {task.content}")

asyncio.run(main())

```

--------------------------------

### Using Quick Add Metadata

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/models.md

Demonstrates how to add a task using quick add syntax and then access the parsed metadata, such as project and labels, from the returned task object. This example requires a valid API token.

```python
api = TodoistAPI("TOKEN")

# Quick add parsing metadata
task = api.add_task_quick(
    "Buy milk #Shopping @groceries tomorrow p1"
)

if task.meta:
    if task.meta.project[0]:
        print(f"Project: {task.meta.project[1]}")
    if task.meta.labels:
        print(f"Labels: {list(task.meta.labels.values())}")
```

--------------------------------

### Example Usage of Task Model

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/models.md

Demonstrates how to retrieve a task using the Todoist API Python client and access its various properties, including content, priority, labels, due date, completion status, URL, and assignee. This example requires a valid API token and task ID.

```python
from todoist_api_python.api import TodoistAPI

api = TodoistAPI("TOKEN")
task = api.get_task("task_id")

print(f"Task: {task.content}")
print(f"Priority: {task.priority}")
print(f"Labels: {task.labels}")
print(f"Due: {task.due.date if task.due else 'No due date'}")
print(f"Completed: {task.is_completed}")
print(f"URL: {task.url}")

if task.assignee_id:
    print(f"Assigned to: {task.assignee_id}")
```

--------------------------------

### Add Project and Label with Color

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/types.md

Example demonstrating how to create a new project and a new label with specified colors using the Todoist API Python library. Colors must be from the supported list.

```python
from todoist_api_python.api import TodoistAPI

api = TodoistAPI("TOKEN")

# Create project with color
project = api.add_project(
    "Work",
    color="blue",
)

# Create label with color
label = api.add_label(
    "urgent",
    color="red",
)

# Update project color
updated = api.update_project("project_id", color="purple")
```

--------------------------------

### Manual API Client Closing Example

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-reference/TodoistAPIAsync.md

This example demonstrates how to manually close the `TodoistAPIAsync` client using a `try...finally` block when not using the `async with` statement.

```python
api = TodoistAPIAsync("YOUR_API_TOKEN")
try:
    task = await api.get_task("task_id")
finally:
    await api.close()

```

--------------------------------

### Run Python REPL for Development

Source: https://github.com/doist/todoist-api-python/blob/main/README.md

Start a Python REPL session using uv to test changes interactively. You can import the library directly without creating a file.

```sh
$ uv run python
```

--------------------------------

### Location Reminder Parameter Examples

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/REFERENCE.md

Examples of parameters for location-based reminders. 'loc_trigger' can be 'on_enter' or 'on_leave', and 'radius' is an integer specifying the trigger radius in meters.

```python
"on_enter"
```

```python
200
```

--------------------------------

### Add Location Reminder Examples

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/types.md

Demonstrates adding location-based reminders, specifying trigger conditions like entering or leaving a location.

```python
from todoist_api_python.api import TodoistAPI

api = TodoistAPI("TOKEN")

# Remind when entering grocery store
reminder = api.add_location_reminder(
    "task_id",
    name="Grocery Store",
    loc_lat="40.7128",
    loc_long="-74.0060",
    loc_trigger="on_enter",
    radius=200,
)

# Remind when leaving office
reminder = api.add_location_reminder(
    "task_id",
    name="Office",
    loc_lat="40.7580",
    loc_long="-73.9855",
    loc_trigger="on_leave",
)
```

--------------------------------

### GET /projects

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-endpoints.md

Retrieves all active projects. Supports filtering by limit and pagination using a cursor.

```APIDOC
## GET /projects

### Description
Get all active projects.

### Method
GET

### Endpoint
/projects

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Max per page
- **cursor** (string) - Optional - Pagination cursor
```

--------------------------------

### GET /projects/{id}

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-endpoints.md

Retrieves a specific project by its unique identifier.

```APIDOC
## GET /projects/{id}

### Description
Get a project by ID.

### Method
GET

### Endpoint
/projects/{id}
```

--------------------------------

### Get a Task

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/00-START-HERE.txt

Retrieve a specific task using its ID. Ensure you have initialized the TodoistAPI with your authentication token.

```python
from todoist_api_python.api import TodoistAPI
api = TodoistAPI("YOUR_TOKEN")
task = api.get_task("task_id")
```

--------------------------------

### Get a Project by ID

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-reference/TodoistAPI.md

Retrieve a specific project using its unique identifier. Requires the project ID as a string.

```python
api = TodoistAPI("YOUR_API_TOKEN")
project = api.get_project("project_id")
print(f"Project: {project.name}")
print(f"Color: {project.color}")
```

--------------------------------

### Create, Update, and Delete Tasks

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/REFERENCE.md

Provides examples for creating new tasks, updating existing tasks by sending only changed fields, and deleting tasks.

```APIDOC
## Create and Update Tasks

### Description
This section covers the basic operations of creating, updating, and deleting tasks using the Todoist API Python client.

### Create Task
```python
from todoist_api_python.api import TodoistAPI

api = TodoistAPI("TOKEN")

task = api.add_task("New task", priority=2)
print(f"Created task with ID: {task.id}")
```

### Update Task
```python
# Update (only changed fields needed)
updated = api.update_task(task.id, priority=4)
print(f"Updated task priority to: {updated.priority}")
```

### Delete Task
```python
api.delete_task(task.id)
print(f"Deleted task with ID: {task.id}")
```
```

--------------------------------

### Async Project Operations

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-reference/TodoistAPIAsync.md

Demonstrates how to perform asynchronous operations on projects, including getting, adding, and iterating through projects. Ensure you have your API token and project IDs ready.

```python
async def main():
    async with TodoistAPIAsync("YOUR_API_TOKEN") as api:
        # Get project
        project = await api.get_project("project_id")
        
        # Add project
        new_project = await api.add_project("New Project", color="blue")
        
        # Iterate projects
        async for projects in api.get_projects(limit=50):
            for project in projects:
                print(project.name)

asyncio.run(main())
```

--------------------------------

### Get Project Collaborators

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/models.md

Shows how to fetch a list of collaborators for a given project ID. Requires API token and project ID.

```python
api = TodoistAPI("TOKEN")

# Get collaborators
for collaborators in api.get_collaborators("project_id"):
    for collab in collaborators:
        print(f"{collab.name} ({collab.email})")
```

--------------------------------

### Use Async API to Get Tasks

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/00-START-HERE.txt

Demonstrates the asynchronous usage of the Todoist API client to fetch all tasks. Requires an async context manager.

```python
from todoist_api_python.api_async import TodoistAPIAsync
async with TodoistAPIAsync("TOKEN") as api:
    tasks = await api.get_tasks()
```

--------------------------------

### Get Authentication URL with Scopes

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/types.md

Shows how to generate an authentication URL requesting specific API permission scopes.

```python
from todoist_api_python.authentication import get_authentication_url

# Request read and write access
auth_url = get_authentication_url(
    client_id="YOUR_CLIENT_ID",
    scopes=["data:read_write"],
    state="random_state_value",
)

# Request multiple scopes
auth_url = get_authentication_url(
    client_id="YOUR_CLIENT_ID",
    scopes=["data:read", "task:add"],
    state="random_state_value",
)
```

--------------------------------

### Project URL Property

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/models.md

Provides a convenient way to get the URL for viewing a specific project within the Todoist application.

```python
@property
def url(self) -> str:
    """Get the URL for viewing this project in the Todoist app."""
```

--------------------------------

### Initialize TodoistAPI Client

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-reference/TodoistAPI.md

Demonstrates basic initialization of the TodoistAPI client with an authentication token. Shows how to provide a custom httpx client, disable request ID generation, and use the client as a context manager.

```python
from todoist_api_python.api import TodoistAPI

# Basic initialization
api = TodoistAPI("YOUR_API_TOKEN")

# With custom httpx client
import httpx
custom_client = httpx.Client(timeout=30.0)
api = TodoistAPI("YOUR_API_TOKEN", client=custom_client)

# Disable request ID generation
api = TodoistAPI("YOUR_API_TOKEN", request_id_fn=None)

# Use as context manager
with TodoistAPI("YOUR_API_TOKEN") as api:
    task = api.get_task("task_id")
```

--------------------------------

### Get All Projects

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-reference/TodoistAPI.md

Iterate through all active projects. Each iteration makes a network request, so be mindful of rate limits. An optional limit can be set for projects per page.

```python
api = TodoistAPI("YOUR_API_TOKEN")

# Get all projects
for projects in api.get_projects():
    for project in projects:
        print(f"Project: {project.name}")

# With limit
for projects in api.get_projects(limit=50):
    for project in projects:
        print(project.name)
```

--------------------------------

### Add Task Quickly Asynchronously

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-reference/TodoistAPIAsync.md

Create a task asynchronously using Quick Add syntax. This method is useful for quickly adding tasks with natural language processing for details like project, labels, and due dates. Ensure you have the httpx library installed.

```python
async def add_task_quick(
    self,
    text: str,
    *,
    note: str | None = None,
    reminder: str | None = None,
    auto_reminder: bool = True,
) -> Task:
```

```python
async def main():
    async with TodoistAPIAsync("YOUR_API_TOKEN") as api:
        task = await api.add_task_quick(
            "Buy milk #Shopping @groceries tomorrow p1"
        )
        print(f"Created: {task.content}")

asyncio.run(main())
```

--------------------------------

### Add Task Asynchronously

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-reference/TodoistAPIAsync.md

Create a new task asynchronously. All parameters are identical to the synchronous TodoistAPI.add_task method. Ensure you have the httpx library installed.

```python
async def add_task(
    self,
    content: Annotated[str, MinLen(1), MaxLen(500)],
    *,
    description: Annotated[str, MaxLen(16383)] | None = None,
    project_id: str | None = None,
    section_id: str | None = None,
    parent_id: str | None = None,
    labels: list[Annotated[str, MaxLen(100)]] | None = None,
    priority: Annotated[int, Ge(1), Le(4)] | None = None,
    due_string: Annotated[str, MaxLen(150)] | None = None,
    due_lang: LanguageCode | None = None,
    due_date: date | None = None,
    due_datetime: datetime | None = None,
    assignee_id: str | None = None,
    order: int | None = None,
    auto_reminder: bool | None = None,
    auto_parse_labels: bool | None = None,
    duration: Annotated[int, Ge(1)] | None = None,
    duration_unit: Literal["minute", "day"] | None = None,
    deadline_date: date | None = None,
    deadline_lang: LanguageCode | None = None,
) -> Task:
```

```python
from datetime import date, timedelta

async def main():
    async with TodoistAPIAsync("YOUR_API_TOKEN") as api:
        task = await api.add_task(
            "Complete project report",
            project_id="project_id",
            labels=["work"],
            priority=4,
            due_date=date.today() + timedelta(days=1),
        )
        print(f"Created task: {task.id}")

asyncio.run(main())
```

--------------------------------

### Asynchronous GET Request to Todoist API

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/http-internals.md

Executes an asynchronous GET request to a specified URL. This is the async counterpart to the synchronous `get` function.

```python
async def get_async(
    client: httpx.AsyncClient,
    url: str,
    token: str | None = None,
    request_id: str | None = None,
    params: dict[str, Any] | None = None,
) -> httpx.Response:
```

--------------------------------

### Project Creation and Update with View Styles

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/types.md

Demonstrates how to create new projects with specific view styles (board, calendar) and how to update an existing project's view style to list using the Todoist API Python library.

```python
from todoist_api_python.api import TodoistAPI

api = TodoistAPI("TOKEN")

# Create project with board view
project = api.add_project(
    "Marketing Campaign",
    view_style="board",
)

# Create project with calendar view
project = api.add_project(
    "Events",
    view_style="calendar",
)

# Switch project to list view
updated = api.update_project("project_id", view_style="list")
```

--------------------------------

### Synchronous GET Request to Todoist API

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/http-internals.md

Executes a synchronous GET request to a specified URL. Use this for standard GET operations where asynchronous execution is not required.

```python
def get(
    client: httpx.Client,
    url: str,
    token: str | None = None,
    request_id: str | None = None,
    params: dict[str, Any] | None = None,
) -> httpx.Response:
```

--------------------------------

### Add and Get Location Reminders

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/models.md

Demonstrates how to add a new location reminder for a task and how to retrieve existing location reminders associated with a task. Requires API token and task ID.

```python
api = TodoistAPI("TOKEN")

# Add location reminder
reminder = api.add_location_reminder(
    "task_id",
    name="Office",
    loc_lat="40.7580",
    loc_long="-73.9855",
    loc_trigger="on_leave",
    radius=200,
)

# Get location reminders
for reminders in api.get_location_reminders(task_id="task_id"):
    for reminder in reminders:
        print(f"Location: {reminder.name}")
```

--------------------------------

### Basic Task Operations with TodoistAPI

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/INDEX.md

Demonstrates how to initialize the API, retrieve all tasks, create a new task with specific properties, update an existing task, and complete a task.

```python
from todoist_api_python.api import TodoistAPI

api = TodoistAPI("TOKEN")

# Get all tasks
for tasks in api.get_tasks():
    for task in tasks:
        print(f"{task.content} (priority: {task.priority})")

# Create task
task = api.add_task("Buy milk", priority=2, due_string="tomorrow")

# Update task
api.update_task(task.id, priority=4)

# Complete task
api.complete_task(task.id)
```

--------------------------------

### Importing and Using Type Hints

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/types.md

Demonstrates how to import specific types like LanguageCode, ColorString, and ViewStyle for type annotations. Shows their application in function signatures and for runtime type validation.

```python
from todoist_api_python.types import (
    LanguageCode,
    ColorString,
    ViewStyle,
)

def create_project(
    name: str,
    color: ColorString,
    view: ViewStyle,
) -> None:
    api = TodoistAPI("TOKEN")
    api.add_project(name, color=color, view_style=view)

lang_code: LanguageCode = "en"  # Valid
# lang_code: LanguageCode = "eng"  # TypeError: 3 characters, not 2
```

--------------------------------

### Projects and Sections Management

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/INDEX.md

Shows how to create a new project with a board view and add a section to that project. It also demonstrates retrieving tasks within a specific section.

```python
# Create project with board view
project = api.add_project("Marketing", color="blue", view_style="board")

# Add section to project
section = api.add_section("Backlog", project_id=project.id)

# Get tasks in section
for tasks in api.get_tasks(section_id=section.id):
    for task in tasks:
        print(task.content)
```

--------------------------------

### Initialize TodoistAPIAsync with Context Manager

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-reference/TodoistAPIAsync.md

Recommended way to initialize and use TodoistAPIAsync. Ensures the client is properly closed after use. Requires an API token.

```python
import asyncio
from todoist_api_python.api_async import TodoistAPIAsync

async def main():
    async with TodoistAPIAsync("YOUR_API_TOKEN") as api:
        task = await api.get_task("task_id")
        print(task.content)

asyncio.run(main())
```

--------------------------------

### Get Completed Tasks by Completion Date

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-endpoints.md

Retrieve tasks that were completed within a specified completion date range. This method is similar to getting tasks by due date but uses the actual completion timestamp.

```python
api = TodoistAPI("TOKEN")
for tasks in api.get_completed_tasks_by_completion_date(since=start, until=end):
    for task in tasks:
        print(task.content)
```

--------------------------------

### Basic Todoist API Python Usage

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/REFERENCE.md

Demonstrates how to initialize the synchronous TodoistAPI client, retrieve tasks, and add a new task. Replace 'YOUR_API_TOKEN' with your actual token.

```python
from todoist_api_python.api import TodoistAPI

api = TodoistAPI("YOUR_API_TOKEN")

# Get tasks
for tasks in api.get_tasks():
    for task in tasks:
        print(f"Task: {task.content}")

# Create task
task = api.add_task("Buy groceries", priority=2)

# Complete task
api.complete_task(task.id)
```

--------------------------------

### Initialize API Client and Fetch Task Comments

Source: https://github.com/doist/todoist-api-python/blob/main/docs/index.md

Initialize the Todoist API client with your token, fetch a specific task, and then paginate through its comments. Ensure you replace 'YOUR_API_TOKEN' with your actual API token.

```python
from todoist_api_python.api import TodoistAPI

api = TodoistAPI("YOUR_API_TOKEN")

task = api.get_task("6X4Vw2Hfmg73Q2XR")
print(f"Task: {task.content}")

comments_iter = api.get_comments(task_id=task.id)
for comments in comments_iter:
    for comment in comments:
        print(f"Comment: {comment.content}")
```

--------------------------------

### GET /reminders/{id}

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-endpoints.md

Retrieves a specific reminder by its unique ID.

```APIDOC
## GET /reminders/{id}

### Description
Get a reminder by ID.

### Method
GET

### Endpoint
/reminders/{id}
```

--------------------------------

### GET /labels/{id}

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-endpoints.md

Retrieves a specific label by its unique identifier.

```APIDOC
## GET /labels/{id}

### Description
Get a label by ID.

### Method
GET

### Endpoint
/labels/{id}
```

--------------------------------

### Add a New Project

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-reference/TodoistAPI.md

Create a new project with a name. Optional parameters include color, favorite status, view style, and parent project ID for nesting.

```python
api = TodoistAPI("YOUR_API_TOKEN")

# Simple project
project = api.add_project("My Project")

# With color and view style
project = api.add_project(
    "Work Tasks",
    color="blue",
    view_style="board",
    favorite=True,
)

# Nested project
project = api.add_project(
    "Subproject",
    parent_id="parent_project_id",
)
```

--------------------------------

### GET /labels

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-endpoints.md

Retrieves a list of all available labels, with support for pagination.

```APIDOC
## GET /labels

### Description
Get all labels.

### Method
GET

### Endpoint
/labels

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Max per page
- **cursor** (string) - Optional - Pagination cursor
```

--------------------------------

### GET /comments/{id}

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-endpoints.md

Retrieves a specific comment by its unique identifier.

```APIDOC
## GET /comments/{id}

### Description
Get a comment by ID.

### Method
GET

### Endpoint
/comments/{id}
```

--------------------------------

### GET /sections/{id}

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-endpoints.md

Retrieves a specific section by its unique identifier.

```APIDOC
## GET /sections/{id}

### Description
Get a section by ID.

### Method
GET

### Endpoint
/sections/{id}
```

--------------------------------

### add_task_quick

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-reference/TodoistAPIAsync.md

Create a task asynchronously using Quick Add syntax. This method simplifies task creation by allowing natural language input.

```APIDOC
## `add_task_quick`

### Description
Create a task asynchronously using Quick Add syntax.

### Method
POST

### Endpoint
/tasks/quick

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **text** (str) - Required - Task text with Quick Add syntax.
- **note** (str | None) - Optional - An optional note for the task.
- **reminder** (str | None) - Optional - An optional reminder date string.
- **auto_reminder** (bool) - Optional - Default: True. Add default reminder if needed.

### Request Example
```json
{
  "text": "Buy milk #Shopping @groceries tomorrow p1",
  "note": "Remember to get the organic kind.",
  "reminder": "tomorrow 10:00"
}
```

### Response
#### Success Response (200)
- **Task** (object) - The newly created task object.

#### Response Example
```json
{
  "id": "67890",
  "content": "Buy milk",
  "project_id": "shopping_project_id",
  "labels": ["Shopping"],
  "due_date": "YYYY-MM-DD"
}
```
```

--------------------------------

### TodoistAPIAsync Context Manager

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-reference/TodoistAPIAsync.md

Demonstrates the recommended way to initialize and use the asynchronous Todoist API client using an async context manager for proper resource management.

```APIDOC
## Best Practices for Async Code: Context Manager

### Description
It is best practice to use the `async with` statement when initializing the `TodoistAPIAsync` client. This ensures that resources are automatically cleaned up upon exiting the context, preventing potential issues.

### Usage
Instantiate the client within an `async with` block to manage its lifecycle.

### Example
```python
import asyncio
from todoist_api_python.api import TodoistAPIAsync

async def get_single_task():
    async with TodoistAPIAsync("TOKEN") as api:
        task = await api.get_task("id")
        print(task.content)

asyncio.run(get_single_task())
```
```

--------------------------------

### GET /authorize

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-endpoints.md

Authorizes a user and requests specific scopes for the OAuth application.

```APIDOC
## GET /authorize

### Description
Authorize a user and request scopes.

### Method
GET

### Endpoint
/authorize

### Parameters
#### Query Parameters
- **client_id** (string) - Required - OAuth app client ID
- **scope** (string) - Required - Comma-separated scopes
- **state** (string) - Optional - State for CSRF protection
- **redirect_uri** (string) - Optional - Where to redirect after auth
```

--------------------------------

### Create Task with Quick Add Syntax

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-endpoints.md

Use this snippet to create a new task using Todoist's Quick Add syntax. This allows for natural language input to define task details like name, project, priority, and due date.

```python
api = TodoistAPI("TOKEN")
task = api.add_task_quick("Buy milk #Shopping tomorrow p1")
```

--------------------------------

### GET /location_reminders/{id}

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-endpoints.md

Retrieves a specific location reminder by its unique identifier.

```APIDOC
## GET /location_reminders/{id}

### Description
Get a location reminder by ID.

### Method
GET

### Endpoint
/location_reminders/{id}
```

--------------------------------

### POST /tasks/quick

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-endpoints.md

Creates a new task using Todoist's Quick Add syntax. This endpoint allows for the creation of tasks with text, optional reminders, notes, and specific reminder dates.

```APIDOC
## POST /tasks/quick

### Description
Create task using Quick Add syntax.

### Method
POST

### Endpoint
/tasks/quick

### Parameters
#### Request Body
- **text** (string) - Required - Task text with Quick Add syntax
- **auto_reminder** (boolean) - Optional - Add reminder if date with time set
- **note** (string) - Optional - Note to add
- **reminder** (string) - Optional - Reminder date

### Request Example
```json
{
  "text": "Buy milk #Shopping tomorrow p1",
  "auto_reminder": true,
  "note": "Remember to get the organic kind.",
  "reminder": "tomorrow 9am"
}
```

### Response
#### Success Response (200)
- **task** (object) - The created task object.
```

--------------------------------

### GET /tasks/{id}

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-endpoints.md

Retrieves a specific task using its unique identifier.

```APIDOC
## GET /tasks/{id}

### Description
Get a specific task by ID.

### Method
GET

### Endpoint
/tasks/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Task ID

### Response
#### Success Response (200)
- **id** (string) - Task ID
- **content** (string) - Task content
- **project_id** (string) - Project ID
...

### Response Example
```json
{
  "id": "123",
  "content": "Buy milk",
  "project_id": "456",
  ...
}
```
```

--------------------------------

### GET /reminders

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-endpoints.md

Retrieves reminders, with an option to filter by task ID. Supports pagination.

```APIDOC
## GET /reminders

### Description
Get reminders (optionally filtered by task).

### Method
GET

### Endpoint
/reminders

### Parameters
#### Query Parameters
- task_id (string) - Optional - Filter by task
- limit (integer) - Optional - Max per page
- cursor (string) - Optional - Pagination cursor
```

--------------------------------

### add_project

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-reference/TodoistAPI.md

Creates a new project with specified details such as name, color, favorite status, view style, and parent project ID.

```APIDOC
## add_project

### Description
Create a new project.

### Method
POST

### Endpoint
/projects

### Parameters
#### Request Body
- **name** (str) - Yes - Project name (1-255 chars).
- **color** (ColorString | None) - No - Project color (one of supported colors).
- **favorite** (bool | None) - No - Whether to add to favorites.
- **view_style** (ViewStyle | None) - No - View style: "list", "board", or "calendar".
- **parent_id** (str | None) - No - Parent project ID for nested projects.

### Response
#### Success Response (200)
- **Project** (object) - The newly created project object.

### Example
```python
api = TodoistAPI("YOUR_API_TOKEN")

# Simple project
project = api.add_project("My Project")

# With color and view style
project = api.add_project(
    "Work Tasks",
    color="blue",
    view_style="board",
    favorite=True,
)

# Nested project
project = api.add_project(
    "Subproject",
    parent_id="parent_project_id",
)
```
```

--------------------------------

### Initialize and Use Async Todoist API Client

Source: https://github.com/doist/todoist-api-python/blob/main/README.md

Initialize the asynchronous API client using an async context manager. Always close the client explicitly using 'async with' or by calling 'await api.close()'.

```python
from todoist_api_python.api_async import TodoistAPIAsync

async with TodoistAPIAsync("YOUR_API_TOKEN") as api:
    task = await api.get_task("6X4Vw2Hfmg73Q2XR")
    print(task.content)
```

--------------------------------

### GET /sections

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-endpoints.md

Retrieves sections, with an option to filter by project ID. Supports pagination.

```APIDOC
## GET /sections

### Description
Get sections (optionally filtered by project).

### Method
GET

### Endpoint
/sections

### Parameters
#### Query Parameters
- **project_id** (string) - Optional - Filter by project
- **limit** (integer) - Optional - Max per page
- **cursor** (string) - Optional - Pagination cursor
```

--------------------------------

### GET /tasks

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-endpoints.md

Retrieves all active tasks, with support for various filtering and pagination options.

```APIDOC
## GET /tasks

### Description
Get all active tasks with optional filtering.

### Method
GET

### Endpoint
/tasks

### Parameters
#### Query Parameters
- **project_id** (string) - Optional - Filter by project ID
- **section_id** (string) - Optional - Filter by section ID
- **parent_id** (string) - Optional - Filter by parent task ID
- **label** (string) - Optional - Filter by label name
- **ids** (string) - Optional - Comma-separated task IDs
- **limit** (integer) - Optional - Max 200, default 50
- **cursor** (string) - Optional - Pagination cursor (internal)

### Response
#### Success Response (200)
- **results** (array) - List of task objects
- **next_cursor** (string) - Pagination cursor for the next page

### Response Example
```json
{
  "results": [
    {
      "id": "123",
      "content": "Buy milk",
      "project_id": "456",
      ...
    }
  ],
  "next_cursor": "abc123def456"
}
```
```

--------------------------------

### POST /projects

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-endpoints.md

Creates a new project. Requires a name and can optionally include color, favorite status, view style, and parent project ID.

```APIDOC
## POST /projects

### Description
Create a project.

### Method
POST

### Endpoint
/projects

### Parameters
#### Request Body
- **name** (string) - Required - Project name
- **color** (string) - Optional - Project color
- **favorite** (boolean) - Optional - Mark as favorite
- **view_style** (string) - Optional - "list", "board", or "calendar"
- **parent_id** (string) - Optional - Parent project ID
```

--------------------------------

### GET /labels/shared

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-endpoints.md

Retrieves shared labels from collaborators. Supports filtering by personal labels and pagination.

```APIDOC
## GET /labels/shared

### Description
Get shared labels from collaborators.

### Method
GET

### Endpoint
/labels/shared

### Parameters
#### Query Parameters
- omit_personal (boolean) - Optional - Exclude personal labels
- limit (integer) - Optional - Max per page
- cursor (string) - Optional - Pagination cursor
```

--------------------------------

### GET /collaborators

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-endpoints.md

Retrieves a list of collaborators associated with a project. Requires a project ID and supports pagination.

```APIDOC
## GET /collaborators

### Description
Get collaborators on a project.

### Method
GET

### Endpoint
/collaborators

### Parameters
#### Query Parameters
- **project_id** (string) - Required - Project ID (required)
- **limit** (integer) - Optional - Max per page
- **cursor** (string) - Optional - Pagination cursor
```

--------------------------------

### TodoistAPI Constructor

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-reference/TodoistAPI.md

Initializes the TodoistAPI client with an authentication token and optional configurations for request IDs and HTTP clients.

```APIDOC
## `__init__` Constructor

### Description
Initializes the TodoistAPI client. This client manages HTTP connections and handles authentication for accessing Todoist resources.

### Method
Constructor

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| token | str | Yes | — | Authentication token for the Todoist API. |
| request_id_fn | Callable[[], str] | No | default_request_id_fn | Generator function that produces request IDs for the X-Request-ID header. Pass None to disable request ID generation. |
| client | httpx.Client | No | None | Pre-configured httpx.Client instance. If not provided, a new client is created automatically. |

### Returns
None

### Raises
None

### Example
```python
from todoist_api_python.api import TodoistAPI

# Basic initialization
api = TodoistAPI("YOUR_API_TOKEN")

# With custom httpx client
import httpx
custom_client = httpx.Client(timeout=30.0)
api = TodoistAPI("YOUR_API_TOKEN", client=custom_client)

# Disable request ID generation
api = TodoistAPI("YOUR_API_TOKEN", request_id_fn=None)

# Use as context manager
with TodoistAPI("YOUR_API_TOKEN") as api:
    task = api.get_task("task_id")
```
```

--------------------------------

### GET /comments

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-endpoints.md

Retrieves a list of comments associated with a specific task or project. Supports pagination and filtering.

```APIDOC
## GET /comments

### Description
Get comments for a task or project.

### Method
GET

### Endpoint
/comments

### Parameters
#### Query Parameters
- **task_id** (string) - Required - Task ID
- **project_id** (string) - Required - Project ID
- **limit** (integer) - Optional - Max per page
- **cursor** (string) - Optional - Pagination cursor

**Note:** Either task_id or project_id is required.
```

--------------------------------

### Get a Specific Comment

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-reference/TodoistAPI-sections-comments-labels.md

Retrieve a single comment by its unique ID. This is useful for fetching details of a particular comment.

```python
api = TodoistAPI("YOUR_API_TOKEN")
comment = api.get_comment("comment_id")
print(f"Comment: {comment.content}")
```

--------------------------------

### add_task_quick

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-reference/TodoistAPI.md

Creates a new task using Todoist's Quick Add syntax, which automatically parses dates, projects, labels, and priorities from the text.

```APIDOC
## add_task_quick

### Description
Create a new task using Todoist's Quick Add syntax, which automatically parses dates, projects, labels, and priorities from the text.

### Method
POST

### Endpoint
/tasks

### Parameters
#### Request Body
- **text** (string) - Required - Task text using Quick Add syntax (e.g., "Buy milk #Shopping @groceries tomorrow p1").
- **note** (string) - Optional - Optional note to add to the task.
- **reminder** (string) - Optional - Optional reminder date in free-form text.
- **auto_reminder** (boolean) - Optional - Default: True. Add default reminder if date with time is set.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created task.
- **content** (string) - The text content of the task.
- **project_id** (string) - The ID of the project the task belongs to.
- **labels** (list[string]) - A list of labels applied to the task.
- **priority** (integer) - The priority level of the task.
- **due** (object) - Due date and time information.
- **created_at** (string) - The timestamp when the task was created.
- **url** (string) - The URL to the task in the Todoist web application.

### Error Handling
- `httpx.HTTPStatusError` — If the API request fails.
- `TypeError` — If the API response cannot be parsed.
```

--------------------------------

### Use Context Manager for Automatic Cleanup (Sync)

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/REFERENCE.md

Utilize the 'with' statement for synchronous API clients to ensure resources are properly cleaned up after use, even if errors occur.

```python
from todoist_api_python.api import TodoistAPI

# Automatic cleanup
with TodoistAPI("TOKEN") as api:
    task = api.get_task("task_id")
```

--------------------------------

### Get Comments

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/models.md

Retrieves comments associated with a specific task or project. The function returns an iterable of comment objects.

```APIDOC
## Get Comments

### Description
Retrieves comments for a given task or project.

### Method
GET (Implied by `get_comments` method)

### Endpoint
/comments (Implied by `get_comments` method)

### Parameters
#### Query Parameters
- **task_id** (str) - Optional - The ID of the task to retrieve comments for.
- **project_id** (str) - Optional - The ID of the project to retrieve comments for.

### Request Example
```python
for comments in api.get_comments(task_id="task_id"):
    for comment in comments:
        print(f"{comment.poster_id}: {comment.content}")
```

### Response
#### Success Response (200)
- **id** (str) - Unique comment identifier.
- **content** (str) - Comment text.
- **poster_id** (str) - User ID who posted the comment.
- **posted_at** (datetime) - When the comment was posted.
- **task_id** (str | None) - Task ID if commenting on a task.
- **project_id** (str | None) - Project ID if commenting on a project.
- **attachment** (Attachment | None) - Optional file attachment.
```

--------------------------------

### Context Manager Usage

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/REFERENCE.md

Demonstrates using the API client as a context manager for automatic resource cleanup, both synchronously and asynchronously.

```APIDOC
## Context Manager

### Description
Using the `TodoistAPI` and `TodoistAPIAsync` classes as context managers ensures that resources are properly cleaned up after use.

### Synchronous Context Manager
```python
from todoist_api_python.api import TodoistAPI

# Automatic cleanup
with TodoistAPI("TOKEN") as api:
    task = api.get_task("task_id")
    print(f"Retrieved task: {task.content}")
```

### Asynchronous Context Manager
```python
import asyncio
from todoist_api_python.api_async import TodoistAPIAsync

async def main():
    async with TodoistAPIAsync("TOKEN") as api:
        task = await api.get_task("task_id")
        print(f"Retrieved task: {task.content}")

asyncio.run(main())
```
```

--------------------------------

### GET /location_reminders

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-endpoints.md

Retrieves a list of location reminders. This endpoint can be filtered by a specific task ID and supports pagination.

```APIDOC
## GET /location_reminders

### Description
Get location reminders (optionally filtered by task).

### Method
GET

### Endpoint
/location_reminders

### Parameters
#### Query Parameters
- **task_id** (string) - Optional - Filter by task
- **limit** (integer) - Optional - Max per page
- **cursor** (string) - Optional - Pagination cursor
```

--------------------------------

### Async API Context Manager Usage

Source: https://github.com/doist/todoist-api-python/blob/main/_autodocs/api-reference/TodoistAPIAsync.md

Use the `async with` statement to ensure the Todoist API client is properly initialized and cleaned up.

```python
async with TodoistAPIAsync("TOKEN") as api:
    task = await api.get_task("id")
```