Metadata-Version: 2.4
Name: kanboard-sdk
Version: 1.2.0
Summary: Python SDK for the Kanboard JSON-RPC API — typed models, structured exceptions, and complete API coverage
Project-URL: Homepage, https://github.com/geekmuse/kanboard-cli
Project-URL: Repository, https://github.com/geekmuse/kanboard-cli
Project-URL: Documentation, https://github.com/geekmuse/kanboard-cli/blob/main/docs/sdk-guide.md
Project-URL: Changelog, https://github.com/geekmuse/kanboard-cli/blob/main/CHANGELOG.md
Author-email: Brad Campbell <oss-projects@bradleyscampbell.net>
License: MIT License
        
        Copyright (c) 2024 kanboard-cli contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Keywords: api,json-rpc,kanboard,project-management,sdk
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# kanboard-sdk

> Python SDK for the [Kanboard](https://kanboard.org/) JSON-RPC API — typed models, structured exceptions, and complete coverage of all 158 API methods.

[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/geekmuse/kanboard-cli/blob/main/LICENSE)
<!-- [![PyPI version](https://img.shields.io/pypi/v/kanboard-sdk.svg)](https://pypi.org/project/kanboard-sdk/) -->

## Installation

```bash
pip install kanboard-sdk
```

## Quick Start

```python
from kanboard import KanboardClient

with KanboardClient(url="https://kanboard.example.com/jsonrpc.php",
                     token="your-api-token") as kb:
    # Create a project
    project_id = kb.projects.create_project(name="My Project")

    # Create a task
    task_id = kb.tasks.create_task(
        title="Implement feature X",
        project_id=project_id,
        color_id="green",
        priority=2,
    )

    # Get all active tasks
    tasks = kb.tasks.get_all_tasks(project_id, status_id=1)
    for task in tasks:
        print(f"#{task.id} [{task.color_id}] {task.title}")
```

## Features

- **Complete API coverage** — All 158 Kanboard JSON-RPC methods across 24 resource categories
- **Typed models** — Dataclass response models with `from_api()` factory methods that handle Kanboard's type inconsistencies
- **Structured exceptions** — `KanboardAuthError`, `KanboardNotFoundError`, `KanboardAPIError`, etc. with rich context
- **Resource-based access** — `client.tasks`, `client.projects`, `client.columns`, etc.
- **Context manager** — `KanboardClient` supports `with` statements for clean resource management
- **Batch calls** — `client.batch()` for sending multiple JSON-RPC requests in one HTTP round-trip
- **Cross-project orchestration** — Portfolio management, milestones, dependency analysis, and critical-path computation via `kanboard.orchestration`
- **Minimal dependencies** — Only `httpx`

## Resource Categories

| Accessor | Methods | Description |
|---|---|---|
| `client.tasks` | 14 | Task CRUD, search, move, duplicate |
| `client.projects` | 14 | Project CRUD, enable/disable, activity |
| `client.board` | 1 | Full board view (columns → swimlanes → tasks) |
| `client.columns` | 6 | Column management and positioning |
| `client.swimlanes` | 11 | Swimlane management |
| `client.comments` | 5 | Task comments |
| `client.categories` | 5 | Project categories |
| `client.tags` | 7 | Global and project tags |
| `client.subtasks` | 5 | Subtask management |
| `client.users` | 10 | User administration |
| `client.links` | 7 | Link type definitions |
| `client.task_links` | 5 | Internal task-to-task links |
| `client.external_task_links` | 7 | External URL links on tasks |
| `client.groups` | 5 | Group management |
| `client.group_members` | 5 | Group membership |
| `client.actions` | 6 | Automatic action configuration |
| `client.project_files` | 6 | Project file attachments |
| `client.task_files` | 6 | Task file attachments |
| `client.project_metadata` | 4 | Project key-value metadata |
| `client.task_metadata` | 4 | Task key-value metadata |
| `client.project_permissions` | 9 | Project user/group permissions |
| `client.subtask_time_tracking` | 4 | Subtask time tracking |
| `client.me` | 7 | Current user (requires user auth) |
| `client.application` | 7 | Application info (version, colors, roles) |

## Exception Hierarchy

```
KanboardError (base)
├── KanboardConfigError          # Missing/invalid configuration
├── KanboardConnectionError      # Network/connection failures
├── KanboardAuthError            # HTTP 401/403, invalid credentials
├── KanboardAPIError             # JSON-RPC error responses
│   ├── KanboardNotFoundError    # Resource not found (null response)
│   └── KanboardValidationError  # Invalid parameters
└── KanboardResponseError        # Malformed/unparseable responses
```

## Configuration

`KanboardClient` accepts URL and token directly, or use `KanboardConfig.resolve()` for layered config resolution (TOML file → environment variables → explicit args):

```python
from kanboard import KanboardClient, KanboardConfig

# Direct
client = KanboardClient(url="...", token="...")

# From config file / env vars
config = KanboardConfig.resolve()
client = KanboardClient(url=config.url, token=config.token)
```

## CLI Companion

For a full command-line interface built on this SDK, install [`kanboard-cli`](https://github.com/geekmuse/kanboard-cli):

```bash
pip install kanboard-cli
```

## Documentation

- **[SDK Guide](https://github.com/geekmuse/kanboard-cli/blob/main/docs/sdk-guide.md)** — Full usage guide with examples for every resource
- **[Configuration](https://github.com/geekmuse/kanboard-cli/blob/main/docs/configuration.md)** — Config file, env vars, and profiles
- **[API Reference](https://github.com/geekmuse/kanboard-cli/blob/main/docs/plan/02-api-reference.md)** — Complete Kanboard JSON-RPC method signatures

## License

[MIT](https://github.com/geekmuse/kanboard-cli/blob/main/LICENSE)
