Metadata-Version: 2.4
Name: datart-client
Version: 1.0.3
Summary: Datart client for Python
License: MIT
Keywords: datart,sql,query,client,pandas
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Database
Classifier: Intended Audience :: Developers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests
Requires-Dist: pandas
Requires-Dist: xlsxwriter
Provides-Extra: socks
Requires-Dist: PySocks; extra == "socks"

# datart-client

A reusable, thread-safe Python client for querying [Datart](https://github.com/running-elephant/datart).

Configuration is fully **injected via constructor arguments** — the client does not
depend on any host project's global config module, so it can be reused across projects.

## Features

- Log in to Datart and obtain a token (auto re-login on HTTP 401)
- Run SQL queries and get results as a pandas `DataFrame`, a raw `dict`, or Excel bytes
- Preconfigured data sources plus dynamic discovery of Datart data sources
- HTTP proxy and SOCKS5 proxy support
- Thread-safe (a reentrant lock guards shared state)
- A fresh `requests.Session` per request (avoids cross-thread connection-pool issues)

## Installation

```bash
pip install datart-client
```

SOCKS5 proxy support is optional:

```bash
pip install "datart-client[socks]"
```

## Quick start

```python
from datart_client import DataArtist

artist = DataArtist(
    username="your_username",
    password="your_password",
    login_url="https://your-datart-host/api/v1/users/login",
    query_url="https://your-datart-host/api/v1/data-provider/execute/test",
    # Optional: enable dynamic data-source discovery
    source_url="https://your-datart-host/api/v1/sources",
    org_id="your_org_id",
    # Optional: preconfigured data sources
    sources=[
        {"name": "example_mysql", "id": "source-id-1", "db_type": "mysql"},
        {"name": "example_oracle", "id": "source-id-2", "db_type": "oracle"},
    ],
    # Optional proxies
    http_proxies=None,   # e.g. {"http": "...", "https": "..."}
    socks5=None,         # e.g. {"ip": "127.0.0.1", "port": 1080}
)

df = artist.query("select 1", source_name="example_mysql", result_type="df")
```

## API

### `DataArtist(username, password, login_url, query_url, source_url=None, org_id=None, sources=None, http_proxies=None, socks5=None)`

Create a client. Only `username`, `password`, `login_url` and `query_url` are required;
everything else is optional.

- `source_url`, `org_id` — enable dynamic data-source discovery via `get_sources()`.
- `sources` — preconfigured data sources; accepts a list of
  `{"name", "id", "db_type"}` dicts, or a legacy `{name: id}` mapping.
- `http_proxies` — a `requests`-style proxies dict.
- `socks5` — `{"ip", "port"}`; enabling this installs a process-wide SOCKS5 proxy.

### `query(statement, source_name, size=1000000, result_type="df")`

Run a SQL statement against the named data source.

- `source_name` is resolved against preconfigured sources first, then discovered ones.
- `result_type`:
  - `"df"` — a pandas `DataFrame` (default)
  - `"raw"` — the raw response `dict`
  - `"excel"` — `.xlsx` file content as bytes

### `get_sources()`

Discover available JDBC data sources from Datart (requires `source_url` and `org_id`).
Results are cached on the instance.

## Requirements

- Python >= 3.8
- `requests`, `pandas`, `xlsxwriter`
- `PySocks` (only when using the `socks5` option; installed via the `socks` extra)

## License

MIT
