ob-duckdb 0.1.0__tar.gz

ob_duckdb-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+.venv/
+venv/
+.env
+*.db
+*.duckdb
+*.sqlite3
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+*.log
+.DS_Store
+.claude/
+security/
+infra/
+site/
+scripts/
+.mcpregistry_github_token
+.mcpregistry_registry_token
+_*/
+blog/
+review*
+design/
+examples/test*

ob_duckdb-0.1.0/CLAUDE.md

@@ -0,0 +1,179 @@
+# ob-duckdb — OrionBelt Semantic Layer Driver for DuckDB
+
+## Purpose
+
+PEP 249 DB-API 2.0 driver wrapping `duckdb` that intercepts OBML YAML
+queries, compiles them to DuckDB SQL via the OrionBelt CompilationPipeline
+(direct import) or OB REST API (standalone), and executes them natively.
+
+**OB dialect string:** `"duckdb"`
+**Author:** Ralf Becher / RALFORION d.o.o. (info@orionbelt.ai)
+**License:** Apache 2.0
+
+---
+
+## Why DuckDB is Special
+
+DuckDB is unique among the OB-supported vendors in two ways:
+
+1. **In-process** — DuckDB runs embedded in the same Python process, no
+   server required. This makes it the ideal driver for local development,
+   testing, and notebook use without any infrastructure.
+
+2. **Already has a DB-API 2.0 interface** — `duckdb.connect()` returns a
+   PEP 249-compliant connection directly. This driver is a thin OBML-aware
+   wrapper, not a full reimplementation.
+
+DuckDB is also the recommended backend for **testing all other OB drivers**
+— load a Parquet or CSV file into DuckDB, point the OB model at it, compile
+with dialect="duckdb", and validate query output without needing Snowflake
+or Postgres credentials.
+
+---
+
+## Module Map
+
+| File | Responsibility |
+|---|---|
+| `__init__.py` | PEP 249 connect() + module constants |
+| `connection.py` | Connection class wrapping duckdb.DuckDBPyConnection |
+| `cursor.py` | Cursor class — OBML detection + execution |
+| `compiler.py` | Direct OB import or REST fallback (shared pattern) |
+| `exceptions.py` | PEP 249 exception hierarchy |
+| `type_codes.py` | PEP 249 type objects |
+
+---
+
+## connect() Parameters
+
+### DuckDB-specific
+| Parameter | Type | Description |
+|---|---|---|
+| database | str | Path to .duckdb file, or `:memory:` (default) |
+| read_only | bool | Open in read-only mode (default: False) |
+| config | dict | DuckDB config options (threads, memory_limit, etc.) |
+
+### OrionBelt parameters (same across all vendors)
+| Parameter | Default | Description |
+|---|---|---|
+| ob_model_id | None | Pre-loaded OB model ID |
+| ob_model_yaml | None | OBML YAML string to load |
+| ob_model_file | None | Path to .obml.yaml file |
+| ob_api_url | http://localhost:8000 | OB REST API URL (standalone mode only) |
+| ob_timeout | 30 | HTTP timeout in seconds |
+
+---
+
+## Key DuckDB-Specific Notes
+
+- `duckdb.connect()` default is `:memory:` — in-memory database, ideal for
+  testing and local development with Parquet/CSV sources
+- DuckDB supports reading Parquet, CSV, JSON directly in SQL:
+  `SELECT * FROM 'data.parquet'` — OBML models can reference these as
+  data objects with `code: 'path/to/file.parquet'`
+- No server process — commit() and rollback() are supported but DuckDB
+  auto-commits by default in most contexts
+- DuckDB's DB-API cursor `.description` uses duckdb type names (VARCHAR,
+  INTEGER, DOUBLE, TIMESTAMP, etc.) — map to PEP 249 type codes accordingly
+- DuckDB is the best choice for the `ob_model_file` pattern: load a model
+  pointing at local Parquet files, query with OBML, zero infrastructure
+- Thread safety: DuckDB connections are NOT thread-safe by default.
+  Use `duckdb.connect(database, check_same_thread=False)` for multi-threaded
+  use, or create one connection per thread.
+- DuckDB dialect in OB generates standard ANSI SQL with DuckDB extensions
+  for time grains: `DATE_TRUNC('month', col)`, `EXTRACT(year FROM col)`
+
+---
+
+## Ideal Use Cases
+
+1. **Local development & testing** — validate OBML models against sample
+   data without any cloud credentials
+2. **CI/CD pipelines** — unit test semantic models with DuckDB + Parquet
+   fixtures, fast and dependency-free
+3. **Notebooks / data science** — OBML queries against local files in Jupyter
+4. **ob-flight-extension testing** — spin up a Flight SQL server backed by
+   DuckDB for end-to-end driver testing without cloud access
+
+---
+
+## Example Usage
+
+```python
+import ob_duckdb
+
+# In-memory with local Parquet files
+conn = ob_duckdb.connect(
+    database=":memory:",
+    ob_model_file="orionbelt_1_model.obml.yaml",
+)
+
+with conn.cursor() as cur:
+    cur.execute("""
+select:
+  dimensions:
+    - Region
+  measures:
+    - Revenue
+limit: 10
+""")
+    print(cur.fetchall())
+```
+
+---
+
+## Compiler Bridge
+
+Same auto-detect pattern as all other vendor drivers:
+
+```python
+def compile_obml(obml, *, model, dialect="duckdb", **kwargs) -> str:
+    try:
+        from orionbelt.compiler.pipeline import CompilationPipeline
+        return CompilationPipeline().compile(obml, model, "duckdb").sql
+    except ImportError:
+        return _compile_rest(obml, dialect="duckdb", **kwargs)
+```
+
+---
+
+## Type Mapping
+
+| DuckDB type | PEP 249 type code |
+|---|---|
+| INTEGER, BIGINT, HUGEINT | NUMBER |
+| FLOAT, DOUBLE, DECIMAL | NUMBER |
+| VARCHAR, TEXT | STRING |
+| BOOLEAN | STRING |
+| DATE | DATETIME |
+| TIMESTAMP, TIMESTAMPTZ | DATETIME |
+| BLOB | BINARY |
+| LIST, STRUCT, MAP | STRING (JSON repr) |
+
+---
+
+## Build Order
+
+Session 1: exceptions.py + type_codes.py + compiler.py + unit tests
+Session 2: connection.py + cursor.py (thin wrapper over duckdb native)
+Session 3: __init__.py + connect() + integration tests with :memory: DB
+Session 4: SQLAlchemy dialect (ob+duckdb:// URL scheme)
+
+---
+
+## Dependencies
+
+```toml
+[project.dependencies]
+duckdb = ">=1.0"
+pyyaml = ">=6.0"
+httpx = ">=0.27"
+
+[project.optional-dependencies]
+sqlalchemy = ["sqlalchemy>=2.0"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "mypy>=1.10", "ruff>=0.4"]
+```
+
+Note: no `respx` needed for unit tests — DuckDB in-memory means integration
+tests run without any external service, so the unit/integration distinction
+is less relevant than for other vendors.

ob_duckdb-0.1.0/LICENSE

@@ -0,0 +1,70 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             RALFORION d.o.o.
+Licensed Work:        OrionBelt Semantic Layer 1.0
+                      The Licensed Work is (c) 2025 RALFORION d.o.o.
+Additional Use Grant: You may use the Licensed Work for any purpose,
+                      including production use, PROVIDED THAT you may
+                      not embed OrionBelt in a commercial product or
+                      provide it as part of a commercial service
+                      without purchasing a commercial license from
+                      the Licensor. Contact licensing@ralforion.com
+                      for commercial licensing inquiries.
+Change Date:          2030-03-16
+Change License:       Apache License, Version 2.0
+
+-----------------------------------------------------------------------------
+
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor of MariaDB's Business Source
+License Trademark Policy available at https://mariadb.com/bsl11/.

ob_duckdb-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: ob-duckdb
+Version: 0.1.0
+Summary: OrionBelt Semantic Layer driver for DuckDB (DB-API 2.0)
+Author-email: Ralf Becher <info@orionbelt.ai>
+License: BSL-1.1
+License-File: LICENSE
+Keywords: db-api,duckdb,obml,orionbelt,semantic-layer
+Requires-Python: >=3.12
+Requires-Dist: duckdb>=1.0
+Requires-Dist: ob-driver-core>=0.1
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy>=2.0; extra == 'sqlalchemy'
+Description-Content-Type: text/markdown
+
+# ob-duckdb
+
+OrionBelt Semantic Layer driver for DuckDB (DB-API 2.0)
+
+Part of the [OrionBelt Semantic Layer](https://github.com/ralfbecher/orionbelt-semantic-layer) project.
+
+## Installation
+
+```bash
+pip install ob-duckdb
+```
+
+## License
+
+BSL-1.1 — see [LICENSE](LICENSE) for details.

ob_duckdb-0.1.0/README.md

@@ -0,0 +1,15 @@
+# ob-duckdb
+
+OrionBelt Semantic Layer driver for DuckDB (DB-API 2.0)
+
+Part of the [OrionBelt Semantic Layer](https://github.com/ralfbecher/orionbelt-semantic-layer) project.
+
+## Installation
+
+```bash
+pip install ob-duckdb
+```
+
+## License
+
+BSL-1.1 — see [LICENSE](LICENSE) for details.

ob_duckdb-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ob-duckdb"
+version = "0.1.0"
+description = "OrionBelt Semantic Layer driver for DuckDB (DB-API 2.0)"
+license = { text = "BSL-1.1" }
+readme = "README.md"
+authors = [{ name = "Ralf Becher", email = "info@orionbelt.ai" }]
+keywords = ["duckdb", "semantic-layer", "obml", "db-api", "orionbelt"]
+requires-python = ">=3.12"
+dependencies = [
+    "ob-driver-core>=0.1",
+    "duckdb>=1.0",
+]
+
+[project.optional-dependencies]
+sqlalchemy = ["sqlalchemy>=2.0"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "mypy>=1.10",
+    "ruff>=0.4",
+]
+
+[project.entry-points."sqlalchemy.dialects"]
+"ob.duckdb" = "ob_duckdb.dialect:OBDuckDBDialect"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ob_duckdb"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "ANN"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src/ob_duckdb"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+# Note: no integration marker needed — DuckDB :memory: runs anywhere

ob_duckdb-0.1.0/src/ob_duckdb/__init__.py

@@ -0,0 +1,90 @@
+"""ob-duckdb — OrionBelt Semantic Layer driver for DuckDB (PEP 249 DB-API 2.0).
+
+Requires the OrionBelt REST API running in single-model mode (MODEL_FILE set).
+OBML queries are compiled to SQL via ``POST /v1/query/sql``.
+
+Usage::
+
+    import ob_duckdb
+
+    conn = ob_duckdb.connect(database=":memory:")
+    with conn.cursor() as cur:
+        cur.execute("select:\\n  dimensions:\\n    - Region\\n  measures:\\n    - Revenue")
+        print(cur.fetchall())
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import duckdb
+
+from ob_duckdb.connection import Connection
+from ob_duckdb.exceptions import (
+    DataError,
+    DatabaseError,
+    Error,
+    IntegrityError,
+    InterfaceError,
+    InternalError,
+    NotSupportedError,
+    OperationalError,
+    ProgrammingError,
+    Warning,
+)
+
+# PEP 249 module-level constants
+apilevel = "2.0"
+threadsafety = 1  # threads may share the module but not connections
+paramstyle = "qmark"  # DuckDB uses ? placeholders
+
+
+def connect(
+    database: str = ":memory:",
+    *,
+    read_only: bool = False,
+    config: dict[str, Any] | None = None,
+    # OrionBelt parameters
+    ob_api_url: str = "http://localhost:8000",
+    ob_timeout: int = 30,
+) -> Connection:
+    """Open a DuckDB connection with OBML support.
+
+    Parameters
+    ----------
+    database : str
+        Path to ``.duckdb`` file or ``":memory:"`` (default).
+    read_only : bool
+        Open in read-only mode.
+    config : dict
+        DuckDB configuration options (threads, memory_limit, etc.).
+    ob_api_url : str
+        OrionBelt REST API URL (must be running in single-model mode).
+    ob_timeout : int
+        HTTP timeout in seconds for OBML compilation.
+    """
+    native = duckdb.connect(database=database, read_only=read_only, config=config or {})
+    return Connection(
+        native,
+        ob_api_url=ob_api_url,
+        ob_timeout=ob_timeout,
+    )
+
+
+__all__ = [
+    "apilevel",
+    "threadsafety",
+    "paramstyle",
+    "connect",
+    "Connection",
+    "Warning",
+    "Error",
+    "InterfaceError",
+    "DatabaseError",
+    "DataError",
+    "OperationalError",
+    "IntegrityError",
+    "InternalError",
+    "ProgrammingError",
+    "NotSupportedError",
+]

ob_duckdb-0.1.0/src/ob_duckdb/compiler.py

@@ -0,0 +1,8 @@
+"""OrionBelt compilation bridge — delegates to ob-driver-core."""
+
+from __future__ import annotations
+
+from ob_driver_core.compiler import compile_obml
+from ob_driver_core.detection import is_obml, parse_obml
+
+__all__ = ["compile_obml", "is_obml", "parse_obml"]

ob_duckdb-0.1.0/src/ob_duckdb/connection.py

@@ -0,0 +1,70 @@
+"""PEP 249 Connection wrapping ``duckdb.DuckDBPyConnection``."""
+
+from __future__ import annotations
+
+import duckdb
+
+from ob_duckdb.cursor import Cursor
+from ob_duckdb.exceptions import ProgrammingError
+
+
+class Connection:
+    """DB-API 2.0 connection that wraps a native DuckDB connection.
+
+    OBML queries are compiled to SQL via the OrionBelt REST API
+    (single-model mode, ``/v1/query/sql`` shortcut).
+    """
+
+    def __init__(
+        self,
+        native: duckdb.DuckDBPyConnection,
+        *,
+        ob_api_url: str = "http://localhost:8000",
+        ob_timeout: int = 30,
+    ) -> None:
+        self._native = native
+        self._closed = False
+        self._ob_api_url = ob_api_url
+        self._ob_timeout = ob_timeout
+
+    def _check_open(self) -> None:
+        if self._closed:
+            raise ProgrammingError("Connection is closed.")
+
+    def cursor(self) -> Cursor:
+        """Return a new Cursor for this connection."""
+        self._check_open()
+        native_cursor = self._native.cursor()
+        return Cursor(
+            native_cursor,
+            ob_api_url=self._ob_api_url,
+            ob_timeout=self._ob_timeout,
+        )
+
+    def commit(self) -> None:
+        """Commit — DuckDB auto-commits by default, so this is usually a no-op."""
+        self._check_open()
+        self._native.commit()
+
+    def rollback(self) -> None:
+        """Rollback the current transaction.
+
+        No-op if no transaction is active (DuckDB auto-commits by default).
+        """
+        self._check_open()
+        try:
+            self._native.rollback()
+        except duckdb.TransactionException:
+            pass  # no active transaction — nothing to roll back
+
+    def close(self) -> None:
+        """Close the connection."""
+        if not self._closed:
+            self._native.close()
+            self._closed = True
+
+    def __enter__(self) -> Connection:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

ob_duckdb-0.1.0/src/ob_duckdb/cursor.py

@@ -0,0 +1,163 @@
+"""PEP 249 Cursor with OBML interception for DuckDB."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import duckdb
+
+from ob_duckdb.compiler import compile_obml, is_obml, parse_obml
+from ob_duckdb.exceptions import NotSupportedError, ProgrammingError
+from ob_duckdb.type_codes import DUCKDB_TYPE_MAP, STRING
+
+
+class Cursor:
+    """DB-API 2.0 cursor that intercepts OBML YAML queries.
+
+    If the query is OBML, it is compiled to DuckDB SQL via the OrionBelt
+    REST API before execution. Plain SQL is passed through unchanged.
+    """
+
+    arraysize: int = 1
+
+    def __init__(
+        self,
+        native: duckdb.DuckDBPyConnection,
+        *,
+        ob_api_url: str = "http://localhost:8000",
+        ob_timeout: int = 30,
+    ) -> None:
+        self._native = native
+        self._closed = False
+        self._ob_api_url = ob_api_url
+        self._ob_timeout = ob_timeout
+        self._description: tuple[tuple[str, Any, None, None, None, None, None], ...] | None = None
+        self._rowcount: int = -1
+
+    @property
+    def description(
+        self,
+    ) -> tuple[tuple[str, Any, None, None, None, None, None], ...] | None:
+        """PEP 249 cursor description — 7-item tuples per column."""
+        return self._description
+
+    @property
+    def rowcount(self) -> int:
+        return self._rowcount
+
+    def _check_open(self) -> None:
+        if self._closed:
+            raise ProgrammingError("Cursor is closed.")
+
+    def _build_description(self) -> None:
+        """Build PEP 249 description from native cursor."""
+        native_desc = self._native.description
+        if native_desc is None:
+            self._description = None
+            return
+        cols: list[tuple[str, Any, None, None, None, None, None]] = []
+        for col in native_desc:
+            name = col[0]
+            raw_type = col[1] if len(col) > 1 else None
+            type_code = STRING  # default
+            # DuckDB returns DuckDBPyType objects — convert to string for lookup
+            type_str = str(raw_type).upper() if raw_type is not None else ""
+            type_code = DUCKDB_TYPE_MAP.get(type_str, STRING)
+            cols.append((name, type_code, None, None, None, None, None))
+        self._description = tuple(cols)
+
+    def execute(self, operation: str, parameters: Any = None) -> Cursor:
+        """Execute a query — OBML YAML or plain SQL."""
+        self._check_open()
+        sql = self._resolve_sql(operation)
+        if parameters is not None:
+            self._native.execute(sql, parameters)
+        else:
+            self._native.execute(sql)
+        self._build_description()
+        self._rowcount = -1
+        return self
+
+    def executemany(self, operation: str, seq_of_parameters: Any) -> None:
+        """Execute against all parameter sequences.
+
+        OBML queries are not supported with executemany — raises NotSupportedError.
+        """
+        self._check_open()
+        if is_obml(operation):
+            raise NotSupportedError("executemany() is not supported for OBML queries.")
+        self._native.executemany(operation, seq_of_parameters)
+        self._build_description()
+
+    def _resolve_sql(self, operation: str) -> str:
+        """Compile OBML to SQL or return plain SQL unchanged."""
+        if not is_obml(operation):
+            return operation
+        obml = parse_obml(operation)
+        return compile_obml(
+            obml,
+            dialect="duckdb",
+            ob_api_url=self._ob_api_url,
+            ob_timeout=self._ob_timeout,
+        )
+
+    def fetchone(self) -> tuple[Any, ...] | None:
+        """Fetch the next row."""
+        self._check_open()
+        row = self._native.fetchone()
+        return tuple(row) if row is not None else None
+
+    def fetchmany(self, size: int | None = None) -> list[tuple[Any, ...]]:
+        """Fetch the next *size* rows."""
+        self._check_open()
+        n = size if size is not None else self.arraysize
+        rows = self._native.fetchmany(n)
+        return [tuple(r) for r in rows]
+
+    def fetchall(self) -> list[tuple[Any, ...]]:
+        """Fetch all remaining rows."""
+        self._check_open()
+        rows = self._native.fetchall()
+        return [tuple(r) for r in rows]
+
+    def fetch_arrow_table(self) -> Any:
+        """Fetch all remaining rows as a PyArrow Table (zero-copy from DuckDB).
+
+        Returns a ``pyarrow.Table``.  This avoids materialising intermediate
+        Python row objects and is significantly more memory-efficient for
+        large result sets.
+        """
+        self._check_open()
+        return self._native.fetch_arrow_table()
+
+    def close(self) -> None:
+        """Close the cursor."""
+        if not self._closed:
+            self._native.close()
+            self._closed = True
+
+    def setinputsizes(self, sizes: Any) -> None:
+        """No-op — required by PEP 249."""
+
+    def setoutputsize(self, size: int, column: int | None = None) -> None:
+        """No-op — required by PEP 249."""
+
+    @property
+    def lastrowid(self) -> None:
+        """DuckDB does not support lastrowid."""
+        return None
+
+    def __enter__(self) -> Cursor:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def __iter__(self) -> Cursor:
+        return self
+
+    def __next__(self) -> tuple[Any, ...]:
+        row = self.fetchone()
+        if row is None:
+            raise StopIteration
+        return row

ob_duckdb-0.1.0/src/ob_duckdb/exceptions.py

@@ -0,0 +1,32 @@
+"""PEP 249 exceptions — re-exported from ob-driver-core for convenience.
+
+Allows users to do: ``from ob_duckdb.exceptions import ProgrammingError``
+"""
+
+from __future__ import annotations
+
+from ob_driver_core.exceptions import (
+    DataError,
+    DatabaseError,
+    Error,
+    IntegrityError,
+    InterfaceError,
+    InternalError,
+    NotSupportedError,
+    OperationalError,
+    ProgrammingError,
+    Warning,
+)
+
+__all__ = [
+    "Warning",
+    "Error",
+    "InterfaceError",
+    "DatabaseError",
+    "DataError",
+    "OperationalError",
+    "IntegrityError",
+    "InternalError",
+    "ProgrammingError",
+    "NotSupportedError",
+]

ob_duckdb-0.1.0/src/ob_duckdb/type_codes.py

@@ -0,0 +1,45 @@
+"""PEP 249 type objects — re-exported from ob-driver-core plus DuckDB mapping.
+
+DuckDB cursor.description uses uppercase type names like 'VARCHAR', 'INTEGER', etc.
+The DUCKDB_TYPE_MAP maps these to PEP 249 type objects.
+"""
+
+from __future__ import annotations
+
+from ob_driver_core.type_codes import BINARY, DATETIME, NUMBER, ROWID, STRING
+
+__all__ = ["STRING", "BINARY", "NUMBER", "DATETIME", "ROWID", "DUCKDB_TYPE_MAP"]
+
+DUCKDB_TYPE_MAP: dict[str, object] = {
+    # String types
+    "VARCHAR": STRING,
+    "TEXT": STRING,
+    "CHAR": STRING,
+    "BOOLEAN": STRING,
+    "UUID": STRING,
+    "ENUM": STRING,
+    # Numeric types
+    "TINYINT": NUMBER,
+    "SMALLINT": NUMBER,
+    "INTEGER": NUMBER,
+    "BIGINT": NUMBER,
+    "HUGEINT": NUMBER,
+    "UTINYINT": NUMBER,
+    "USMALLINT": NUMBER,
+    "UINTEGER": NUMBER,
+    "UBIGINT": NUMBER,
+    "FLOAT": NUMBER,
+    "DOUBLE": NUMBER,
+    "DECIMAL": NUMBER,
+    # Date/time types
+    "DATE": DATETIME,
+    "TIME": DATETIME,
+    "TIMESTAMP": DATETIME,
+    "TIMESTAMP WITH TIME ZONE": DATETIME,
+    "TIMESTAMP_S": DATETIME,
+    "TIMESTAMP_MS": DATETIME,
+    "TIMESTAMP_NS": DATETIME,
+    "INTERVAL": DATETIME,
+    # Binary types
+    "BLOB": BINARY,
+}

ob_duckdb-0.1.0/tests/test_driver.py

@@ -0,0 +1,333 @@
+"""Unit tests for the ob-duckdb DB-API 2.0 driver.
+
+Plain SQL tests run against DuckDB :memory: — no external services needed.
+OBML tests mock the REST API call to ``/v1/query/sql``.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+import ob_duckdb
+from ob_duckdb.connection import Connection
+from ob_duckdb.exceptions import NotSupportedError, ProgrammingError
+from ob_duckdb.type_codes import DATETIME, NUMBER, STRING
+
+
+# ---------------------------------------------------------------------------
+# PEP 249 module-level constants
+# ---------------------------------------------------------------------------
+
+
+def test_apilevel() -> None:
+    assert ob_duckdb.apilevel == "2.0"
+
+
+def test_threadsafety() -> None:
+    assert ob_duckdb.threadsafety == 1
+
+
+def test_paramstyle() -> None:
+    assert ob_duckdb.paramstyle == "qmark"
+
+
+# ---------------------------------------------------------------------------
+# connect()
+# ---------------------------------------------------------------------------
+
+
+def test_connect_returns_connection() -> None:
+    conn = ob_duckdb.connect()
+    assert isinstance(conn, Connection)
+    conn.close()
+
+
+def test_connect_memory_default() -> None:
+    conn = ob_duckdb.connect()
+    with conn.cursor() as cur:
+        cur.execute("SELECT 42 AS answer")
+        assert cur.fetchone() == (42,)
+    conn.close()
+
+
+def test_connect_context_manager() -> None:
+    with ob_duckdb.connect() as conn:
+        with conn.cursor() as cur:
+            cur.execute("SELECT 1")
+            assert cur.fetchone() == (1,)
+
+
+# ---------------------------------------------------------------------------
+# Connection
+# ---------------------------------------------------------------------------
+
+
+def test_connection_close_is_idempotent() -> None:
+    conn = ob_duckdb.connect()
+    conn.close()
+    conn.close()  # should not raise
+
+
+def test_connection_cursor_after_close_raises() -> None:
+    conn = ob_duckdb.connect()
+    conn.close()
+    with pytest.raises(ProgrammingError, match="closed"):
+        conn.cursor()
+
+
+def test_connection_commit() -> None:
+    conn = ob_duckdb.connect()
+    conn.commit()  # should not raise
+    conn.close()
+
+
+def test_connection_rollback() -> None:
+    conn = ob_duckdb.connect()
+    conn.rollback()  # should not raise
+    conn.close()
+
+
+# ---------------------------------------------------------------------------
+# Cursor — plain SQL
+# ---------------------------------------------------------------------------
+
+
+def test_cursor_execute_select() -> None:
+    with ob_duckdb.connect() as conn:
+        with conn.cursor() as cur:
+            cur.execute("SELECT 1 AS a, 'hello' AS b, CAST(3.14 AS DOUBLE) AS c")
+            row = cur.fetchone()
+            assert row == (1, "hello", 3.14)
+
+
+def test_cursor_description() -> None:
+    with ob_duckdb.connect() as conn:
+        with conn.cursor() as cur:
+            cur.execute("SELECT 1 AS num, 'txt' AS str, CURRENT_DATE AS dt")
+            desc = cur.description
+            assert desc is not None
+            assert len(desc) == 3
+            # Each entry is a 7-tuple
+            assert all(len(col) == 7 for col in desc)
+            # Column names
+            assert desc[0][0] == "num"
+            assert desc[1][0] == "str"
+            assert desc[2][0] == "dt"
+
+
+def test_cursor_description_type_codes() -> None:
+    with ob_duckdb.connect() as conn:
+        with conn.cursor() as cur:
+            cur.execute(
+                "SELECT "
+                "CAST(1 AS INTEGER) AS i, "
+                "CAST('x' AS VARCHAR) AS v, "
+                "CAST('2024-01-01' AS DATE) AS d, "
+                "CAST(1.5 AS DOUBLE) AS f"
+            )
+            desc = cur.description
+            assert desc is not None
+            assert desc[0][1] == NUMBER
+            assert desc[1][1] == STRING
+            assert desc[2][1] == DATETIME
+            assert desc[3][1] == NUMBER
+
+
+def test_cursor_fetchall() -> None:
+    with ob_duckdb.connect() as conn:
+        with conn.cursor() as cur:
+            cur.execute("SELECT * FROM (VALUES (1, 'a'), (2, 'b'), (3, 'c')) AS t(id, name)")
+            rows = cur.fetchall()
+            assert len(rows) == 3
+            assert rows[0] == (1, "a")
+            assert rows[2] == (3, "c")
+
+
+def test_cursor_fetchmany() -> None:
+    with ob_duckdb.connect() as conn:
+        with conn.cursor() as cur:
+            cur.execute("SELECT * FROM range(10) AS t(n)")
+            batch = cur.fetchmany(3)
+            assert len(batch) == 3
+            rest = cur.fetchall()
+            assert len(rest) == 7
+
+
+def test_cursor_fetchone_exhausted() -> None:
+    with ob_duckdb.connect() as conn:
+        with conn.cursor() as cur:
+            cur.execute("SELECT 1")
+            assert cur.fetchone() is not None
+            assert cur.fetchone() is None
+
+
+def test_cursor_iteration() -> None:
+    with ob_duckdb.connect() as conn:
+        with conn.cursor() as cur:
+            cur.execute("SELECT * FROM range(5) AS t(n)")
+            rows = list(cur)
+            assert len(rows) == 5
+            assert rows[0] == (0,)
+
+
+def test_cursor_execute_returns_self() -> None:
+    with ob_duckdb.connect() as conn:
+        with conn.cursor() as cur:
+            result = cur.execute("SELECT 1")
+            assert result is cur
+
+
+def test_cursor_close_then_fetch_raises() -> None:
+    with ob_duckdb.connect() as conn:
+        cur = conn.cursor()
+        cur.execute("SELECT 1")
+        cur.close()
+        with pytest.raises(ProgrammingError, match="closed"):
+            cur.fetchone()
+
+
+def test_cursor_executemany_plain_sql() -> None:
+    with ob_duckdb.connect() as conn:
+        with conn.cursor() as cur:
+            cur.execute("CREATE TABLE t (id INTEGER, name VARCHAR)")
+            cur.executemany("INSERT INTO t VALUES (?, ?)", [(1, "a"), (2, "b")])
+            cur.execute("SELECT COUNT(*) FROM t")
+            assert cur.fetchone() == (2,)
+
+
+def test_cursor_executemany_obml_raises() -> None:
+    with ob_duckdb.connect() as conn:
+        with conn.cursor() as cur:
+            obml = "select:\n  dimensions:\n    - Region\n  measures:\n    - Revenue\n"
+            with pytest.raises(NotSupportedError, match="executemany"):
+                cur.executemany(obml, [])
+
+
+def test_cursor_setinputsizes_noop() -> None:
+    with ob_duckdb.connect() as conn:
+        with conn.cursor() as cur:
+            cur.setinputsizes([])  # should not raise
+
+
+def test_cursor_setoutputsize_noop() -> None:
+    with ob_duckdb.connect() as conn:
+        with conn.cursor() as cur:
+            cur.setoutputsize(1000)  # should not raise
+
+
+def test_cursor_lastrowid_is_none() -> None:
+    with ob_duckdb.connect() as conn:
+        with conn.cursor() as cur:
+            assert cur.lastrowid is None
+
+
+def test_cursor_with_parameters() -> None:
+    with ob_duckdb.connect() as conn:
+        with conn.cursor() as cur:
+            cur.execute("SELECT ? + ? AS result", [3, 4])
+            assert cur.fetchone() == (7,)
+
+
+# ---------------------------------------------------------------------------
+# Cursor — OBML queries (mocked REST API)
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def duckdb_conn_with_data() -> Connection:
+    """DuckDB connection with sample data (no model — OBML goes via REST)."""
+    conn = ob_duckdb.connect()
+    with conn.cursor() as cur:
+        cur.execute("""
+            CREATE TABLE orders (
+                order_id VARCHAR,
+                region VARCHAR,
+                amount DOUBLE
+            )
+        """)
+        cur.execute("""
+            INSERT INTO orders VALUES
+                ('O1', 'EMEA', 100.0),
+                ('O2', 'EMEA', 200.0),
+                ('O3', 'APAC', 150.0),
+                ('O4', 'AMER', 300.0),
+                ('O5', 'AMER', 250.0)
+        """)
+    return conn
+
+
+def _mock_api_response(sql: str) -> MagicMock:
+    """Create a mock httpx response returning the given SQL."""
+    resp = MagicMock()
+    resp.is_success = True
+    resp.json.return_value = {"sql": sql}
+    return resp
+
+
+def test_obml_compile_and_execute(duckdb_conn_with_data: Connection) -> None:
+    """Full round-trip: OBML → REST compile → execute on DuckDB."""
+    compiled_sql = "SELECT region, SUM(amount) AS revenue FROM orders GROUP BY region"
+    with patch("httpx.post", return_value=_mock_api_response(compiled_sql)):
+        with duckdb_conn_with_data.cursor() as cur:
+            cur.execute("select:\n  dimensions:\n    - Region\n  measures:\n    - Revenue\n")
+            rows = cur.fetchall()
+            assert len(rows) == 3
+            desc = cur.description
+            assert desc is not None
+            assert len(desc) == 2
+
+
+def test_obml_measures_only(duckdb_conn_with_data: Connection) -> None:
+    """OBML with measures only (no dimensions)."""
+    compiled_sql = "SELECT SUM(amount) AS revenue FROM orders"
+    with patch("httpx.post", return_value=_mock_api_response(compiled_sql)):
+        with duckdb_conn_with_data.cursor() as cur:
+            cur.execute("select:\n  measures:\n    - Revenue\n")
+            rows = cur.fetchall()
+            assert len(rows) == 1
+            assert rows[0][0] == 1000.0
+
+
+def test_obml_count_measure(duckdb_conn_with_data: Connection) -> None:
+    """OBML count aggregation."""
+    compiled_sql = "SELECT COUNT(order_id) AS order_count FROM orders"
+    with patch("httpx.post", return_value=_mock_api_response(compiled_sql)):
+        with duckdb_conn_with_data.cursor() as cur:
+            cur.execute("select:\n  measures:\n    - Order Count\n")
+            rows = cur.fetchall()
+            assert len(rows) == 1
+            assert rows[0][0] == 5
+
+
+def test_obml_with_limit(duckdb_conn_with_data: Connection) -> None:
+    """OBML with limit clause."""
+    compiled_sql = (
+        "SELECT region, SUM(amount) AS revenue FROM orders GROUP BY region LIMIT 2"
+    )
+    with patch("httpx.post", return_value=_mock_api_response(compiled_sql)):
+        with duckdb_conn_with_data.cursor() as cur:
+            cur.execute(
+                "select:\n  dimensions:\n    - Region\n  measures:\n    - Revenue\nlimit: 2\n"
+            )
+            rows = cur.fetchall()
+            assert len(rows) == 2
+
+
+def test_obml_rest_api_url_forwarded(duckdb_conn_with_data: Connection) -> None:
+    """The ob_api_url is forwarded to the REST call."""
+    compiled_sql = "SELECT 1"
+    with patch("httpx.post", return_value=_mock_api_response(compiled_sql)) as mock_post:
+        with duckdb_conn_with_data.cursor() as cur:
+            cur.execute("select:\n  measures:\n    - Revenue\n")
+            url = mock_post.call_args.args[0]
+            assert "/v1/query/sql" in url
+            assert mock_post.call_args.kwargs["params"] == {"dialect": "duckdb"}
+
+
+def test_plain_sql_passthrough(duckdb_conn_with_data: Connection) -> None:
+    """Plain SQL is passed through without OBML compilation."""
+    with duckdb_conn_with_data.cursor() as cur:
+        cur.execute("SELECT COUNT(*) FROM orders")
+        assert cur.fetchone() == (5,)

ob_duckdb-0.1.0/tests/test_yaml_detection.py

@@ -0,0 +1,29 @@
+"""Unit tests for OBML YAML detection — runs without any external service."""
+import pytest
+from ob_duckdb.compiler import is_obml, parse_obml
+
+
+@pytest.mark.parametrize("query,expected", [
+    ("select:\n  dimensions:\n    - Region\n  measures:\n    - Revenue\n", True),
+    ("select:\n  measures:\n    - Revenue\n", True),
+    ("select:\n  dimensions:\n    - Country\n", True),
+    ("SELECT:\n  dimensions:\n    - X\n", True),
+    ("   select:\n  dimensions:\n    - X\n", True),
+    ("SELECT * FROM orders", False),
+    ("SELECT id FROM customers WHERE id = 1", False),
+    ("", False),
+    ("model:\n  name: test\n", False),
+    ("select:\n  filters:\n    - x = 1\n", False),
+    ("select:\n  - [unclosed", False),
+    ("select:\n  - dimension1\n", False),
+])
+def test_obml_detection(query, expected):
+    assert is_obml(query) == expected
+
+
+def test_parse_obml_returns_dict():
+    q = "select:\n  dimensions:\n    - Region\n  measures:\n    - Revenue\nlimit: 100\n"
+    result = parse_obml(q)
+    assert result["select"]["dimensions"] == ["Region"]
+    assert result["select"]["measures"] == ["Revenue"]
+    assert result["limit"] == 100