ob-driver-core 0.1.0__tar.gz

ob_driver_core-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_driver_core-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_driver_core-0.1.0/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: ob-driver-core
+Version: 0.1.0
+Summary: Shared foundation for OrionBelt DB-API 2.0 drivers (PEP 249 types, OBML detection, compilation bridge)
+Author-email: Ralf Becher <info@orionbelt.ai>
+License: BSL-1.1
+License-File: LICENSE
+Keywords: db-api,obml,orionbelt,pep249,semantic-layer
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ob-driver-core
+
+Shared foundation for OrionBelt DB-API 2.0 drivers (PEP 249 types, OBML detection, compilation bridge)
+
+Part of the [OrionBelt Semantic Layer](https://github.com/ralfbecher/orionbelt-semantic-layer) project.
+
+## Installation
+
+```bash
+pip install ob-driver-core
+```
+
+## License
+
+BSL-1.1 — see [LICENSE](LICENSE) for details.

ob_driver_core-0.1.0/README.md

@@ -0,0 +1,15 @@
+# ob-driver-core
+
+Shared foundation for OrionBelt DB-API 2.0 drivers (PEP 249 types, OBML detection, compilation bridge)
+
+Part of the [OrionBelt Semantic Layer](https://github.com/ralfbecher/orionbelt-semantic-layer) project.
+
+## Installation
+
+```bash
+pip install ob-driver-core
+```
+
+## License
+
+BSL-1.1 — see [LICENSE](LICENSE) for details.

ob_driver_core-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ob-driver-core"
+version = "0.1.0"
+description = "Shared foundation for OrionBelt DB-API 2.0 drivers (PEP 249 types, OBML detection, compilation bridge)"
+license = { text = "BSL-1.1" }
+readme = "README.md"
+authors = [{ name = "Ralf Becher", email = "info@orionbelt.ai" }]
+keywords = ["semantic-layer", "obml", "db-api", "orionbelt", "pep249"]
+requires-python = ">=3.12"
+dependencies = [
+    "pyyaml>=6.0",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "mypy>=1.10",
+    "ruff>=0.4",
+    "respx>=0.21",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ob_driver_core"]
+
+[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_driver_core"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ob_driver_core-0.1.0/src/ob_driver_core/__init__.py

@@ -0,0 +1,5 @@
+"""OrionBelt DB-API 2.0 driver core — shared PEP 249 types, OBML detection, compilation bridge."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

ob_driver_core-0.1.0/src/ob_driver_core/compiler.py

@@ -0,0 +1,52 @@
+"""OrionBelt compilation bridge for DB-API 2.0 drivers.
+
+Compiles OBML query dicts to SQL by calling the OrionBelt REST API.
+Assumes the API is running in single-model mode (MODEL_FILE set).
+Uses the ``/v1/query/sql`` shortcut endpoint — no session or model ID required.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ob_driver_core.exceptions import OperationalError, ProgrammingError
+
+logger = logging.getLogger(__name__)
+
+
+def compile_obml(
+    obml: dict[str, Any],
+    *,
+    dialect: str,
+    ob_api_url: str = "http://localhost:8000",
+    ob_timeout: int = 30,
+) -> str:
+    """Compile an OBML query dict to SQL via the OrionBelt REST API.
+
+    Calls ``POST /v1/query/sql?dialect=...`` which auto-resolves the
+    single session and model in single-model mode.
+    """
+    import httpx
+
+    url = f"{ob_api_url.rstrip('/')}/v1/query/sql"
+    try:
+        response = httpx.post(
+            url,
+            params={"dialect": dialect},
+            json=obml,
+            timeout=ob_timeout,
+        )
+    except httpx.ConnectError as exc:
+        raise OperationalError(f"OB API unavailable at {ob_api_url}: {exc}") from exc
+
+    if not response.is_success:
+        try:
+            detail = response.json().get("detail", response.text)
+        except Exception:
+            detail = response.text
+        if response.status_code < 500:
+            raise ProgrammingError(f"OB compile error: {detail}")
+        raise OperationalError(f"OB API error: {detail}")
+
+    return response.json()["sql"]  # type: ignore[no-any-return]

ob_driver_core-0.1.0/src/ob_driver_core/detection.py

@@ -0,0 +1,36 @@
+"""OBML YAML query detection.
+
+Determines whether a query string is an OBML semantic query or plain SQL.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import yaml
+
+
+def is_obml(query: str) -> bool:
+    """Return True if *query* is an OBML YAML query (starts with ``select:`` and
+    contains ``dimensions`` or ``measures``).
+    """
+    stripped = query.strip()
+    if not stripped.lower().startswith("select:"):
+        return False
+    try:
+        parsed = yaml.safe_load(stripped)
+    except yaml.YAMLError:
+        return False
+    if not isinstance(parsed, dict):
+        return False
+    # YAML preserves key case — normalise to lowercase for lookup
+    lower_keys = {k.lower() if isinstance(k, str) else k: v for k, v in parsed.items()}
+    select = lower_keys.get("select", {})
+    if not isinstance(select, dict):
+        return False
+    return "dimensions" in select or "measures" in select
+
+
+def parse_obml(query: str) -> dict[str, Any]:
+    """Parse an OBML YAML string into a dict. Call only after :func:`is_obml`."""
+    return yaml.safe_load(query.strip())  # type: ignore[return-value]

ob_driver_core-0.1.0/src/ob_driver_core/exceptions.py

@@ -0,0 +1,57 @@
+"""PEP 249 DB-API 2.0 exception hierarchy.
+
+Hierarchy (per PEP 249):
+    StandardError (builtin Exception)
+    ├── Warning
+    └── Error
+        ├── InterfaceError
+        └── DatabaseError
+            ├── DataError
+            ├── OperationalError
+            ├── IntegrityError
+            ├── InternalError
+            ├── ProgrammingError
+            └── NotSupportedError
+"""
+
+from __future__ import annotations
+
+
+class Warning(Exception):  # noqa: A001
+    """Exception raised for important warnings (e.g. data truncation)."""
+
+
+class Error(Exception):
+    """Base class for all DB-API errors."""
+
+
+class InterfaceError(Error):
+    """Exception for errors related to the database interface, not the database itself."""
+
+
+class DatabaseError(Error):
+    """Exception for errors related to the database."""
+
+
+class DataError(DatabaseError):
+    """Exception for errors due to problems with processed data."""
+
+
+class OperationalError(DatabaseError):
+    """Exception for errors related to the database's operation."""
+
+
+class IntegrityError(DatabaseError):
+    """Exception for errors related to database integrity."""
+
+
+class InternalError(DatabaseError):
+    """Exception for internal database errors."""
+
+
+class ProgrammingError(DatabaseError):
+    """Exception for programming errors (e.g. bad SQL, table not found)."""
+
+
+class NotSupportedError(DatabaseError):
+    """Exception for optional features not supported by the database."""

ob_driver_core-0.1.0/src/ob_driver_core/type_codes.py

@@ -0,0 +1,41 @@
+"""PEP 249 DB-API 2.0 type objects.
+
+Type objects compare equal to any value in their set, enabling:
+    if cursor.description[i][1] == NUMBER:
+        ...
+"""
+
+from __future__ import annotations
+
+
+class DBAPITypeObject:
+    """PEP 249 type object that compares equal to any value in its set."""
+
+    def __init__(self, *values: str) -> None:
+        self._values = frozenset(values)
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, str):
+            return other in self._values
+        if isinstance(other, DBAPITypeObject):
+            return self._values == other._values
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash(self._values)
+
+    def __repr__(self) -> str:
+        return f"DBAPITypeObject({', '.join(sorted(self._values))})"
+
+
+STRING = DBAPITypeObject("STRING", "VARCHAR", "TEXT", "CHAR", "NVARCHAR", "NCHAR")
+BINARY = DBAPITypeObject("BINARY", "BLOB", "VARBINARY", "BYTEA", "BYTES")
+NUMBER = DBAPITypeObject(
+    "NUMBER", "INT", "INTEGER", "BIGINT", "SMALLINT", "TINYINT",
+    "FLOAT", "DOUBLE", "DECIMAL", "NUMERIC", "REAL", "HUGEINT",
+)
+DATETIME = DBAPITypeObject(
+    "DATETIME", "DATE", "TIME", "TIMESTAMP", "TIMESTAMPTZ",
+    "TIMESTAMP_NTZ", "TIMESTAMP_LTZ", "TIMESTAMP_TZ",
+)
+ROWID = DBAPITypeObject("ROWID")

ob_driver_core-0.1.0/tests/test_compiler.py

@@ -0,0 +1,86 @@
+"""Unit tests for the compilation bridge."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import httpx
+import pytest
+
+from ob_driver_core.compiler import compile_obml
+from ob_driver_core.exceptions import OperationalError, ProgrammingError
+
+
+SAMPLE_OBML = {"select": {"dimensions": ["Region"], "measures": ["Revenue"]}}
+
+
+def test_compile_success() -> None:
+    """Successful REST call returns SQL."""
+    mock_response = MagicMock()
+    mock_response.is_success = True
+    mock_response.json.return_value = {"sql": "SELECT region, SUM(amount) FROM orders GROUP BY region"}
+
+    with patch("httpx.post", return_value=mock_response) as mock_post:
+        sql = compile_obml(SAMPLE_OBML, dialect="duckdb")
+        assert sql == "SELECT region, SUM(amount) FROM orders GROUP BY region"
+        mock_post.assert_called_once()
+        call_kwargs = mock_post.call_args
+        assert call_kwargs.kwargs["params"] == {"dialect": "duckdb"}
+        assert "/v1/query/sql" in call_kwargs.args[0]
+
+
+def test_compile_connect_error_raises_operational() -> None:
+    """Connection failure to REST API raises OperationalError."""
+    with patch("httpx.post", side_effect=httpx.ConnectError("refused")):
+        with pytest.raises(OperationalError, match="unavailable"):
+            compile_obml(SAMPLE_OBML, dialect="duckdb")
+
+
+def test_compile_4xx_raises_programming() -> None:
+    """4xx response from REST API raises ProgrammingError."""
+    mock_response = MagicMock()
+    mock_response.is_success = False
+    mock_response.status_code = 400
+    mock_response.json.return_value = {"detail": "bad query"}
+    mock_response.text = "bad query"
+
+    with patch("httpx.post", return_value=mock_response):
+        with pytest.raises(ProgrammingError, match="bad query"):
+            compile_obml(SAMPLE_OBML, dialect="duckdb")
+
+
+def test_compile_5xx_raises_operational() -> None:
+    """5xx response from REST API raises OperationalError."""
+    mock_response = MagicMock()
+    mock_response.is_success = False
+    mock_response.status_code = 500
+    mock_response.json.return_value = {"detail": "internal"}
+    mock_response.text = "internal"
+
+    with patch("httpx.post", return_value=mock_response):
+        with pytest.raises(OperationalError, match="internal"):
+            compile_obml(SAMPLE_OBML, dialect="duckdb")
+
+
+def test_compile_custom_api_url() -> None:
+    """Custom ob_api_url is used in the request."""
+    mock_response = MagicMock()
+    mock_response.is_success = True
+    mock_response.json.return_value = {"sql": "SELECT 1"}
+
+    with patch("httpx.post", return_value=mock_response) as mock_post:
+        compile_obml(SAMPLE_OBML, dialect="postgres", ob_api_url="http://my-api:9000")
+        url = mock_post.call_args.args[0]
+        assert url == "http://my-api:9000/v1/query/sql"
+
+
+def test_compile_trailing_slash_stripped() -> None:
+    """Trailing slash in ob_api_url is stripped."""
+    mock_response = MagicMock()
+    mock_response.is_success = True
+    mock_response.json.return_value = {"sql": "SELECT 1"}
+
+    with patch("httpx.post", return_value=mock_response) as mock_post:
+        compile_obml(SAMPLE_OBML, dialect="duckdb", ob_api_url="http://localhost:8000/")
+        url = mock_post.call_args.args[0]
+        assert url == "http://localhost:8000/v1/query/sql"

ob_driver_core-0.1.0/tests/test_detection.py

@@ -0,0 +1,34 @@
+"""Unit tests for OBML YAML detection."""
+
+import pytest
+
+from ob_driver_core.detection 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: str, expected: bool) -> None:
+    assert is_obml(query) == expected
+
+
+def test_parse_obml_returns_dict() -> None:
+    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

ob_driver_core-0.1.0/tests/test_exceptions.py

@@ -0,0 +1,63 @@
+"""Verify the PEP 249 exception hierarchy."""
+
+from ob_driver_core.exceptions import (
+    DataError,
+    DatabaseError,
+    Error,
+    IntegrityError,
+    InterfaceError,
+    InternalError,
+    NotSupportedError,
+    OperationalError,
+    ProgrammingError,
+    Warning,
+)
+
+
+def test_warning_is_exception() -> None:
+    assert issubclass(Warning, Exception)
+
+
+def test_error_is_exception() -> None:
+    assert issubclass(Error, Exception)
+
+
+def test_interface_error_is_error() -> None:
+    assert issubclass(InterfaceError, Error)
+
+
+def test_database_error_is_error() -> None:
+    assert issubclass(DatabaseError, Error)
+
+
+def test_data_error_is_database_error() -> None:
+    assert issubclass(DataError, DatabaseError)
+
+
+def test_operational_error_is_database_error() -> None:
+    assert issubclass(OperationalError, DatabaseError)
+
+
+def test_integrity_error_is_database_error() -> None:
+    assert issubclass(IntegrityError, DatabaseError)
+
+
+def test_internal_error_is_database_error() -> None:
+    assert issubclass(InternalError, DatabaseError)
+
+
+def test_programming_error_is_database_error() -> None:
+    assert issubclass(ProgrammingError, DatabaseError)
+
+
+def test_not_supported_error_is_database_error() -> None:
+    assert issubclass(NotSupportedError, DatabaseError)
+
+
+def test_can_raise_and_catch_by_parent() -> None:
+    try:
+        raise ProgrammingError("bad query")
+    except DatabaseError as exc:
+        assert str(exc) == "bad query"
+    except Exception:
+        raise AssertionError("ProgrammingError should be catchable as DatabaseError")

ob_driver_core-0.1.0/tests/test_type_codes.py

@@ -0,0 +1,55 @@
+"""Verify PEP 249 type objects."""
+
+from ob_driver_core.type_codes import BINARY, DATETIME, NUMBER, ROWID, STRING, DBAPITypeObject
+
+
+def test_string_matches() -> None:
+    assert STRING == "STRING"
+    assert STRING == "VARCHAR"
+    assert STRING == "TEXT"
+    assert STRING != "INTEGER"
+
+
+def test_number_matches() -> None:
+    assert NUMBER == "INT"
+    assert NUMBER == "INTEGER"
+    assert NUMBER == "BIGINT"
+    assert NUMBER == "FLOAT"
+    assert NUMBER == "DECIMAL"
+    assert NUMBER != "VARCHAR"
+
+
+def test_datetime_matches() -> None:
+    assert DATETIME == "TIMESTAMP"
+    assert DATETIME == "DATE"
+    assert DATETIME == "TIMESTAMP_NTZ"
+    assert DATETIME != "INT"
+
+
+def test_binary_matches() -> None:
+    assert BINARY == "BLOB"
+    assert BINARY == "BYTEA"
+    assert BINARY != "TEXT"
+
+
+def test_rowid_matches() -> None:
+    assert ROWID == "ROWID"
+    assert ROWID != "INT"
+
+
+def test_equality_between_type_objects() -> None:
+    other = DBAPITypeObject("STRING", "VARCHAR", "TEXT", "CHAR", "NVARCHAR", "NCHAR")
+    assert STRING == other
+
+
+def test_repr() -> None:
+    r = repr(ROWID)
+    assert "ROWID" in r
+    assert "DBAPITypeObject" in r
+
+
+def test_hash_stable() -> None:
+    a = DBAPITypeObject("A", "B")
+    b = DBAPITypeObject("B", "A")
+    assert hash(a) == hash(b)
+    assert a == b