ob-postgres 0.1.0__py3-none-any.whl

ob_postgres/__init__.py

@@ -0,0 +1,157 @@
+"""ob-postgres — OrionBelt Semantic Layer driver for PostgreSQL (PEP 249 DB-API 2.0).
+
+Uses ``adbc-driver-postgresql`` for native Arrow support.  ADBC provides
+zero-copy Arrow results directly from the PostgreSQL wire protocol, enabling
+efficient Arrow Flight SQL streaming.
+
+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_postgres
+
+    conn = ob_postgres.connect(dbname="mydb", user="me", password="secret")
+    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
+from urllib.parse import quote_plus, urlencode
+
+import adbc_driver_postgresql.dbapi
+
+from ob_postgres.connection import Connection
+from ob_postgres.exceptions import (
+    DatabaseError,
+    DataError,
+    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"  # ADBC uses ? placeholders
+
+
+def _build_pg_uri(
+    *,
+    host: str,
+    port: int,
+    dbname: str,
+    user: str | None,
+    password: str | None,
+    sslmode: str | None,
+) -> str:
+    """Build a PostgreSQL connection URI from keyword arguments."""
+    userinfo = ""
+    if user is not None:
+        userinfo = quote_plus(user)
+        if password is not None:
+            userinfo += f":{quote_plus(password)}"
+        userinfo += "@"
+    params: dict[str, str] = {}
+    if sslmode is not None:
+        params["sslmode"] = sslmode
+    query = f"?{urlencode(params)}" if params else ""
+    return f"postgresql://{userinfo}{host}:{port}/{dbname}{query}"
+
+
+def connect(
+    dsn: str | None = None,
+    *,
+    host: str = "localhost",
+    port: int = 5432,
+    dbname: str = "postgres",
+    user: str | None = None,
+    password: str | None = None,
+    sslmode: str | None = None,
+    schema: str | None = None,
+    options: dict[str, Any] | None = None,
+    # OrionBelt parameters
+    ob_api_url: str = "http://localhost:8000",
+    ob_timeout: int = 30,
+) -> Connection:
+    """Open a PostgreSQL connection with OBML support (ADBC driver).
+
+    Parameters
+    ----------
+    dsn : str, optional
+        Full PostgreSQL URI (overrides individual params).
+    host : str
+        PostgreSQL host (default: ``localhost``).
+    port : int
+        PostgreSQL port (default: ``5432``).
+    dbname : str
+        Database name (default: ``postgres``).
+    user : str, optional
+        Username.
+    password : str, optional
+        Password.
+    sslmode : str, optional
+        SSL mode (``disable``, ``require``, ``verify-full``, etc.).
+    schema : str, optional
+        PostgreSQL schema — sets ``search_path`` after connecting.
+    options : dict, optional
+        Extra connection options (added as URI query parameters).
+    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.
+    """
+    if dsn is not None:
+        uri = dsn
+    else:
+        # Include search_path as a connection option if schema is specified
+        extra_options = dict(options) if options else {}
+        if schema:
+            extra_options["options"] = f"-csearch_path={schema}"
+
+        uri = _build_pg_uri(
+            host=host,
+            port=port,
+            dbname=dbname,
+            user=user,
+            password=password,
+            sslmode=sslmode,
+        )
+        if extra_options:
+            sep = "&" if "?" in uri else "?"
+            uri += sep + urlencode(extra_options)
+
+    native = adbc_driver_postgresql.dbapi.connect(uri)
+
+    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_postgres/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_postgres/connection.py

@@ -0,0 +1,65 @@
+"""PEP 249 Connection wrapping ``adbc_driver_postgresql.dbapi.Connection``."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ob_postgres.cursor import Cursor
+from ob_postgres.exceptions import ProgrammingError
+
+
+class Connection:
+    """DB-API 2.0 connection that wraps an ADBC PostgreSQL connection.
+
+    ADBC provides native Arrow support — cursors created from this connection
+    support ``fetch_arrow_table()`` for zero-copy Arrow Flight SQL streaming.
+    OBML queries are compiled to SQL via the OrionBelt REST API.
+    """
+
+    def __init__(
+        self,
+        native: Any,
+        *,
+        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 the current transaction."""
+        self._check_open()
+        self._native.commit()
+
+    def rollback(self) -> None:
+        """Rollback the current transaction."""
+        self._check_open()
+        self._native.rollback()
+
+    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_postgres/cursor.py

@@ -0,0 +1,158 @@
+"""PEP 249 Cursor with OBML interception for PostgreSQL.
+
+Uses ``adbc-driver-postgresql`` (Arrow Database Connectivity) for native
+Arrow support.  ``fetch_arrow_table()`` returns a PyArrow Table directly
+from the ADBC cursor — zero-copy columnar transfer for Arrow Flight SQL.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ob_postgres.compiler import compile_obml, is_obml, parse_obml
+from ob_postgres.exceptions import NotSupportedError, ProgrammingError
+from ob_postgres.type_codes import PG_OID_MAP, STRING
+
+
+class Cursor:
+    """DB-API 2.0 cursor that intercepts OBML YAML queries.
+
+    If the query is OBML, it is compiled to PostgreSQL SQL via the OrionBelt
+    REST API before execution. Plain SQL is passed through unchanged.
+
+    Wraps an ``adbc_driver_postgresql.dbapi`` cursor which natively supports
+    ``fetch_arrow_table()`` for zero-copy Arrow results.
+    """
+
+    arraysize: int = 1
+
+    def __init__(
+        self,
+        native: Any,
+        *,
+        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
+
+    @property
+    def description(
+        self,
+    ) -> tuple[tuple[str, Any, None, None, None, None, None], ...] | None:
+        """PEP 249 cursor description — 7-item tuples per column."""
+        native_desc = self._native.description
+        if native_desc is None:
+            return None
+        cols: list[tuple[str, Any, None, None, None, None, None]] = []
+        for col in native_desc:
+            name = col[0]
+            type_code = col[1]
+            # ADBC PG driver may return OIDs or other type identifiers
+            mapped = PG_OID_MAP.get(type_code, STRING) if isinstance(type_code, int) else STRING
+            cols.append((name, mapped, None, None, None, None, None))
+        return tuple(cols)
+
+    @property
+    def rowcount(self) -> int:
+        return self._native.rowcount
+
+    def _check_open(self) -> None:
+        if self._closed:
+            raise ProgrammingError("Cursor is closed.")
+
+    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)
+        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.")
+        for params in seq_of_parameters:
+            self._native.execute(operation, params)
+
+    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="postgres",
+            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 (ADBC native).
+
+        ADBC provides zero-copy Arrow results directly from the PostgreSQL
+        wire protocol.  Significantly more memory-efficient than materialising
+        Python row objects and enables efficient Arrow Flight SQL streaming.
+        """
+        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:
+        """PostgreSQL does not expose lastrowid via ADBC cursor."""
+        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_postgres/exceptions.py

@@ -0,0 +1,32 @@
+"""PEP 249 exceptions — re-exported from ob-driver-core for convenience.
+
+Allows users to do: ``from ob_postgres.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_postgres/type_codes.py

@@ -0,0 +1,45 @@
+"""PEP 249 type objects — re-exported from ob-driver-core plus Postgres OID mapping.
+
+psycopg2 cursor.description returns integer OIDs as type_code.
+The PG_OID_MAP maps common OIDs 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", "PG_OID_MAP"]
+
+# Common PostgreSQL OIDs — see pg_type catalog
+# https://www.postgresql.org/docs/current/catalog-pg-type.html
+PG_OID_MAP: dict[int, object] = {
+    # Boolean
+    16: STRING,  # bool
+    # Numeric types
+    20: NUMBER,  # int8 (bigint)
+    21: NUMBER,  # int2 (smallint)
+    23: NUMBER,  # int4 (integer)
+    26: NUMBER,  # oid
+    700: NUMBER,  # float4
+    701: NUMBER,  # float8
+    790: NUMBER,  # money
+    1700: NUMBER,  # numeric/decimal
+    # String types
+    18: STRING,  # char
+    19: STRING,  # name
+    25: STRING,  # text
+    1042: STRING,  # bpchar (char(n))
+    1043: STRING,  # varchar
+    2950: STRING,  # uuid
+    114: STRING,  # json
+    3802: STRING,  # jsonb
+    # Date/time types
+    1082: DATETIME,  # date
+    1083: DATETIME,  # time
+    1114: DATETIME,  # timestamp
+    1184: DATETIME,  # timestamptz
+    1186: DATETIME,  # interval
+    1266: DATETIME,  # timetz
+    # Binary types
+    17: BINARY,  # bytea
+}

ob_postgres-0.1.0.dist-info/METADATA

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: ob-postgres
+Version: 0.1.0
+Summary: OrionBelt Semantic Layer driver for PostgreSQL (DB-API 2.0)
+Author-email: Ralf Becher <info@orionbelt.ai>
+License: BSL-1.1
+License-File: LICENSE
+Keywords: db-api,obml,orionbelt,postgres,semantic-layer
+Requires-Python: >=3.12
+Requires-Dist: adbc-driver-postgresql>=1.0
+Requires-Dist: ob-driver-core>=0.1
+Requires-Dist: pyarrow>=16.0
+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: respx>=0.21; 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-postgres
+
+OrionBelt Semantic Layer driver for PostgreSQL (DB-API 2.0)
+
+Part of the [OrionBelt Semantic Layer](https://github.com/ralfbecher/orionbelt-semantic-layer) project.
+
+## Installation
+
+```bash
+pip install ob-postgres
+```
+
+## License
+
+BSL-1.1 — see [LICENSE](LICENSE) for details.

ob_postgres-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+ob_postgres/__init__.py,sha256=qtrEuq_lXWQBdUCzFIXqCUOrX2aeBPRnPf5RYeqNqX4,4295
+ob_postgres/compiler.py,sha256=WTYZzdsJJiOxgIDS3NpDOpk_SG7_0weT4el-xuuBGsE,264
+ob_postgres/connection.py,sha256=FV5Rt08T6RZ6jqDssIo1fHG3DJv-wJCrRhVcSBH92Fw,1835
+ob_postgres/cursor.py,sha256=VaTQUbBVUJtNuZegfjloTX2bw9G4Z_-n9bAoUlfiCYI,5311
+ob_postgres/exceptions.py,sha256=ijpN5kj3_faOS8jlH5FXCY1ynyX2plnJ7fqukG-81_8,638
+ob_postgres/type_codes.py,sha256=EEsdrqmzHDo3dz1VtQ1y1c1Grw1Z2gXZQaG9vSDlUaM,1341
+ob_postgres-0.1.0.dist-info/METADATA,sha256=qagacjqfnd5j67FGnlLBwHW_F1f-Ood_LuMHBEd7VIs,1054
+ob_postgres-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ob_postgres-0.1.0.dist-info/entry_points.txt,sha256=y2fG3zJChKHGb1X9heLZhzusl87wpiL6I4l9gJyQ3TY,74
+ob_postgres-0.1.0.dist-info/licenses/LICENSE,sha256=t-vr73N5s2w6yxpCnwo5r_QuB5_u6FuEovAYMjlfe7E,3378
+ob_postgres-0.1.0.dist-info/RECORD,,

ob_postgres-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ob_postgres-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[sqlalchemy.dialects]
+ob.postgres = ob_postgres.dialect:OBPostgresDialect

ob_postgres-0.1.0.dist-info/licenses/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/.