oxyde-postgres 0.1.0__py3-none-any.whl

oxyde/core/ir.py

@@ -0,0 +1,380 @@
+"""Intermediate Representation (IR) builders for Rust query execution.
+
+This module provides functions to construct query IR dicts that are
+serialized to MessagePack and sent to the Rust core for SQL generation.
+
+IR Protocol:
+    Every IR payload has:
+        proto: Version number (currently 1)
+        op: Operation type ("select", "insert", "update", "delete", "raw")
+        table: Target table name
+
+Filter Tree:
+    WHERE clauses are represented as a tree of FilterNode dicts:
+
+    Condition (leaf):
+        {"type": "condition", "field": "age", "operator": ">=", "value": 18}
+
+    AND (branch):
+        {"type": "and", "conditions": [node1, node2, ...]}
+
+    OR (branch):
+        {"type": "or", "conditions": [node1, node2]}
+
+    NOT (branch):
+        {"type": "not", "condition": node}
+
+Functions:
+    filter_condition(field, operator, value) → FilterNode
+    filter_and(*nodes) → FilterNode
+    filter_or(*nodes) → FilterNode
+    filter_not(node) → FilterNode
+
+    build_select_ir(...) → dict:
+        SELECT with columns, filter_tree, order_by, limit, joins, aggregates, etc.
+
+    build_insert_ir(...) → dict:
+        INSERT with values or bulk_values, pk_column for RETURNING.
+
+    build_update_ir(...) → dict:
+        UPDATE with values and filter_tree, or bulk_update for CASE WHEN.
+
+    build_delete_ir(...) → dict:
+        DELETE with filter_tree.
+
+    build_raw_sql_ir(sql, params) → dict:
+        Raw SQL escape hatch.
+
+Example IR (SELECT):
+    {
+        "proto": 1,
+        "op": "select",
+        "table": "users",
+        "cols": ["id", "name", "email"],
+        "column_types": {"id": {"kind": "big_integer"}, "name": {"kind": "string"}},
+        "filter_tree": {"type": "condition", "field": "active", "operator": "=", "value": true},
+        "order_by": [("created_at", "desc")],
+        "limit": 10
+    }
+
+Rust Processing:
+    IR bytes → oxyde-codec::QueryIR → oxyde-sql::build_sql() → SQL string
+    SQL → oxyde-driver::execute_query() → rows → MessagePack bytes → Python
+"""
+
+from __future__ import annotations
+
+from collections.abc import MutableMapping, Sequence
+from typing import Any
+
+IR_PROTO_VERSION = 1
+
+FilterNode = MutableMapping[str, Any]
+
+
+def filter_condition(
+    field: str,
+    operator: str,
+    value: Any,
+    *,
+    column: str | None = None,
+    escape: str | None = None,
+) -> FilterNode:
+    """Create a simple condition node."""
+    payload: FilterNode = {
+        "type": "condition",
+        "field": field,
+        "operator": operator,
+        "value": value,
+    }
+    if column is not None and column != field:
+        payload["column"] = column
+    if escape is not None:
+        payload["escape"] = escape
+    return payload
+
+
+def filter_and(*nodes: FilterNode) -> FilterNode:
+    """Combine nodes with logical AND."""
+    normalized = [_ensure_filter_node(node) for node in nodes if node]
+    if not normalized:
+        raise ValueError("filter_and() requires at least one condition")
+    if len(normalized) == 1:
+        return normalized[0]
+    return {"type": "and", "conditions": normalized}
+
+
+def filter_or(*nodes: FilterNode) -> FilterNode:
+    """Combine nodes with logical OR."""
+    normalized = [_ensure_filter_node(node) for node in nodes if node]
+    if len(normalized) < 2:
+        raise ValueError("filter_or() requires at least two conditions")
+    return {"type": "or", "conditions": normalized}
+
+
+def filter_not(node: FilterNode) -> FilterNode:
+    """Negate a filter node."""
+    return {"type": "not", "condition": _ensure_filter_node(node)}
+
+
+def _ensure_filter_node(node: FilterNode) -> FilterNode:
+    if not isinstance(node, MutableMapping) or "type" not in node:
+        raise TypeError("Filter node must be a mapping with a 'type' key")
+    return node
+
+
+def build_select_ir(
+    *,
+    table: str,
+    columns: Sequence[str] | None = None,
+    column_types: dict[str, dict] | None = None,
+    column_db_types: dict[str, str] | None = None,
+    model: str | None = None,
+    column_mappings: dict[str, str] | None = None,
+    filter_tree: FilterNode | None = None,
+    distinct: bool | None = None,
+    limit: int | None = None,
+    offset: int | None = None,
+    order_by: Sequence[tuple[str, str]] | None = None,
+    joins: Sequence[dict[str, Any]] | None = None,
+    group_by: Sequence[str] | None = None,
+    having: FilterNode | None = None,
+    aggregates: Sequence[dict[str, Any]] | None = None,
+    returning: bool | None = None,
+    exists: bool | None = None,
+    count: bool | None = None,
+    lock: str | None = None,
+    pk_column: str | None = None,
+    union_query: dict[str, Any] | None = None,
+    union_all: bool | None = None,
+) -> dict[str, Any]:
+    """Build a SELECT query IR payload.
+
+    Args:
+        column_types: Optional mapping of column name to ColumnTypeSpec dict
+            ({"kind": ...}). Used by Rust for typed binding and decoding
+        column_db_types: Optional mapping of column name (keyed like
+            column_types) to its db_type override. PostgreSQL filters cast
+            array values and array-lookup operands to an array override.
+        pk_column: Primary key column name, used for deduplication in JOIN queries.
+    """
+    payload: dict[str, Any] = {
+        "proto": IR_PROTO_VERSION,
+        "op": "select",
+        "table": table,
+    }
+    # cols is optional when count=True or exists=True
+    if columns:
+        payload["cols"] = list(columns)
+    if column_types:
+        payload["column_types"] = dict(column_types)
+    if column_db_types:
+        payload["column_db_types"] = dict(column_db_types)
+    if filter_tree:
+        payload["filter_tree"] = filter_tree
+    if model:
+        payload["model"] = model
+    if column_mappings:
+        payload["column_mappings"] = dict(column_mappings)
+    if distinct is not None:
+        payload["distinct"] = bool(distinct)
+    if limit is not None:
+        payload["limit"] = int(limit)
+    if offset is not None:
+        payload["offset"] = int(offset)
+    if order_by:
+        payload["order_by"] = [(str(col), direction) for col, direction in order_by]
+    if joins:
+        payload["joins"] = list(joins)
+    if group_by:
+        payload["group_by"] = list(group_by)
+    if having:
+        payload["having"] = having
+    if aggregates:
+        payload["aggregates"] = [dict(agg) for agg in aggregates]
+    if returning is not None:
+        payload["returning"] = bool(returning)
+    if exists is not None:
+        payload["exists"] = bool(exists)
+    if count is not None:
+        payload["count"] = bool(count)
+    if lock is not None:
+        payload["lock"] = lock
+    if pk_column is not None:
+        payload["pk_column"] = pk_column
+    if union_query is not None:
+        payload["union_query"] = union_query
+    if union_all is not None:
+        payload["union_all"] = union_all
+    return payload
+
+
+def build_insert_ir(
+    *,
+    table: str,
+    values: dict[str, Any] | None = None,
+    bulk_values: Sequence[dict[str, Any]] | None = None,
+    column_types: dict[str, dict] | None = None,
+    model: str | None = None,
+    returning: bool | None = None,
+    pk_column: str | None = None,
+) -> dict[str, Any]:
+    """Build an INSERT query IR payload.
+
+    Args:
+        table: Table name
+        values: Single row values dict
+        bulk_values: Multiple rows for bulk insert
+        column_types: ColumnTypeSpec dicts for typed parameter binding.
+        model: Model name for validation
+        returning: Whether to return inserted rows
+        pk_column: Primary key column name (defaults to "id" if not specified)
+    """
+    if not values and not bulk_values:
+        raise ValueError("INSERT requires either 'values' or 'bulk_values'")
+    payload: dict[str, Any] = {
+        "proto": IR_PROTO_VERSION,
+        "op": "insert",
+        "table": table,
+    }
+    if values:
+        payload["values"] = dict(values)
+    if bulk_values:
+        payload["bulk_values"] = [dict(row) for row in bulk_values]
+    if column_types:
+        payload["column_types"] = dict(column_types)
+    if model:
+        payload["model"] = model
+    if returning is not None:
+        payload["returning"] = bool(returning)
+    if pk_column is not None:
+        payload["pk_column"] = pk_column
+    return payload
+
+
+def build_update_ir(
+    *,
+    table: str,
+    values: dict[str, Any] | None = None,
+    filter_tree: FilterNode | None = None,
+    column_types: dict[str, dict] | None = None,
+    column_db_types: dict[str, str] | None = None,
+    model: str | None = None,
+    returning: bool | None = None,
+    bulk_update: Sequence[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    """Build an UPDATE query IR payload.
+
+    Args:
+        table: Table name
+        values: Values to update
+        filter_tree: Filter conditions
+        column_types: ColumnTypeSpec dicts for typed parameter binding.
+        column_db_types: Column db_type overrides for array casts and JSON lookups.
+        model: Model name
+        returning: Whether to return updated rows
+        bulk_update: Bulk update rows
+    """
+    if not values and not bulk_update:
+        raise ValueError("UPDATE requires either 'values' or 'bulk_update'")
+    if values and bulk_update:
+        raise ValueError("Provide either 'values' or 'bulk_update', not both")
+    payload: dict[str, Any] = {
+        "proto": IR_PROTO_VERSION,
+        "op": "update",
+        "table": table,
+    }
+    if values:
+        payload["values"] = dict(values)
+    if bulk_update:
+        normalized_rows: list[dict[str, Any]] = []
+        for entry in bulk_update:
+            filters_payload = dict(entry.get("filters") or {})
+            values_payload = dict(entry.get("values") or {})
+            if not filters_payload or not values_payload:
+                raise ValueError(
+                    "Each bulk_update entry requires 'filters' and 'values'"
+                )
+            normalized_rows.append(
+                {
+                    "filters": filters_payload,
+                    "values": values_payload,
+                }
+            )
+        # Wrap in object with "rows" field to match Rust BulkUpdate struct
+        payload["bulk_update"] = {"rows": normalized_rows}
+    if column_types:
+        payload["column_types"] = dict(column_types)
+    if column_db_types:
+        payload["column_db_types"] = dict(column_db_types)
+    if filter_tree:
+        payload["filter_tree"] = filter_tree
+    if model:
+        payload["model"] = model
+    if returning is not None:
+        payload["returning"] = bool(returning)
+    return payload
+
+
+def build_delete_ir(
+    *,
+    table: str,
+    filter_tree: FilterNode | None = None,
+    column_types: dict[str, dict] | None = None,
+    column_db_types: dict[str, str] | None = None,
+    model: str | None = None,
+    returning: bool | None = None,
+) -> dict[str, Any]:
+    """Build a DELETE query IR payload."""
+    payload: dict[str, Any] = {
+        "proto": IR_PROTO_VERSION,
+        "op": "delete",
+        "table": table,
+    }
+    if filter_tree:
+        payload["filter_tree"] = filter_tree
+    if column_types:
+        payload["column_types"] = dict(column_types)
+    if column_db_types:
+        payload["column_db_types"] = dict(column_db_types)
+    if model:
+        payload["model"] = model
+    if returning is not None:
+        payload["returning"] = bool(returning)
+    return payload
+
+
+def build_raw_sql_ir(*, sql: str, params: list[Any] | None = None) -> dict[str, Any]:
+    """Build a raw SQL query IR payload.
+
+    Args:
+        sql: Raw SQL statement
+        params: Optional parameters for the SQL statement
+
+    Returns:
+        IR payload dict
+    """
+    payload: dict[str, Any] = {
+        "proto": IR_PROTO_VERSION,
+        "op": "raw",
+        "table": "",  # Empty table for raw SQL (required by QueryIR)
+        "sql": sql,
+    }
+    if params:
+        payload["params"] = list(params)
+    return payload
+
+
+__all__ = [
+    "IR_PROTO_VERSION",
+    "FilterNode",
+    "filter_condition",
+    "filter_and",
+    "filter_or",
+    "filter_not",
+    "build_select_ir",
+    "build_raw_sql_ir",
+    "build_insert_ir",
+    "build_update_ir",
+    "build_delete_ir",
+]

oxyde/core/types.py

@@ -0,0 +1,69 @@
+"""Unified type registry for the Oxyde ORM.
+
+TYPE_REGISTRY maps Python types to their ORM-level descriptors:
+    - category: lookup category for query filters
+    - serialize: value → msgpack-safe value
+
+Column type classification lives in `core/column_types.py`
+(`compute_column_type`); this registry covers the remaining roles.
+Uses exact type() lookup — no issubclass ordering issues (bool vs int).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal
+from enum import Enum
+from typing import Any
+from uuid import UUID
+
+
+@dataclass(frozen=True, slots=True)
+class TypeDescriptor:
+    """Describes how a Python type maps to ORM operations."""
+
+    category: str  # "string", "numeric", "datetime", "time", "uuid", "bool", "generic"
+    serialize: Callable[[Any], Any]  # value → msgpack-safe value
+
+
+TYPE_REGISTRY: dict[type, TypeDescriptor] = {
+    bool: TypeDescriptor("bool", lambda v: v),
+    int: TypeDescriptor("numeric", lambda v: v),
+    float: TypeDescriptor("numeric", lambda v: v),
+    str: TypeDescriptor("string", lambda v: v),
+    bytes: TypeDescriptor("generic", lambda v: v),
+    bytearray: TypeDescriptor("generic", bytes),
+    datetime: TypeDescriptor("datetime", lambda v: v.isoformat()),
+    date: TypeDescriptor("datetime", lambda v: v.isoformat()),
+    # Own category: comparisons apply, but a time-of-day has no calendar
+    # part, so date-part lookups (year/month/day) must not be offered.
+    time: TypeDescriptor("time", lambda v: v.isoformat()),
+    timedelta: TypeDescriptor("generic", lambda v: int(v.total_seconds() * 1_000_000)),
+    UUID: TypeDescriptor("uuid", str),
+    Decimal: TypeDescriptor("numeric", str),
+    dict: TypeDescriptor("generic", lambda v: v),
+}
+
+
+def serialize_value(value: Any) -> Any:
+    """Serialize a value for msgpack/IR using TYPE_REGISTRY.
+
+    Handles lists, tuples (as lists) and dicts recursively. Returns value
+    unchanged if type is not in the registry (int, str, float, bool, None
+    pass through as-is since msgpack handles them natively).
+    """
+    if isinstance(value, (list, tuple)):
+        return [serialize_value(v) for v in value]
+    if isinstance(value, dict):
+        return {k: serialize_value(v) for k, v in value.items()}
+    if isinstance(value, Enum):
+        return value.value
+    desc = TYPE_REGISTRY.get(type(value))
+    if desc is not None:
+        return desc.serialize(value)
+    return value
+
+
+__all__ = ["TypeDescriptor", "TYPE_REGISTRY", "serialize_value"]

oxyde/core/wrapper.py

@@ -0,0 +1,242 @@
+"""Dynamic import of _oxyde_core Rust extension with ABI version checking.
+
+This module handles the import of the Rust PyO3 extension module (_oxyde_core)
+and provides stub functions if the module is not available or incompatible.
+
+ABI Version:
+    EXPECTED_ABI_VERSION must match __abi_version__ in the Rust module.
+    If mismatch, ImportError is raised prompting rebuild.
+
+Import Strategy:
+    1. Try to import _oxyde_core
+    2. Check ABI version
+    3. Export available functions with hasattr() checks for backwards compat
+    4. If import fails, create stub functions that raise RuntimeError
+
+Why Stub Functions?
+    Allows Python code to import oxyde even without the Rust module built.
+    Useful for:
+    - IDE autocomplete without full build
+    - Documentation generation
+    - Partial testing (model definitions, IR building)
+
+Functions Exported:
+    Pool management:
+        init_pool, init_pool_overwrite, close_pool, close_all_pools
+
+    Query execution:
+        execute, execute_in_transaction
+
+    Transactions:
+        begin_transaction, commit_transaction, rollback_transaction
+        create_savepoint, rollback_to_savepoint, release_savepoint
+
+    Debugging:
+        render_sql, render_sql_debug, explain_query
+
+    Migrations:
+        migration_compute_diff, migration_to_sql
+
+    Validation:
+        register_validator (no-op, not implemented in Rust)
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from typing import Any
+
+# Expected ABI version - must match __abi_version__ in Rust module
+EXPECTED_ABI_VERSION = 1
+
+# Function registry: (rust_name, export_name, is_async, is_noop_fallback)
+# - rust_name: name in _oxyde_core module
+# - export_name: name to export (usually same, but explain -> explain_query)
+# - is_async: True for async functions
+# - is_noop_fallback: True if stub should be no-op instead of raising
+_FUNCTION_REGISTRY: list[tuple[str, str, bool, bool]] = [
+    # Pool management
+    ("init_pool", "init_pool", True, False),
+    ("init_pool_overwrite", "init_pool_overwrite", True, False),
+    ("close_pool", "close_pool", True, False),
+    ("close_all_pools", "close_all_pools", True, False),
+    # Query execution
+    ("execute", "execute", True, False),
+    ("execute_in_transaction", "execute_in_transaction", True, False),
+    # Transactions
+    ("begin_transaction", "begin_transaction", True, False),
+    ("commit_transaction", "commit_transaction", True, False),
+    ("rollback_transaction", "rollback_transaction", True, False),
+    ("create_savepoint", "create_savepoint", True, False),
+    ("rollback_to_savepoint", "rollback_to_savepoint", True, False),
+    ("release_savepoint", "release_savepoint", True, False),
+    # Pool introspection
+    ("pool_backend", "pool_backend", True, False),
+    # Debug/introspection
+    ("render_sql", "render_sql", True, False),
+    ("render_sql_debug", "render_sql_debug", False, False),
+    ("explain", "explain_query", True, False),  # Renamed for API consistency
+    # Migrations
+    ("migration_compute_diff", "migration_compute_diff", False, False),
+    ("migration_to_sql", "migration_to_sql", False, False),
+    # Validation (no-op - not implemented in Rust, kept for compatibility)
+    ("register_validator", "register_validator", False, True),
+]
+
+
+def _make_stub(name: str, is_async: bool, is_noop: bool) -> Callable[..., Any]:
+    """Create a stub function that either raises RuntimeError or is a no-op."""
+    if is_noop:
+
+        def noop_stub(*args: Any, **kwargs: Any) -> None:
+            pass
+
+        noop_stub.__name__ = name
+        noop_stub.__doc__ = f"No-op stub for {name} (Rust module not available)"
+        return noop_stub
+
+    error_msg = (
+        f"Rust core module not available or missing '{name}'. "
+        "Please rebuild with: maturin develop --release"
+    )
+
+    if is_async:
+
+        async def async_stub(*args: Any, **kwargs: Any) -> Any:
+            raise RuntimeError(error_msg)
+
+        async_stub.__name__ = name
+        async_stub.__doc__ = f"Stub for {name} - raises RuntimeError"
+        return async_stub
+    else:
+
+        def sync_stub(*args: Any, **kwargs: Any) -> Any:
+            raise RuntimeError(error_msg)
+
+        sync_stub.__name__ = name
+        sync_stub.__doc__ = f"Stub for {name} - raises RuntimeError"
+        return sync_stub
+
+
+def _load_functions() -> dict[str, Callable[..., Any]]:
+    """Load functions from Rust module or create stubs."""
+    exports: dict[str, Callable[..., Any]] = {}
+
+    try:
+        import _oxyde_core  # type: ignore[import-untyped, import-not-found, unused-ignore]
+
+        # ABI version check
+        abi_version = getattr(_oxyde_core, "__abi_version__", None)
+        if abi_version is None:
+            raise ImportError("Rust core module does not expose __abi_version__")
+        if abi_version != EXPECTED_ABI_VERSION:
+            raise ImportError(
+                f"ABI version mismatch: expected {EXPECTED_ABI_VERSION}, "
+                f"got {abi_version}. Please reinstall oxyde-postgres-core."
+            )
+
+        # Load each function from registry
+        for rust_name, export_name, is_async, is_noop in _FUNCTION_REGISTRY:
+            if hasattr(_oxyde_core, rust_name):
+                exports[export_name] = getattr(_oxyde_core, rust_name)
+            else:
+                # Function missing in Rust module (older version?)
+                exports[export_name] = _make_stub(export_name, is_async, is_noop)
+
+    except ImportError as e:
+        print(f"Warning: Failed to import Rust core module: {e}", file=sys.stderr)
+        print("Oxyde ORM will not be fully functional.", file=sys.stderr)
+
+        # Create all stubs
+        for _, export_name, is_async, is_noop in _FUNCTION_REGISTRY:
+            exports[export_name] = _make_stub(export_name, is_async, is_noop)
+
+    return exports
+
+
+# Load functions once at module import
+_exports = _load_functions()
+
+# Export individual functions for IDE support and type checking
+execute = _exports["execute"]
+execute_in_transaction = _exports["execute_in_transaction"]
+init_pool = _exports["init_pool"]
+init_pool_overwrite = _exports["init_pool_overwrite"]
+close_pool = _exports["close_pool"]
+close_all_pools = _exports["close_all_pools"]
+begin_transaction = _exports["begin_transaction"]
+commit_transaction = _exports["commit_transaction"]
+rollback_transaction = _exports["rollback_transaction"]
+create_savepoint = _exports["create_savepoint"]
+rollback_to_savepoint = _exports["rollback_to_savepoint"]
+release_savepoint = _exports["release_savepoint"]
+register_validator = _exports["register_validator"]
+pool_backend = _exports["pool_backend"]
+render_sql = _exports["render_sql"]
+render_sql_debug = _exports["render_sql_debug"]
+explain_query = _exports["explain_query"]
+migration_compute_diff = _exports["migration_compute_diff"]
+migration_to_sql = _exports["migration_to_sql"]
+
+# ── Core exception classes ────────────────────────────────────────────────
+# Raised by the Rust core; constraint classification happens in the driver
+# (sqlx ErrorKind), never by matching error message text. Stubs keep
+# isinstance() checks working when the extension is unavailable.
+try:
+    from _oxyde_core import (  # type: ignore[import-untyped, import-not-found, unused-ignore]
+        CheckViolationError,
+        DatabaseError,
+        ForeignKeyViolationError,
+        IntegrityError,
+        NotNullViolationError,
+        UniqueViolationError,
+    )
+except ImportError:  # pragma: no cover - extension missing
+
+    class DatabaseError(RuntimeError):  # type: ignore[no-redef]
+        """Stub: Rust core module not available."""
+
+    class IntegrityError(DatabaseError):  # type: ignore[no-redef]
+        """Stub: Rust core module not available."""
+
+    class UniqueViolationError(IntegrityError):  # type: ignore[no-redef]
+        """Stub: Rust core module not available."""
+
+    class ForeignKeyViolationError(IntegrityError):  # type: ignore[no-redef]
+        """Stub: Rust core module not available."""
+
+    class NotNullViolationError(IntegrityError):  # type: ignore[no-redef]
+        """Stub: Rust core module not available."""
+
+    class CheckViolationError(IntegrityError):  # type: ignore[no-redef]
+        """Stub: Rust core module not available."""
+
+
+__all__ = [
+    "execute",
+    "execute_in_transaction",
+    "init_pool",
+    "init_pool_overwrite",
+    "close_pool",
+    "close_all_pools",
+    "begin_transaction",
+    "commit_transaction",
+    "rollback_transaction",
+    "create_savepoint",
+    "rollback_to_savepoint",
+    "release_savepoint",
+    "register_validator",
+    "pool_backend",
+    "render_sql",
+    "render_sql_debug",
+    "explain_query",
+    "migration_compute_diff",
+    "migration_to_sql",
+    "DatabaseError",
+    "IntegrityError",
+    "UniqueViolationError",
+    "ForeignKeyViolationError",
+    "NotNullViolationError",
+    "CheckViolationError",
+]