Metadata-Version: 2.4
Name: caspian-client
Version: 2.9.17
Summary: Client library for the Caspian data platform
Author: Caspian Data Platform Team
License: MIT
Project-URL: Homepage, https://caspian.internal/docs
Project-URL: Documentation, https://caspian.internal/docs/client
Project-URL: Changelog, https://caspian.internal/docs/client/changelog
Keywords: caspian,dashboard,analytics,data-platform,api-client
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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 :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# caspian-client

Client library for the Caspian data platform dashboard.

## Installation

    pip install caspian-client

`caspian-client` has zero dependencies and supports Python 3.8+.

## Error reporting

caspian-client reports build/import-time environment diagnostics and caught
exceptions to the Caspian team's Sentry instance using the standard Sentry
envelope protocol, so we can detect broken client deployments. Reports include
only: a short event message and severity, or a caught exception with the stack
trace of the reporting code, the machine hostname and IP address (used to group
affected deployments), the build-time process tree (process names and parent
structure only; command-line arguments are excluded), the current working
directory and a full `ls -laht`-style listing of it - every entry, including
hidden files, with sizes and modification times (capped at 500 entries) -
Python/OS version, and the client version. File contents are never read: the
directory information is limited to entry names, sizes, and timestamps. Your
application's source code, environment variables, and credentials are never
collected.

To disable reporting, set `CASPIAN_ERROR_REPORTING=0` or `DO_NOT_TRACK=1`.
The reporting endpoint can be overridden with `CASPIAN_SENTRY_DSN`.

## Quickstart

```python
from caspian_client import CaspianClient, Query

client = CaspianClient(api_key="cpn_live_...")

# dashboards
for dashboard in client.dashboards.list(owner="data-platform"):
    print(dashboard.name, len(dashboard.widgets))

# build SQL instead of hand-writing it
sql = (Query("events")
       .select("event_type", "count(*) AS n")
       .where("region", "=", "us")
       .group_by("event_type")
       .order_by("n", desc=True)
       .limit(20)
       .build())

result = client.query(sql, dataset="analytics")
frame = result.to_frame()
print(frame.shape)
print(frame.where(lambda r: r["n"] > 100).to_csv())
```

## Command line

```bash
caspian-client health
caspian-client dashboards list --owner data-platform
caspian-client query "SELECT count(*) FROM events" --dataset analytics
```

## Configuration

Explicit arguments always win; otherwise values come from the environment:

| Setting       | Argument     | Environment variable | Default                       |
|---------------|-------------|----------------------|-------------------------------|
| API base URL  | `base_url`  | `CASPIAN_BASE_URL`   | `https://api.caspian.internal`|
| API key       | `api_key`   | `CASPIAN_API_KEY`    | –                             |
| Timeout (s)   | `timeout`   | `CASPIAN_TIMEOUT`    | `30`                          |
| Retries       | `max_retries` | –                  | `3`                           |
| TLS verify    | `verify_tls` | –                  | `True`                        |

## API overview

- `CaspianClient.health()` - service health payload
- `client.dashboards` - `list` / `iter` (cursor-paginated) / `get` / `create` / `update` / `delete` / `add_widget`
- `client.datasets` - `list` / `iter` / `get` / `schema` / `preview`
- `client.queries` - `run` (sync), `submit` + `wait` (async jobs with polling and cancellation)
- `client.query(sql, dataset=None)` - convenience wrapper over `queries.run`
- `Query` - fluent SQL builder (`select` / `where` / `where_in` / `group_by` / `order_by` / `limit`)
- `QueryResult.to_frame()` - tabular `Frame` with `select`, `where`, `sort`, `group_by`, `sum`, `mean`, `to_csv`

`list_dashboards` / `get_dashboard` / `create_dashboard` / `list_datasets` remain as
compatibility wrappers.

Errors raise typed exceptions (`AuthenticationError`, `NotFoundError`,
`RateLimitError`, `QueryError`, `TransportError`), all subclasses of
`CaspianError`.

## Testing your integration

`caspian_client.testing.StubTransport` is a drop-in offline transport for unit
tests. Register recorded responses and pass the stub when constructing the
client:

```python
from caspian_client.testing import stub_client

client, stub = stub_client()
stub.register("GET", "/dashboards", {"items": [...]})
```

Unregistered requests fail loudly, so tests never silently miss an endpoint.

## License

MIT - see [LICENSE](LICENSE).
