Metadata-Version: 2.4
Name: dbfy
Version: 0.1.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
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: License :: OSI Approved :: Apache Software License
Requires-Dist: pyarrow>=15.0.0
Summary: Embedded federated SQL engine for REST/JSON datasources
License: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/frhack/dbfy/blob/main/docs/quickstart.md
Project-URL: Homepage, https://github.com/frhack/dbfy
Project-URL: Issues, https://github.com/frhack/dbfy/issues
Project-URL: Repository, https://github.com/frhack/dbfy

# dbfy (Python)

Python bindings for the embedded federated SQL engine `dbfy`. Queries return PyArrow `RecordBatch` objects.

## Install

From a checkout, with maturin in a virtualenv:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install maturin pyarrow
maturin develop --release
```

## Usage

```python
import dbfy

engine = dbfy.Engine.from_yaml("""
version: 1
sources:
  crm:
    type: rest
    base_url: https://api.example.com
    tables:
      customers:
        endpoint:
          method: GET
          path: /customers
        root: "$.data[*]"
        columns:
          id:
            path: "$.id"
            type: int64
          name:
            path: "$.name"
            type: string
""")

print(engine.registered_tables())

batches = engine.query("SELECT id, name FROM crm.customers LIMIT 10")
import pyarrow as pa
table = pa.Table.from_batches(batches)
print(table.to_pandas())

print(engine.explain("SELECT id FROM crm.customers WHERE id = 1"))
```

## API

- `Engine.from_yaml(yaml: str) -> Engine` — parse and validate a YAML config.
- `Engine.from_path(path: str) -> Engine` — load a YAML config from disk.
- `Engine.registered_tables() -> list[str]` — qualified names of registered tables.
- `Engine.query(sql: str) -> list[pyarrow.RecordBatch]` — execute SQL and return Arrow batches.
- `Engine.explain(sql: str) -> str` — render the optimized plan with pushdown details.
- `DbfyError` — base exception for engine errors (config validation, REST execution, etc.).

