Metadata-Version: 2.4
Name: smplkit-sdk
Version: 2.10.5
Summary: Official Python SDK for the smplkit platform
Project-URL: Homepage, https://www.smplkit.com
Project-URL: Documentation, https://docs.smplkit.com
Project-URL: Repository, https://github.com/smplkit/python-sdk
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: attrs>=21.3.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: json-logic-qubit>=0.9.1
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dateutil>=2.9.0
Requires-Dist: websockets>=13.0
Provides-Extra: dev
Requires-Dist: loguru>=0.7.0; extra == 'dev'
Requires-Dist: openapi-python-client>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: loguru
Requires-Dist: loguru>=0.7.0; extra == 'loguru'
Description-Content-Type: text/markdown

# smplkit Python SDK

[![PyPI Version](https://img.shields.io/pypi/v/smplkit-sdk)](https://pypi.org/project/smplkit-sdk/) [![Build](https://github.com/smplkit/python-sdk/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/smplkit/python-sdk/actions) [![Coverage](https://codecov.io/gh/smplkit/python-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/smplkit/python-sdk) [![License](https://img.shields.io/pypi/l/smplkit-sdk)](LICENSE) [![Docs](https://img.shields.io/badge/docs-docs.smplkit.com-blue)](https://docs.smplkit.com)

The official Python SDK for [smplkit](https://www.smplkit.com) — simple application infrastructure that just works.

## Installation

```bash
pip install smplkit-sdk
```

## Requirements

- Python 3.10+

## Quick Start

```python
from smplkit import SmplClient

# Option 1: Explicit API key
client = SmplClient(api_key="sk_api_...")

# Option 2: Environment variable (SMPLKIT_API_KEY)
# export SMPLKIT_API_KEY=sk_api_...
client = SmplClient()

# Option 3: Configuration file (~/.smplkit)
# [default]
# api_key = sk_api_...
client = SmplClient()
```

```python
from smplkit import SmplClient

with SmplClient(api_key="sk_api_...") as client:
    # --- Runtime: resolve config values ---
    # Connect and read resolved key/value pairs for your service
    db = client.config.get("database")  # {"host": "...", "port": 5432}

    # --- Management: CRUD operations ---
    # List all configs
    configs = client.config.management.list()

    # Create a new config
    cfg = client.config.management.new("my_service", name="My Service")
    cfg.save()

    # Get a config by id
    cfg = client.config.management.get("my_service")

    # Delete a config
    client.config.management.delete("my_service")

    # --- Flags management ---
    flag = client.flags.management.newBooleanFlag("checkout-v2", default=False)
    flag.save()
    flags = client.flags.management.list()

    # --- Logging management ---
    logger = client.logging.management.new("sql", name="SQL Logger")
    logger.save()
```

For async usage:

```python
from smplkit import AsyncSmplClient

async with AsyncSmplClient(api_key="sk_api_...") as client:
    # Runtime
    db = await client.config.get("database")

    # Management
    cfg = await client.config.management.get("my_service")
    configs = await client.config.management.list()
```

## Configuration

All settings are resolved from three sources, in order of precedence:

1. **Constructor arguments** — highest priority, always wins.
2. **Environment variables** — e.g. `SMPLKIT_API_KEY`, `SMPLKIT_ENVIRONMENT`.
3. **Configuration file** (`~/.smplkit`) — INI-format with profile support.
4. **Defaults** — built-in SDK defaults.

### Configuration File

The `~/.smplkit` file supports a `[common]` section (applied to all profiles) and named profiles:

```ini
[common]
environment = production
service = my-app

[default]
api_key = sk_api_abc123

[local]
base_domain = localhost
scheme = http
api_key = sk_api_local_xyz
environment = development
debug = true
```

### Constructor Examples

```python
# Use a named profile
client = SmplClient(profile="local")

# Or configure explicitly
client = SmplClient(
    api_key="sk_api_...",
    environment="production",
    service="my-service",
)
```

For the complete configuration reference, see the [Configuration Guide](https://docs.smplkit.com/getting-started/configuration).

## Error Handling

All SDK errors extend `SmplError`:

```python
from smplkit import SmplError, SmplNotFoundError

try:
    config = client.config.management.get("nonexistent")
except SmplNotFoundError:
    print("Config not found")
except SmplError as e:
    print(f"SDK error: {e}")
```

| Exception              | Cause                        |
|------------------------|------------------------------|
| `SmplNotFoundError`    | Resource not found           |
| `SmplConflictError`    | Conflict (e.g., has children)|
| `SmplValidationError`  | Validation error             |
| `SmplTimeoutError`     | Request timed out            |
| `SmplConnectionError`  | Network connectivity issue   |
| `SmplError`            | Any other SDK error          |

## Debug Logging

Set `SMPLKIT_DEBUG=1` to enable verbose diagnostic output to stderr. This is useful for troubleshooting real-time level changes, WebSocket connectivity, and SDK initialization. Debug output bypasses the managed logging framework and writes directly to stderr.

```bash
SMPLKIT_DEBUG=1 python my_app.py
```

Accepted values: `1`, `true`, `yes` (case-insensitive). Any other value (or unset) disables debug output.

## Documentation

- [Getting Started](https://docs.smplkit.com/getting-started)
- [Python SDK Guide](https://docs.smplkit.com/sdks/python)
- [API Reference](https://docs.smplkit.com/api)

## License

MIT
