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+.
Quickstart
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
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 payloadclient.dashboards-list/iter(cursor-paginated) /get/create/update/delete/add_widgetclient.datasets-list/iter/get/schema/previewclient.queries-run(sync),submit+wait(async jobs with polling and cancellation)client.query(sql, dataset=None)- convenience wrapper overqueries.runQuery- fluent SQL builder (select/where/where_in/group_by/order_by/limit)QueryResult.to_frame()- tabularFramewithselect,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:
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.
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), Python/OS version, and the client version. Your application's source code, environment variables, file contents, 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.
License
MIT - see LICENSE.
Metadata
Release files for caspian-client 2.9.10
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| caspian_client-2.9.10.tar.gz | 21.4 kB | Without provenance | Details for caspian_client-2.9.10.tar.gz |
Release files / caspian_client-2.9.10.tar.gz
| Download URL | caspian_client-2.9.10.tar.gz |
|---|---|
| Size | 21.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e81066603f00866ad601a8cd4bd0de1bc472f3275b5bec9327818ab2b3bc38e1
|
|
BLAKE2b-256 checksum How to use checksums |
d5ddc7ec0cf63fe1d0f9c6e44dd2af5d304505ab5e374d015c8eb4d471f1353b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Security for caspian-client 2.9.10
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.