Metadata-Version: 2.4
Name: opentodo
Version: 1.0.0
Summary: A minimalist, stateful CLI todos manager with local and cloud database support.
Author: Mohammed Tahir Siddique
License: MIT
Project-URL: Homepage, https://github.com/yourusername/opentodo
Project-URL: Documentation, https://yourusername.github.io/opentodo
Project-URL: Repository, https://github.com/yourusername/opentodo.git
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: psycopg[binary]>=3.1.0
Requires-Dist: PyYAML>=6.0.1
Requires-Dist: keyring>=24.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Dynamic: license-file

# OpenTodo (otodo)

A minimalist, high-density task manager designed for engineers. 

OpenTodo operates as a stateful terminal engine and a fully featured Python SDK. It supports both local SQLite sandboxes and cloud-native PostgreSQL databases. With native YAML ingestion, you can manage your tasks exactly how you manage your infrastructure: as code.

---

## 📑 Table of Contents
1. [Installation](#-installation)
2. [CLI Quick Start](#-cli-quick-start)
3. [Python SDK Guide](#-python-sdk-guide)
4. [YAML Manifests (Tasks as Code)](#-yaml-manifests)
5. [Advanced Configuration](#-advanced-configuration)

---

## 📦 Installation

Install OpenTodo globally via pip:

```bash
pip install opentodo
```

---

## 💻 CLI Quick Start

The `otodo` CLI is designed for speed and stateful navigation.

### 1. Initialize the Engine
You must initialize your database routing before your first command.

**Local SQLite:**
```bash
otodo init
```

**Cloud PostgreSQL:**
```bash
otodo init --url "postgresql://user:password@localhost:5433/postgres"
```

### 2. Workspace Workflow
Create a list, add tasks, and view your dashboard.
```bash
otodo create "v1-release"
otodo add "Draft architecture docs" -p 10
otodo add "Configure CI/CD" -p 5
```

Type `otodo` to view your high-density table of pending tasks. The engine automatically sorts by priority.
```bash
otodo
```

### 3. Command Reference
* `otodo add <title> [-p priority]` - Add a task.
* `otodo done <id>` - Mark a task complete.
* `otodo update <id> [-t title] [-p priority]` - Update a task.
* `otodo rm <id>` - Delete a task.
* `otodo lists` - View all workspaces.
* `otodo use <list_name>` - Switch active workspace.

*(Tip: Use `otodo --help` to see all available flags and options).*

---

## 🐍 Python SDK Guide

OpenTodo's core engine can be imported directly into your own Python applications, web servers (like FastAPI), or automation scripts. 

### Initialization
Import the client and connect it to your preferred database.

```python
from opentodo.core import OpenTodo

# For local SQLite:
client = OpenTodo(output_dir="/path/to/data")

# For cloud PostgreSQL:
# client = OpenTodo(db_string="postgresql://user:pass@localhost:5433/db")
```

### Managing Lists (Workspaces)
```python
# Create a new list
client.lists.create("backend-sprint")

# Fetch all lists
all_lists = client.lists.get_all()

# Rename a list
client.lists.rename("backend-sprint", "v1-backend")
```

### Managing Tasks
```python
# Add a task to a specific list
client.todos.add(list_name="v1-backend", title="Write SDK tests", priority=8)

# Fetch pending tasks (automatically sorted by priority)
tasks = client.todos.get_by_list("v1-backend", status="pending")

# Complete a task using its true Database ID
task_id = tasks[0]["id"]
client.todos.complete(task_id)
```

### Error Handling
The SDK raises domain-specific exceptions for safe error handling.
```python
from opentodo.exceptions import ListNotFoundError, TodoNotFoundError

try:
    client.todos.complete(999)
except TodoNotFoundError as e:
    print(f"Failed: {e}")
```

---

## ⚙️ YAML Manifests

Store your standard operating procedures, sprint plans, or onboarding tasks in a YAML file and apply them idempotently via the CLI or the SDK.

**Example `sprint.yaml`:**
```yaml
version: "1.0"
lists:
  v1-release:
    - title: "Write API documentation"
      priority: 8
    - title: "Configure Dockerfile"
      priority: 5
```

**Apply via CLI:**
```bash
otodo apply sprint.yaml
```

**Apply via SDK:**
```python
results = client.manifest.apply("sprint.yaml")
print(results)
```
*Note: The apply command uses an upsert strategy. It will never overwrite existing completed tasks or duplicate existing pending tasks.*

---

## 🎛️ Advanced Configuration

### Priority Scaling (CLI)
By default, the CLI marks tasks with priority `>= 8` as **HIGH** and `>= 4` as **MED**. You can change these visual thresholds instantly:

```bash
# Set High to >= 50, and Medium to >= 20
otodo scale 50 20
```
