Metadata-Version: 2.4
Name: onehouse-python-sdk
Version: 0.1.0
Summary: Onehouse Python SDK — modular data-plane clients for LakeBase and beyond
Project-URL: Homepage, https://github.com/onehouseinc/onehouse-python-sdk
Project-URL: Repository, https://github.com/onehouseinc/onehouse-python-sdk
Project-URL: Issues, https://github.com/onehouseinc/onehouse-python-sdk/issues
Author-email: Onehouse Team <eng@onehouse.ai>
License: Proprietary
Keywords: auth,azure,lakebase,oauth2,oidc,onehouse,postgresql,saml
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary 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
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: lakebase
Requires-Dist: certifi>=2024.1; extra == 'lakebase'
Requires-Dist: psycopg2-binary>=2.9; extra == 'lakebase'
Description-Content-Type: text/markdown

# onehouse-python-sdk

Python SDK for connecting to [Onehouse](https://www.onehouse.ai) data-plane services.

The base package has **zero required dependencies**. Drivers ship as optional extras so you only install what you need.

```bash
pip install onehouse-python-sdk[lakebase]
```

## LakeBase

LakeBase is Onehouse's PostgreSQL-compatible managed lakehouse engine. This SDK provides a `psycopg2`-backed client that handles the browser-based and federated authentication flows LakeBase clusters require, on top of standard username/password auth.

### Installation

```bash
pip install onehouse-python-sdk[lakebase]
```

Requires Python 3.9+.

### Quickstart

```python
from onehouse_python_sdk import LakebaseClient

# Username / password
with LakebaseClient().connect(
    host="<cluster-host>",
    port=5432,
    dbname="mydb",
    user="admin",
    password="secret",
) as client:
    rows = client.fetchall("SELECT * FROM mytable WHERE id = %s", (42,))
```

### Authentication flows

| Flow | Parameters |
|------|------------|
| Username / password | `user`, `password` |
| OIDC Device Flow (Okta / Auth0) | `browser_auth=true`, `oidc_client_id`, `oidc_issuer_url`, `oidc_iam_role` |
| Azure AD OAuth2 | `browser_auth=true`, `azure_oauth_tenant_id`, `azure_oauth_client_id`, `azure_oauth_client_secret` |
| Azure Entra ID SAML | `browser_auth=true`, `azure_tenant_id`, `azure_entity_id` |
| Built-in login form | `browser_auth=true` _(default when no IdP params are set)_ |
| External redirect | `browser_auth=true`, `auth_redirect_url` |

```python
# OIDC Device Flow
client = LakebaseClient().connect(
    host="<cluster-host>",
    port=5432,
    dbname="mydb",
    browser_auth="true",
    oidc_client_id="0oaXXXXX",
    oidc_issuer_url="https://myorg.okta.com",
    oidc_iam_role="arn:aws:iam::123456789012:role/LakeBaseRole",
)

# Azure AD OAuth2
client = LakebaseClient().connect(
    host="<cluster-host>",
    port=5432,
    dbname="mydb",
    browser_auth="true",
    azure_oauth_tenant_id="your-tenant-id",
    azure_oauth_client_id="your-client-id",
    azure_oauth_client_secret="your-client-secret",
)
```

DSN string form is also supported:

```python
client = LakebaseClient().connect(
    "postgresql://<cluster-host>:5432/mydb"
    "?browser_auth=true"
    "&oidc_client_id=0oaXXXX"
    "&oidc_issuer_url=https://myorg.okta.com"
    "&oidc_iam_role=arn:aws:iam::123456789012:role/LakeBaseRole"
)
```

### Client API

All clients implement the `SqlClient` interface:

| Method | Description |
|--------|-------------|
| `connect(dsn=None, **kwargs) → self` | Establish connection, returns self for chaining |
| `execute(sql, params)` | Run a statement, return rowcount |
| `fetchall(sql, params)` | Run a query, return `list[tuple]` |
| `fetchone(sql, params)` | Run a query, return first row or `None` |
| `cursor()` | Raw cursor for advanced use |
| `raw_connection` | Underlying `psycopg2` connection |
| `close()` | Close the connection |
| `__enter__` / `__exit__` | Context manager — closes on exit |

### Notes

- **Credential caching** — auth tokens are cached for 4 minutes per connection parameters to avoid repeated browser prompts within the same process.
- **Callback port** — the local auth callback server defaults to port `8888` at path `/lakebase`. Override with `auth_callback_port` and `auth_callback_path`.
