Metadata-Version: 2.4
Name: knotaru-common
Version: 0.1.0
Summary: Shared utilities for Knotaru — JSON, type helpers, and more
Author: Knotaru
License: MIT
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Description-Content-Type: text/markdown

# knotaru-common

Shared utilities for the Knotaru platform — zero dependencies, stdlib only.

## Modules

| Module | Description |
|---|---|
| `knotaru_common.json` | Safe JSON serialisation and deserialisation |

## Installation

```bash
pip install knotaru-common
```

## Quick Start

### Safe JSON

```python
from knotaru_common.json import safe_json_dumps, safe_json_loads

# Serialise — returns None instead of raising on failure
text = safe_json_dumps({"key": "value"})          # '{"key": "value"}'
text = safe_json_dumps(object())                   # None (unserializable)
text = safe_json_dumps(object(), default="{}")     # "{}" (custom fallback)

# Deserialise — returns None instead of raising on failure
data = safe_json_loads('{"key": "value"}')         # {"key": "value"}
data = safe_json_loads("not json")                 # None (parse error)
data = safe_json_loads("not json", default={})     # {} (custom fallback)
```

## Design Principles

- **Zero mandatory dependencies** — pure stdlib, always importable
- **Never raises** — all safe_* functions catch errors and return a default
- **Typed** — full `mypy --strict` compliance with proper overloads
