Metadata-Version: 2.4
Name: calvery
Version: 0.3.0
Summary: Official Python SDK for Calvery Vault secret manager
Author-email: Calvery <support@calvery.xyz>
License: MIT
Project-URL: Homepage, https://calvery.xyz
Project-URL: Documentation, https://docs.calvery.xyz
Project-URL: Repository, https://github.com/RenzyArmstrong/Calvery-Vault
Project-URL: Issues, https://github.com/RenzyArmstrong/Calvery-Vault/issues
Keywords: secrets,secret-manager,calvery,vault,env,dotenv
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Security
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0

# calvery

Official Python SDK untuk [Calvery Vault](https://calvery.xyz) — secret manager untuk tim developer.

## Install

```bash
pip install calvery
```

Python 3.8+.

## Quick start

```python
import os
from calvery import Calvery

c = Calvery(token=os.environ["CVSM_TOKEN"], team="acme-corp")

# Ambil satu secret
db_url = c.get("DATABASE_URL")

# Ambil semua sebagai dict
secrets = c.get_all()

# Inject ke os.environ
c.inject()
print(os.environ["DATABASE_URL"])  # sudah terisi
```

## API

### `Calvery(token, team, **opts)`

| Arg            | Type  | Default                   | Keterangan                                          |
| -------------- | ----- | ------------------------- | --------------------------------------------------- |
| `token`        | str   | **wajib**                 | Personal Access Token (`cvsm_...`)                  |
| `team`         | str   | **wajib**                 | Team slug atau UUID                                 |
| `base_url`     | str   | `https://api.calvery.xyz` | Override untuk self-host                            |
| `environment`  | str   | `"production"`            | Default env kalau tidak di-override                 |
| `cache_ttl`    | float | `30.0`                    | Cache TTL (detik). Set `0` untuk disable            |
| `max_retries`  | int   | `3`                       | Retry 5xx + network error                           |
| `timeout`      | float | `10.0`                    | HTTP timeout per attempt                            |

### `c.get(name, *, environment=None) -> str`

```python
val = c.get("STRIPE_KEY")
staging = c.get("STRIPE_KEY", environment="staging")
```

Raise `CalverySecretNotFoundError` kalau secret tidak ada.

### `c.get_all(*, environment=None) -> dict[str, str]`

```python
for k, v in c.get_all().items():
    print(k, v)
```

### `c.inject(*, environment=None, overwrite=False) -> list[str]`

Inject semua secret ke `os.environ`. Default tidak overwrite env yang sudah ada.

### `c.clear_cache()`

Manual clear cache tanpa nunggu TTL.

## Patterns

### Django `settings.py`

```python
from calvery import Calvery

c = Calvery(token=os.environ["CVSM_TOKEN"], team="acme")
c.inject()

DATABASE_URL = os.environ["DATABASE_URL"]
SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]
```

### FastAPI startup

```python
from contextlib import asynccontextmanager
from fastapi import FastAPI
from calvery import Calvery

@asynccontextmanager
async def lifespan(app: FastAPI):
    Calvery(token=os.environ["CVSM_TOKEN"], team="acme").inject()
    yield

app = FastAPI(lifespan=lifespan)
```

### Jupyter / data science

```python
from calvery import Calvery
c = Calvery(token="cvsm_...", team="data-team", environment="staging")
db_conn_string = c.get("WAREHOUSE_URL")
```

## Error handling

```python
from calvery import Calvery, CalveryAuthError, CalverySecretNotFoundError

try:
    val = c.get("FOO")
except CalveryAuthError:
    # Token expired / revoked
    ...
except CalverySecretNotFoundError:
    # Secret belum dibuat
    ...
```

## License

MIT
