Skip to content

Python SDK Integration

OpenTodo operates as a fully headless, stateless execution engine. By importing the OpenTodo client into your Python environment, you can build custom automation scripts, CI/CD validations, or integrate task execution directly into backend services.

1. Installation

The SDK requires the core engine and a .env parser to handle infrastructure routing securely.

pip install opentodo python-dotenv

2. Engine Initialization

The engine requires explicit database routing to prevent automated scripts from silently writing to the wrong environment.

Method A: Cloud Infrastructure (Strict Mode)

This is the recommended approach for production scripts. It instantiates a completely stateless client.

import os
from dotenv import load_dotenv
from opentodo import OpenTodo

load_dotenv()
db_string = os.getenv("DATABASE_URL")

if not db_string:
    raise ValueError("CRITICAL: DATABASE_URL environment variable is missing.")

client = OpenTodo(db_string=db_string)

Method B: Terminal State Inheritance

If you are building local extension tools, you can force the SDK to inherit the active workspace and credentials currently configured in the developer's CLI.

from opentodo import OpenTodo

client = OpenTodo(load_config=True)

3. Workspace Domain (client.lists)

This domain manages the isolated environments (lists/sprints) where tasks live.

API Reference

Method Arguments Description
create() name: str Provisions a new workspace. Raises an error if it exists.
get_all() None Returns a list of dictionary objects representing all workspaces.
rename() old_name: str, new_name: str Updates the identifier of an existing workspace.
delete() name: str [Destructive] Purges a workspace and all relational tasks.

Implementation Example

from opentodo.exceptions import ListAlreadyExistsError

try:
    client.lists.create("backend-architecture")
except ListAlreadyExistsError:
    print("Workspace already provisioned.")

workspaces = client.lists.get_all()
for ws in workspaces:
    print(ws["name"])

4. Task Domain (client.todos)

This domain handles the CRUD operations for individual tasks.

Architectural Note: The SDK strictly operates on database primary keys (id), not the temporary display_id used in the CLI dashboard.

API Reference

Method Arguments Description
add() list_name: str, title: str, priority: int Appends a task to a specific workspace.
get_by_list() list_name: str, status: str Fetches tasks. Status accepts: pending, completed, or all.
update() task_id: int, updates: dict Mutates a task. The updates dictionary accepts title and/or priority.
complete() task_id: int Marks a task as complete.
remove() task_id: int [Destructive] Deletes a specific task.

Implementation Example

# 1. Provision a task
client.todos.add(
    list_name="backend-architecture", 
    title="Design the Neon PostgreSQL schema", 
    priority=10
)

# 2. Fetch and mutate
tasks = client.todos.get_by_list("backend-architecture", status="pending")

for task in tasks:
    db_id = task['id']
    if "schema" in task['title'].lower():
        client.todos.complete(db_id)

5. Declarative Pipelines (client.manifest)

The SDK can parse and execute YAML manifests programmatically. This allows you to provision complex task environments instantly during automated testing or CI/CD deployments.

API Reference

Method Arguments Description
apply() file_path: str Parses a YAML file and idempotently creates lists and tasks.

Implementation Example

# Apply the infrastructure manifest
results = client.manifest.apply("./configs/sprint_template.yaml")

# Read the execution telemetry
for list_name, stats in results.items():
    print(f"Workspace: {list_name}")
    print(f"Status: {stats['status']}")
    print(f"Tasks Injected: {stats['tasks_added']}")