Metadata-Version: 2.1
Name: cube-http-client
Version: 0.3.4
Summary: Pythonic HTTP client for Cube.js REST API (sync + async)
Home-page: https://github.com/mharrisb1/cube-http-client
License: MIT
Keywords: cube.js,cube js,cube.dev,cube
Author: Michael Harris
Author-email: mharris@definite.app
Requires-Python: >=3.9,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: httpx (>=0.27.0,<0.28.0)
Requires-Dist: pydantic (>=1,<3)
Project-URL: Documentation, https://github.com/mharrisb1/cube-http-client
Project-URL: Repository, https://github.com/mharrisb1/cube-http-client
Description-Content-Type: text/markdown

# cube-http-client

Pythonic HTTP client for [Cube.dev](https://cube.dev) REST API (sync + async support)

## Installation

```sh
pip install cube-http-client
```

## Quickstart

```python
import cube_http

cube = cube_http.Client({"url": "...", "token": "..."})

# get metadata
meta = cube.v1.meta()

# load query results
results = cube.v1.load({
    "measures": ["..."],
    "dimensions": ["..."],
})

# compile to SQL
compiled_sql = cube.v1.sql({
    "measures": ["..."],
    "dimensions": ["..."],
})
```

## Support Coverage

| Endpoint                    | Description                                                                                                                                                               | Supported? |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `/v1/load`                  | Get the data for a query.                                                                                                                                                 | ✅         |
| `/v1/sql`                   | Get the SQL Code generated by Cube to be executed in the database.                                                                                                        | ✅         |
| `/v1/meta`                  | Get meta-information for cubes and views defined in the data model. Information about cubes and views with `public: false` will not be returned.                          | ✅         |
| `/v1/run-scheduled-refresh` | Trigger a scheduled refresh run to refresh pre-aggregations.                                                                                                              | ❌         |
| `/v1/pre-aggregations/jobs` | Trigger pre-aggregation build jobs or retrieve statuses of such jobs.                                                                                                     | ❌         |
| `/readyz`                   | Returns the ready state of the deployment.                                                                                                                                | ❌         |
| `/livez`                    | Returns the liveness state of the deployment. This is confirmed by testing any existing connections to dataSource. If no connections exist, it will report as successful. | ❌         |

## Usage

### Synchronous

```python
import cube_http

cube = cube_http.Client(...)
```

### Asynchronous

```python
import cube_http

cube = cube_http.AsyncClient(...)
```

### Error handling

Error classes are available for each endpoint. For example, handling an API error when calling `/v1/meta` endpoint:

```python
import cube_http
from cube_http.exc.v1 import V1MetaError

cube = cube_http.Client(...)

try:
    meta = cube.v1.meta()
except V1MetaError as e:
    print(e)
```

