# ConfigPig — Python SDK

Python SDK for [ConfigPig](https://configpig.com), a managed config file registry for teams.

## Installation

```bash
pip install configpig
```

Or with uv:

```bash
uv add configpig
```

## Configuration

Set environment variables or pass directly to the client:

```bash
export CONFIGPIG_API_KEY="sk-api01-your-key-here"
export CONFIGPIG_URL="https://configpig.com"  # optional, this is the default
```

## Quick Start — `get_config()`

The simplest way to use ConfigPig. One function, no boilerplate:

```python
from configpig import get_config

# Fetch a config
content = get_config("my-config")

# With a specific label
content = get_config("my-config", label="production")

# With format conversion
content = get_config("my-config", output_format="yaml")

# With a fallback if the service is unreachable
content = get_config("my-config", fallback='{"default": true}')

# With TTL caching (seconds)
content = get_config("my-config", ttl=300)
```

Set global defaults so you don't repeat yourself:

```python
import configpig

configpig.configure(
    api_key="sk-api01-...",
    base_url="https://configpig.com",
    default_label="latest",
    default_ttl=300,
)
```

## Using the Full Client

For advanced use cases (creating configs, managing versions, labels, etc.):

```python
from configpig import Client

client = Client()

# List all configs
result = client.list_configs()
if result.ok:
    for cfg in result.data:
        print(f"{cfg.slug}: {cfg.name}")

# Get a specific config
result = client.get_config("my-config")
if result.ok:
    print(result.data.name)

# Fetch config content with optional format conversion
result = client.fetch("my-config", label="latest", output_format="yaml")
if result.ok:
    print(result.data.content)

# Create a new config
result = client.create_config(
    name="App Settings",
    slug="app-settings",
    content='{"debug": false, "log_level": "info"}',
    format="json",
    tags=["app"],
)

# Create a new version
result = client.create_version(
    "app-settings",
    content='{"debug": false, "log_level": "warn"}',
    change_note="Changed log level to warn",
)

# Promote a version to a label
result = client.promote("app-settings", version=2, label="production")
```

## API Reference

All methods return `APIResponse[T]` with fields:
- `ok: bool` — whether the request succeeded
- `status_code: int` — HTTP status code
- `data: T | None` — response data (when `ok` is True)
- `error: str | None` — error message (when `ok` is False)

### Configs

| Method | Description |
|---|---|
| `list_configs(tag?, search?)` | List all configs |
| `get_config(slug)` | Get config details |
| `create_config(...)` | Create a new config |
| `update_config(slug, ...)` | Update config metadata |
| `delete_config(slug)` | Delete a config |

### Versions

| Method | Description |
|---|---|
| `list_versions(slug)` | List all versions |
| `get_version(slug, version_number)` | Get specific version |
| `create_version(slug, ...)` | Create a new version |

### Fetch

| Method | Description |
|---|---|
| `fetch(slug, label?, output_format?)` | Fetch config content with optional format conversion |

### Labels

| Method | Description |
|---|---|
| `list_labels()` | List team labels |
| `create_label(name, ...)` | Create a team label |
| `delete_label(name)` | Delete a team label |
| `list_config_labels(slug)` | List labels for a config |
| `assign_label(slug, label, version)` | Assign label to version |

### Promote / Rollback

| Method | Description |
|---|---|
| `promote(slug, version, label)` | Assign label to a version |
| `rollback(slug, label)` | Rollback label to previous version |

### Exports

| Method | Description |
|---|---|
| `list_exports()` | List exports |
| `create_export(name, ...)` | Create an export |
| `get_export(export_id)` | Get export details |
| `delete_export(export_id)` | Delete an export |

### System

| Method | Description |
|---|---|
| `health_check()` | Check API health |

## License

MIT — Bright Wing Solutions LLC
