Metadata-Version: 2.4
Name: iceberg-subzero
Version: 0.2.1
Summary: Python client for the Subzero tokenization vault
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28.0
Provides-Extra: dev
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: respx>=0.22.0; extra == 'dev'
Description-Content-Type: text/markdown

# Subzero Python SDK

Thin Python client for the [Subzero](../subzero-api/) tokenization vault.

Configure entity types, API keys, and reveal policies in the **dashboard** first. This SDK is for server-side vault operations only.

See **[docs/vault-sdk.md](docs/vault-sdk.md)** for the full integration guide.

## Install

```bash
pip install iceberg-subzero
```

## Quick start

```python
from subzero import SubzeroClient

client = SubzeroClient(
    tokenize_key="sz_live_...",   # tokenize + search + batch
    reveal_key="sz_live_...",     # reveal
)
client.ready()

token = client.tokenize("SSN", "123-45-6789")
found = client.search("SSN", "123-45-6789")   # blind index lookup
value = client.reveal(token)
```

Or from environment variables:

```python
client = SubzeroClient.from_env()  # SUBZERO_API_KEY or split keys; SUBZERO_BASE_URL
```

A single `api_key` works when one key has both scopes (e.g. `admin`):

```python
client = SubzeroClient(api_key="sz_live_...")
```

## API key scopes

| Scope | SDK methods |
|-------|-------------|
| `tokenize` | `tokenize`, `search`, `tokenize_batch` |
| `reveal` | `reveal` (requires a matching reveal policy in the dashboard) |
| `admin` | All of the above (bypasses reveal policy) |

Use separate `tokenize_key` and `reveal_key` in production for least privilege.

## Batch tokenize

For ETL pipelines. Max **100** items per API request; the SDK auto-chunks larger lists.

```python
from subzero import TokenizeBatchItem, TokenizeBatchContext

results = client.tokenize_batch(
    [
        TokenizeBatchItem(index=0, entity_type="SSN", value="123-45-6789"),
        TokenizeBatchItem(index=1, entity_type="SSN", value="987-65-4321"),
    ],
    context=TokenizeBatchContext(source="dbt", pipeline_id="contacts"),
)

for item in results:
    if item.ok:
        print(item.index, item.token)
    else:
        print(item.index, item.error)  # per-item errors do not fail the batch
```

## Example

With the API running and keys configured in the dashboard:

```bash
export SUBZERO_TOKENIZE_API_KEY=sz_live_...
export SUBZERO_REVEAL_API_KEY=sz_live_...
python examples/vault_demo.py
```

## Tests

```bash
pytest
```

## PyPI

Local editable install only for now.
