Metadata-Version: 2.4
Name: adept-client
Version: 0.1.0
Summary: A Python client for the Adept platform.
Author: Maxime Sünnen
Author-email: Maxime Sünnen <maxime.suennen@uni.lu>
License-Expression: MIT
License-File: LICENSE
Requires-Dist: pandas>=2.3.3
Requires-Dist: requests>=2.32.5
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# adept-client

A Python client for the [Adept](https://adept.lcsb.uni.lu) platform. Log in via your browser and load datasets straight into pandas DataFrames.

Requires Python 3.12+.

## Installation

```bash
pip install adept-client
```

or, with [uv](https://docs.astral.sh/uv/):

```bash
uv add adept-client
```

## Authentication

Creating an `AdeptClient` starts an interactive browser login (OIDC via the Adept backend). No configuration files or environment variables are needed.

```python
from adept_client import AdeptClient

client = AdeptClient()  # connects to https://adept.lcsb.uni.lu
```

1. The client prints a login URL (or opens it directly with `open_browser=True`).
2. You log in with your Adept credentials. A fresh login is always requested, even if your browser already has an active session.
3. The browser is redirected to a temporary local server on `http://127.0.0.1:8250/callback`, which completes the login. You can then close the browser tab.

Port `8250` must be free on your machine during login.

### Options

| Argument              | Default                       | Description                                                       |
|-----------------------|-------------------------------|-------------------------------------------------------------------|
| `api_base_url`        | `"https://adept.lcsb.uni.lu"` | Base URL of the Adept instance.                                   |
| `open_browser`        | `False`                       | Open the login page automatically instead of printing the URL.    |
| `ignore_https_errors` | `False`                       | Accept invalid/self-signed TLS certificates. **Development only.** |

## Usage

### List datasets and collections

```python
datasets = client.get_available_datasets()        # list[dict]
collections = client.get_available_collections()  # list[dict], nested via "children"
```

### Load a full dataset

Simple, but loads all rows into memory.

```python
df = client.get_dataset(id=42)  # pandas.DataFrame
```

### Load a dataset page by page

Recommended for large datasets. Returns a generator yielding one DataFrame per page.

```python
for page in client.get_dataset(id=42, paginate=True, rows_per_page=1000):
    ...  # process each page
```

`rows_per_page` defaults to `500`.

### Filter rows with a query

```python
df = client.get_dataset(id=42, query="<QUERY>")
```

### Log out

```python
client.logout()
```

## Logging

The client logs errors through the standard `logging` module under the `adept_client` logger:

```python
import logging

logging.basicConfig(level=logging.INFO)
```

## License

MIT. See [LICENSE](LICENSE).
