pyoq-sql 1.0.2__py3-none-any.whl

pyoq/query/sqlite/factory.py

@@ -0,0 +1,32 @@
+"""SQLite runtime connection creation."""
+
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass
+from pathlib import Path
+
+from pyoq.errors import ConnectionPoolError
+
+
+@dataclass(frozen=True, slots=True)
+class SQLiteConnectionFactory:
+    database: str | Path
+    uri: bool = False
+
+    def __call__(self) -> sqlite3.Connection:
+        try:
+            connection = sqlite3.connect(
+                str(self.database),
+                uri=self.uri,
+                check_same_thread=False,
+                isolation_level=None,
+            )
+        except sqlite3.Error as error:
+            message = f"unable to open SQLite connection: {error}"
+            raise ConnectionPoolError(message) from error
+        connection.row_factory = None
+        return connection
+
+
+__all__ = ("SQLiteConnectionFactory",)

pyoq/query/sqlite/health.py

@@ -0,0 +1,28 @@
+"""SQLite connection failure classification."""
+
+from __future__ import annotations
+
+import sqlite3
+
+_FATAL_PRIMARY_CODES = frozenset(
+    {
+        sqlite3.SQLITE_CANTOPEN,
+        sqlite3.SQLITE_CORRUPT,
+        sqlite3.SQLITE_IOERR,
+        sqlite3.SQLITE_NOTADB,
+    }
+)
+
+
+def is_connection_failure(error: sqlite3.Error) -> bool:
+    if isinstance(error, sqlite3.InterfaceError):
+        return True
+    if isinstance(error, sqlite3.ProgrammingError):
+        return "closed" in str(error).lower()
+    error_code = getattr(error, "sqlite_errorcode", None)
+    if not isinstance(error_code, int):
+        return False
+    return error_code & 0xFF in _FATAL_PRIMARY_CODES
+
+
+__all__ = ("is_connection_failure",)

pyoq/query/sqlite/identifiers.py

@@ -0,0 +1,9 @@
+"""SQLite identifier rendering."""
+
+from __future__ import annotations
+
+from pyoq.query.rendering.identifiers import IdentifierQuoting
+
+QUOTING = IdentifierQuoting("SQLite")
+
+__all__ = ("QUOTING",)

pyoq/query/sqlite/model.py

@@ -0,0 +1,73 @@
+"""SQLite compilation capabilities and immutable output."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pyoq.errors import QueryValidationError
+from pyoq.query.execution import CompiledQuery, ParameterStyle
+from pyoq.relations.planning import FetchCapabilities
+
+
+@dataclass(frozen=True, slots=True)
+class SQLiteCapabilities:
+    maximum_parameters: int = 999
+    parameter_style: ParameterStyle = ParameterStyle.QMARK
+    right_join: bool = False
+    full_join: bool = False
+    null_ordering: bool = True
+    lateral_sources: bool = False
+    recursive_common_tables: bool = True
+    raw_expressions: bool = True
+    # Ordering inside an aggregate needs SQLite 3.44 or later.
+    nested_collections: bool = True
+    ordered_nested_collections: bool = True
+    window_functions: bool = True
+    returning: bool = True
+    upsert: bool = True
+
+    @property
+    def fetch(self) -> FetchCapabilities:
+        """What this dialect can do when fetching a collection in one query."""
+        return FetchCapabilities(
+            self.nested_collections,
+            self.ordered_nested_collections,
+        )
+
+    def __post_init__(self) -> None:
+        if not _is_positive_integer(self.maximum_parameters):
+            message = "SQLite maximum parameters must be a positive integer"
+            raise QueryValidationError(message)
+        if not _is_parameter_style(self.parameter_style):
+            message = "SQLite parameter style must be a ParameterStyle value"
+            raise QueryValidationError(message)
+        feature_flags: tuple[object, ...] = (
+            self.right_join,
+            self.full_join,
+            self.null_ordering,
+            self.lateral_sources,
+            self.recursive_common_tables,
+            self.raw_expressions,
+            self.nested_collections,
+            self.ordered_nested_collections,
+            self.returning,
+            self.upsert,
+        )
+        if not _all_boolean(feature_flags):
+            message = "SQLite capability flags must be boolean"
+            raise QueryValidationError(message)
+
+
+def _is_parameter_style(value: object) -> bool:
+    return isinstance(value, ParameterStyle)
+
+
+def _is_positive_integer(value: object) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool) and value > 0
+
+
+def _all_boolean(values: tuple[object, ...]) -> bool:
+    return all(isinstance(value, bool) for value in values)
+
+
+__all__ = ("CompiledQuery", "SQLiteCapabilities")

pyoq/query/sqlite/operations.py

@@ -0,0 +1,36 @@
+"""SQLite typed result operations."""
+
+from __future__ import annotations
+
+import sqlite3
+from typing import cast
+
+from pyoq.query.execution import (
+    BulkPlan,
+    DatabaseCursor,
+    QueryOperations,
+    WriteProvider,
+)
+from pyoq.query.sqlite.compiler import SQLiteCompiler
+from pyoq.query.sqlite.planning import SQLiteBulkPlanner
+from pyoq.query.write_nodes import WriteNode
+
+
+class SQLiteQueryOperations(QueryOperations):
+    __slots__ = ("_compiler",)
+
+    def __init__(self, compiler: SQLiteCompiler) -> None:
+        self._compiler = compiler
+
+    @property
+    def compiler(self) -> SQLiteCompiler:
+        return self._compiler
+
+    def last_inserted_id(self, cursor: DatabaseCursor) -> int | None:
+        return cast("sqlite3.Cursor", cursor).lastrowid
+
+    def plan_bulk(self, statement: WriteProvider | WriteNode, /) -> BulkPlan:
+        return SQLiteBulkPlanner(self.compiler).plan(statement)
+
+
+__all__ = ("SQLiteQueryOperations",)

pyoq/query/sqlite/parameters.py

@@ -0,0 +1,50 @@
+"""SQLite driver parameter adaptation."""
+
+from __future__ import annotations
+
+import json
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal
+from enum import Enum
+from typing import cast
+from uuid import UUID
+
+from pyoq.errors import ParameterBindingError
+
+SQLiteParameter = str | int | float | bytes | None
+
+
+def adapt_parameters(values: tuple[object, ...]) -> tuple[SQLiteParameter, ...]:
+    return tuple(adapt_parameter(value) for value in values)
+
+
+def adapt_parameter(value: object) -> SQLiteParameter:
+    if value is None or isinstance(value, (str, int, float, bytes)):
+        return value
+    if isinstance(value, Decimal):
+        return str(value)
+    if isinstance(value, (datetime, date, time)):
+        return value.isoformat()
+    if isinstance(value, timedelta):
+        return value.total_seconds()
+    if isinstance(value, UUID):
+        return str(value)
+    if isinstance(value, memoryview):
+        return value.tobytes()
+    if isinstance(value, Enum):
+        return adapt_parameter(value.value)
+    if isinstance(value, (list, tuple, dict)):
+        return _json_parameter(cast(object, value))
+    message = f"unsupported SQLite parameter type: {type(value).__name__}"
+    raise ParameterBindingError(message)
+
+
+def _json_parameter(value: object) -> str:
+    try:
+        return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+    except (TypeError, ValueError) as error:
+        message = "SQLite JSON parameter is not serializable"
+        raise ParameterBindingError(message) from error
+
+
+__all__ = ("SQLiteParameter", "adapt_parameter", "adapt_parameters")

pyoq/query/sqlite/planning.py

@@ -0,0 +1,20 @@
+"""SQLite bulk write planning."""
+
+from __future__ import annotations
+
+from pyoq.query.execution.planning import BulkPlanner
+from pyoq.query.sqlite.compiler import SQLiteCompiler
+
+
+class SQLiteBulkPlanner(BulkPlanner):
+    __slots__ = ()
+
+    def __init__(self, compiler: SQLiteCompiler) -> None:
+        super().__init__(
+            compiler,
+            compiler.capabilities.maximum_parameters,
+            "SQLite",
+        )
+
+
+__all__ = ("SQLiteBulkPlanner",)

pyoq/query/sqlite/pool.py

@@ -0,0 +1,50 @@
+"""Exclusive synchronous SQLite connection pool."""
+
+from __future__ import annotations
+
+import sqlite3
+from collections.abc import Callable
+from typing import TypeAlias
+
+from pyoq.errors import ConnectionPoolError
+from pyoq.query.execution.pooling import (
+    ConnectionLease,
+    ConnectionPool,
+    PoolPolicy,
+    PoolStats,
+)
+
+SQLiteConnectionFactoryProtocol = Callable[[], sqlite3.Connection]
+SQLiteConnectionLease: TypeAlias = ConnectionLease[sqlite3.Connection]
+SQLitePoolPolicy: TypeAlias = PoolPolicy
+SQLitePoolStats: TypeAlias = PoolStats
+
+
+class SQLitePool(ConnectionPool[sqlite3.Connection]):
+    __slots__ = ()
+
+    def reset(self, connection: sqlite3.Connection) -> bool:
+        try:
+            if connection.in_transaction:
+                connection.rollback()
+        except sqlite3.Error:
+            return False
+        return True
+
+    def validate(self, value: object) -> sqlite3.Connection:
+        if not isinstance(value, sqlite3.Connection):
+            message = "SQLite connection factory returned an invalid connection"
+            raise ConnectionPoolError(message)
+        return value
+
+    def dispose(self, connection: sqlite3.Connection) -> None:
+        connection.close()
+
+
+__all__ = (
+    "SQLiteConnectionFactoryProtocol",
+    "SQLiteConnectionLease",
+    "SQLitePool",
+    "SQLitePoolPolicy",
+    "SQLitePoolStats",
+)

pyoq/query/sqlite/streaming.py

@@ -0,0 +1,13 @@
+"""Bounded synchronous SQLite row streaming."""
+
+from __future__ import annotations
+
+from typing import TypeAlias
+
+from pyoq.query.execution.streaming import RowStream, StreamPolicy, StreamResource
+
+SQLiteStreamPolicy: TypeAlias = StreamPolicy
+SQLiteStreamResource: TypeAlias = StreamResource
+SQLiteRowStream = RowStream
+
+__all__ = ("SQLiteRowStream", "SQLiteStreamPolicy", "SQLiteStreamResource")

pyoq/query/sqlite/transactions.py

@@ -0,0 +1,274 @@
+"""Owned SQLite transactions and nested savepoints."""
+
+from __future__ import annotations
+
+import sqlite3
+from collections.abc import Callable
+from enum import Enum
+from typing import TypeVar, cast
+
+from pyoq.errors import ExecutionError, QueryValidationError, TransactionStateError
+from pyoq.query.execution import ExecutionControl, TransactionState
+from pyoq.query.select import Query
+from pyoq.query.sqlite.commands import open_cursor, run_sql
+from pyoq.query.sqlite.compiler import SQLiteCompiler
+from pyoq.query.sqlite.model import CompiledQuery
+from pyoq.query.sqlite.operations import SQLiteQueryOperations
+from pyoq.query.sqlite.parameters import adapt_parameters
+from pyoq.query.sqlite.pool import SQLitePool
+from pyoq.query.sqlite.streaming import (
+    SQLiteRowStream,
+    SQLiteStreamPolicy,
+    SQLiteStreamResource,
+)
+
+_SQLiteTransactionState = TransactionState[sqlite3.Connection, "SQLiteTransaction"]
+
+OperationResult = TypeVar("OperationResult")
+ResultRow = TypeVar("ResultRow")
+
+
+class TransactionMode(Enum):
+    DEFERRED = "DEFERRED"
+    IMMEDIATE = "IMMEDIATE"
+    EXCLUSIVE = "EXCLUSIVE"
+
+
+class SQLiteTransaction(SQLiteQueryOperations):
+    __slots__ = (
+        "_control",
+        "_entered",
+        "_finished",
+        "_mode",
+        "_parent",
+        "_pool",
+        "_savepoint_name",
+        "_state",
+    )
+
+    def __init__(
+        self,
+        pool: SQLitePool,
+        compiler: SQLiteCompiler,
+        mode: TransactionMode = TransactionMode.DEFERRED,
+        control: ExecutionControl | None = None,
+        *,
+        parent: SQLiteTransaction | None = None,
+        state: _SQLiteTransactionState | None = None,
+    ) -> None:
+        super().__init__(compiler)
+        if not _is_transaction_mode(mode):
+            raise QueryValidationError("SQLite transaction mode is invalid")
+        self._pool = pool
+        self._mode = mode
+        self._control = control
+        self._parent = parent
+        self._state = state or _SQLiteTransactionState()
+        self._savepoint_name: str | None = None
+        self._entered = False
+        self._finished = False
+
+    def __enter__(self) -> SQLiteTransaction:
+        if self._entered or self._finished:
+            raise TransactionStateError("SQLite transaction cannot be entered twice")
+        if self._parent is None:
+            self._enter_outer()
+        else:
+            self._enter_savepoint()
+        self._entered = True
+        return self
+
+    def __exit__(
+        self,
+        exception_type: type[BaseException] | None,
+        exception: BaseException | None,
+        traceback: object,
+    ) -> None:
+        if not self._entered or self._finished:
+            return
+        if self._parent is None:
+            self._exit_outer(exception_type)
+        else:
+            self._exit_savepoint(exception_type)
+
+    def savepoint(
+        self,
+        *,
+        control: ExecutionControl | None = None,
+    ) -> SQLiteTransaction:
+        self._state.require_current(self)
+        return SQLiteTransaction(
+            self._pool,
+            self.compiler,
+            self._mode,
+            control or self._control,
+            parent=self,
+            state=self._state,
+        )
+
+    def stream(
+        self,
+        query: Query[ResultRow],
+        /,
+        *,
+        policy: SQLiteStreamPolicy | None = None,
+    ) -> SQLiteRowStream[ResultRow]:
+        self._state.require_current(self)
+        selected_policy = policy or SQLiteStreamPolicy(control=self._control)
+        if selected_policy.control is None and self._control is not None:
+            selected_policy = SQLiteStreamPolicy(
+                selected_policy.batch_size,
+                self._control,
+            )
+        statement = self.compiler.compile(query)
+        stream: SQLiteRowStream[ResultRow]
+        stream = SQLiteRowStream(
+            lambda: self._open_stream(stream, statement, selected_policy),
+            selected_policy,
+            statement.row_types,
+        )
+        return stream
+
+    def _run(
+        self,
+        statement: CompiledQuery,
+        operation: Callable[[sqlite3.Cursor], OperationResult],
+        control: ExecutionControl | None,
+    ) -> OperationResult:
+        parameters = adapt_parameters(statement.parameters)
+        connection = self._state.require_current(self)
+        return run_sql(
+            connection,
+            statement.sql,
+            parameters,
+            operation,
+            control or self._control,
+            self._state.invalidate,
+        )
+
+    def _enter_outer(self) -> None:
+        self._state.adopt(self._pool.checkout(), self)
+        try:
+            self._run_transaction_sql(f"BEGIN {self._mode.value}")
+        except BaseException:
+            self._release_outer()
+            raise
+
+    def _enter_savepoint(self) -> None:
+        self._state.require_current(cast(SQLiteTransaction, self._parent))
+        name = self._state.next_savepoint()
+        self._run_transaction_sql(f'SAVEPOINT "{name}"', scope=self._parent)
+        self._savepoint_name = name
+        self._state.current_scope = self
+
+    def _exit_outer(self, exception_type: type[BaseException] | None) -> None:
+        try:
+            self._state.require_scope(self)
+        except TransactionStateError:
+            self._abort_misnested_outer(exception_type)
+            return
+        self._state.close_stream()
+        command = "ROLLBACK" if exception_type is not None else "COMMIT"
+        try:
+            if not self._state.broken:
+                self._run_transaction_sql(command)
+        except ExecutionError:
+            self._state.invalidate()
+            if exception_type is None:
+                raise
+        finally:
+            self._release_outer()
+
+    def _exit_savepoint(self, exception_type: type[BaseException] | None) -> None:
+        self._state.require_scope(self)
+        self._state.close_stream()
+        name = cast(str, self._savepoint_name)
+        try:
+            self._finish_savepoint(name, exception_type)
+        except ExecutionError:
+            self._state.invalidate()
+            if exception_type is None:
+                raise
+        finally:
+            self._state.current_scope = self._parent
+            self._finished = True
+
+    def _finish_savepoint(
+        self,
+        name: str,
+        exception_type: type[BaseException] | None,
+    ) -> None:
+        if self._state.broken:
+            return
+        if exception_type is not None:
+            self._run_transaction_sql(f'ROLLBACK TO SAVEPOINT "{name}"')
+        self._run_transaction_sql(f'RELEASE SAVEPOINT "{name}"')
+
+    def _run_transaction_sql(
+        self,
+        sql: str,
+        *,
+        scope: SQLiteTransaction | None = None,
+    ) -> None:
+        connection = self._state.require_current(scope or self, allow_stream=True)
+        run_sql(
+            connection,
+            sql,
+            (),
+            _discard_cursor,
+            self._control,
+            self._state.invalidate,
+        )
+
+    def _open_stream(
+        self,
+        stream: SQLiteRowStream[ResultRow],
+        statement: CompiledQuery,
+        policy: SQLiteStreamPolicy,
+    ) -> SQLiteStreamResource:
+        parameters = adapt_parameters(statement.parameters)
+        connection = self._state.require_current(self)
+        session = open_cursor(
+            connection,
+            statement.sql,
+            parameters,
+            policy.control,
+            self._state.invalidate,
+        )
+        stored_stream = cast(SQLiteRowStream[object], stream)
+        self._state.active_stream = stored_stream
+        return SQLiteStreamResource(
+            session,
+            self._state.release_stream,
+        )
+
+    def _release_outer(self) -> None:
+        self._finished = True
+        self._state.release()
+
+    def _abort_misnested_outer(
+        self,
+        exception_type: type[BaseException] | None,
+    ) -> None:
+        connection = self._state.require_owner()
+        self._state.close_stream()
+        try:
+            connection.rollback()
+        except sqlite3.Error:
+            self._state.invalidate()
+        finally:
+            self._release_outer()
+        if exception_type is None:
+            message = "SQLite transaction exited with an active nested savepoint"
+            raise TransactionStateError(message)
+
+
+def _discard_cursor(cursor: sqlite3.Cursor) -> None:
+    del cursor
+
+
+def _is_transaction_mode(value: object) -> bool:
+    return isinstance(value, TransactionMode)
+
+
+__all__ = ("SQLiteTransaction", "TransactionMode")

pyoq/query/sqlite/writes.py

@@ -0,0 +1,35 @@
+"""SQLite write statement compilation."""
+
+from __future__ import annotations
+
+from pyoq.errors import UnsupportedQueryError
+from pyoq.query.rendering.identifiers import IdentifierQuoting
+from pyoq.query.rendering.writes import WriteRenderer
+from pyoq.query.sqlite.context import SQLiteCompilationContext
+from pyoq.query.sqlite.expressions import SQLiteExpressionCompiler
+from pyoq.query.sqlite.identifiers import QUOTING
+
+
+class SQLiteWriteCompilation(WriteRenderer):
+    __slots__ = ("_context",)
+
+    def __init__(self, context: SQLiteCompilationContext) -> None:
+        self._context = context
+        super().__init__(SQLiteExpressionCompiler(context))
+
+    @property
+    def quoting(self) -> IdentifierQuoting:
+        return QUOTING
+
+    def require_returning(self) -> None:
+        if not self._context.capabilities.returning:
+            message = "SQLite RETURNING is disabled by compiler capabilities"
+            raise UnsupportedQueryError(message)
+
+    def require_conflict_resolution(self) -> None:
+        if not self._context.capabilities.upsert:
+            message = "SQLite conflict resolution is disabled by compiler capabilities"
+            raise UnsupportedQueryError(message)
+
+
+__all__ = ("SQLiteWriteCompilation",)

pyoq/query/statements.py

@@ -0,0 +1,27 @@
+"""Dialect-neutral statement contracts shared by every compiler."""
+
+from __future__ import annotations
+
+from typing import Protocol, TypeAlias
+
+from pyoq.query.execution import CompiledQuery
+from pyoq.query.select_nodes import QueryNode
+from pyoq.query.write_nodes import CallNode, WriteNode
+
+StatementNode: TypeAlias = QueryNode | WriteNode | CallNode
+
+
+class StatementProvider(Protocol):
+    @property
+    def node(self) -> StatementNode: ...
+
+
+class StatementCompiler(Protocol):
+    def compile(
+        self,
+        statement: StatementProvider | StatementNode,
+        /,
+    ) -> CompiledQuery: ...
+
+
+__all__ = ("StatementCompiler", "StatementNode", "StatementProvider")

pyoq/query/values.py

@@ -0,0 +1,23 @@
+"""Bound query values and scalar family resolution."""
+
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+from pyoq.query.expressions import Expression, family_for_value
+from pyoq.query.nodes import BoundValueNode
+
+Value = TypeVar("Value")
+InputValue = TypeVar("InputValue")
+
+
+class BoundValue(Expression[Value], Generic[Value]):
+    __slots__ = ()
+
+
+def bind(value: InputValue, /, *, sensitive: bool = False) -> BoundValue[InputValue]:
+    family = family_for_value(value)
+    return BoundValue(BoundValueNode(value, family, sensitive), family)
+
+
+__all__ = ("BoundValue", "bind")