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
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.
License
MIT - see LICENSE.
Metadata
Release files for caspian-client 2.9.11
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.11.tar.gz | 23.8 kB | Without provenance | Details for caspian_client-2.9.11.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| caspian_client-2.9.11-py3-none-any.whl | Python 3 | none | any | Details for caspian_client-2.9.11-py3-none-any.whl |
Total release size: 47.4 kB
Release files / caspian_client-2.9.11.tar.gz
| Download URL | caspian_client-2.9.11.tar.gz |
|---|---|
| Size | 23.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
412041dc03a4c429337bd0796266f9b525b8a59613bf4fc123dcf0a4408ebb1a
|
|
BLAKE2b-256 checksum How to use checksums |
b2d4f9c3aff8aff00c54c21fee646b89b38b33c01385e7358b8f2dbe95710909
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Release files / caspian_client-2.9.11-py3-none-any.whl
| Download URL | caspian_client-2.9.11-py3-none-any.whl |
|---|---|
| Size | 23.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
72a4416e9bda6d732ff3aa22885b3a0610d81617f1da9840155200869a2c1667
|
|
BLAKE2b-256 checksum How to use checksums |
42a3c66918e00b1def98b16a03e95d69174981f9dfc485369665f0badf800fe5
|
| 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.11
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.