pyoq-sql 1.0.2__py3-none-any.whl

pyoq/dsl/writes.py

@@ -0,0 +1,360 @@
+"""Writes that know which database they belong to.
+
+The same split as the queries: a statement is still described by the builder
+that cannot reach a database, and these carry one alongside the operations it
+will run against.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Generic, TypeVar, TypeVarTuple, cast, overload
+
+from pyoq.dsl.labels import labels_of
+from pyoq.dsl.result import Result, Row
+from pyoq.query.write_nodes import WriteNode
+from pyoq.query.writes import (
+    ConflictUpdate,
+    DeleteStatement,
+    InsertStatement,
+    MutationStatement,
+    ReturningStatement,
+    UpdateStatement,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable
+
+    from pyoq.query.execution import QueryOperations
+    from pyoq.query.expressions import Expression
+    from pyoq.query.writes import ColumnReference
+
+Values = TypeVarTuple("Values")
+Mutation = TypeVar("Mutation", bound=MutationStatement[WriteNode])
+ResultRow = TypeVar("ResultRow", bound=tuple[object, ...])
+Mapped = TypeVar("Mapped")
+ScalarValue = TypeVar("ScalarValue")
+Value1 = TypeVar("Value1")
+Value2 = TypeVar("Value2")
+Value3 = TypeVar("Value3")
+Value4 = TypeVar("Value4")
+Value5 = TypeVar("Value5")
+Value6 = TypeVar("Value6")
+Value7 = TypeVar("Value7")
+Value8 = TypeVar("Value8")
+AssignedValue = TypeVar("AssignedValue")
+
+
+class BoundReturning(Generic[ResultRow]):
+    """Rows a write handed back, read the way a query's rows are read."""
+
+    __slots__ = ("_operations", "_statement")
+    _operations: QueryOperations
+    _statement: ReturningStatement[ResultRow]
+
+    def __init__(
+        self,
+        operations: QueryOperations,
+        statement: ReturningStatement[ResultRow],
+    ) -> None:
+        object.__setattr__(self, "_operations", operations)
+        object.__setattr__(self, "_statement", statement)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        message = f"{type(self).__name__} is immutable"
+        raise AttributeError(message, name, value)
+
+    @property
+    def statement(self) -> ReturningStatement[ResultRow]:
+        """The statement on its own, which cannot reach a database."""
+        return self._statement
+
+    def fetch_all(self) -> Result[ResultRow]:
+        rows = tuple(self._operations.many(self._statement))
+        return Result(rows, labels_of(self._statement.node.returning))
+
+    def fetch_one(self) -> Row[ResultRow]:
+        """Exactly one row, because that is what the caller said to expect."""
+        return Row(
+            self._operations.one(self._statement),
+            labels_of(self._statement.node.returning),
+        )
+
+    def fetch_optional(self) -> Row[ResultRow] | None:
+        row = self._operations.one_or_none(self._statement)
+        return (
+            None if row is None else Row(row, labels_of(self._statement.node.returning))
+        )
+
+    def fetch_optional_into(
+        self,
+        factory: Callable[..., Mapped],
+        /,
+    ) -> Mapped | None:
+        """One row built by the caller's own type, or nothing.
+
+        The row and the many-row result both take a factory inline.
+        A row that may be missing had to be tested for first, which
+        is the one shape that could not be asked for in the chain.
+        """
+        row = self.fetch_optional()
+        return None if row is None else row.into(factory)
+
+    def fetch_value(self: BoundReturning[tuple[ScalarValue]], /) -> ScalarValue:
+        return self._operations.scalar(self._statement)
+
+
+class BoundMutation(Generic[Mutation]):
+    """What every bound write can do, whatever it is writing."""
+
+    __slots__ = ("_operations", "_statement")
+    _operations: QueryOperations
+    _statement: Mutation
+
+    def __init__(self, operations: QueryOperations, statement: Mutation) -> None:
+        object.__setattr__(self, "_operations", operations)
+        object.__setattr__(self, "_statement", statement)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        message = f"{type(self).__name__} is immutable"
+        raise AttributeError(message, name, value)
+
+    @property
+    def statement(self) -> Mutation:
+        """The statement on its own, which cannot reach a database."""
+        return self._statement
+
+    def execute(self) -> int:
+        """How many rows the database says it wrote."""
+        return self._operations.execute(self._statement).rows_affected
+
+    def returning_all(self) -> BoundReturning[tuple[object, ...]]:
+        """Every column the table declares, without listing them."""
+        return BoundReturning(self._operations, self._statement.returning_all())
+
+    @overload
+    def returning(
+        self,
+        value1: Expression[Value1],
+        /,
+    ) -> BoundReturning[tuple[Value1]]: ...
+
+    @overload
+    def returning(
+        self,
+        value1: Expression[Value1],
+        value2: Expression[Value2],
+        /,
+    ) -> BoundReturning[tuple[Value1, Value2]]: ...
+
+    @overload
+    def returning(
+        self,
+        value1: Expression[Value1],
+        value2: Expression[Value2],
+        value3: Expression[Value3],
+        /,
+    ) -> BoundReturning[tuple[Value1, Value2, Value3]]: ...
+
+    @overload
+    def returning(
+        self,
+        value1: Expression[Value1],
+        value2: Expression[Value2],
+        value3: Expression[Value3],
+        value4: Expression[Value4],
+        /,
+    ) -> BoundReturning[tuple[Value1, Value2, Value3, Value4]]: ...
+
+    @overload
+    def returning(
+        self,
+        value1: Expression[Value1],
+        value2: Expression[Value2],
+        value3: Expression[Value3],
+        value4: Expression[Value4],
+        value5: Expression[Value5],
+        /,
+    ) -> BoundReturning[tuple[Value1, Value2, Value3, Value4, Value5]]: ...
+
+    @overload
+    def returning(
+        self,
+        value1: Expression[Value1],
+        value2: Expression[Value2],
+        value3: Expression[Value3],
+        value4: Expression[Value4],
+        value5: Expression[Value5],
+        value6: Expression[Value6],
+        /,
+    ) -> BoundReturning[tuple[Value1, Value2, Value3, Value4, Value5, Value6]]: ...
+
+    @overload
+    def returning(
+        self,
+        value1: Expression[Value1],
+        value2: Expression[Value2],
+        value3: Expression[Value3],
+        value4: Expression[Value4],
+        value5: Expression[Value5],
+        value6: Expression[Value6],
+        value7: Expression[Value7],
+        /,
+    ) -> BoundReturning[
+        tuple[Value1, Value2, Value3, Value4, Value5, Value6, Value7]
+    ]: ...
+
+    @overload
+    def returning(
+        self,
+        value1: Expression[Value1],
+        value2: Expression[Value2],
+        value3: Expression[Value3],
+        value4: Expression[Value4],
+        value5: Expression[Value5],
+        value6: Expression[Value6],
+        value7: Expression[Value7],
+        value8: Expression[Value8],
+        /,
+    ) -> BoundReturning[
+        tuple[Value1, Value2, Value3, Value4, Value5, Value6, Value7, Value8]
+    ]: ...
+
+    @overload
+    def returning(
+        self,
+        value1: object,
+        value2: object,
+        value3: object,
+        value4: object,
+        value5: object,
+        value6: object,
+        value7: object,
+        value8: object,
+        /,
+        *values: object,
+    ) -> BoundReturning[tuple[object, ...]]:
+        """Wider than the overloads above name, where the types stop.
+
+        A statement is still a statement past eight returned columns,
+        and matching no overload would take the whole chain down with
+        it rather than just the tuple.
+        """
+
+    def returning(  # type: ignore[misc]
+        self,
+        *values: object,
+    ) -> BoundReturning[tuple[object, ...]]:
+        # The builder declares typed overloads for callers; this is the one
+        # implementation behind them, reached variadically. The overloads above
+        # are what a caller sees, and they carry the types across.
+        build = cast(
+            "Callable[..., ReturningStatement[tuple[object, ...]]]",
+            self._statement.returning,
+        )
+        return BoundReturning(self._operations, build(*values))
+
+
+class BoundInsert(BoundMutation[InsertStatement[*Values]], Generic[*Values]):
+    """An INSERT and the database it will run against."""
+
+    __slots__ = ()
+
+    def values(self, *values: *Values) -> BoundInsert[*Values]:
+        return BoundInsert(self._operations, self._statement.values(*values))
+
+    def values_many(self, rows: Iterable[object], /) -> BoundInsert[*Values]:
+        return BoundInsert(self._operations, self._statement.values_many(rows))
+
+    def on_conflict_do_nothing(
+        self,
+        *columns: ColumnReference,
+    ) -> BoundInsert[*Values]:
+        return BoundInsert(
+            self._operations,
+            self._statement.on_conflict_do_nothing(*columns),
+        )
+
+    def on_conflict_do_update(
+        self,
+        *columns: ColumnReference,
+    ) -> BoundConflictUpdate[*Values]:
+        return BoundConflictUpdate(
+            self._operations,
+            self._statement.on_conflict_do_update(*columns),
+        )
+
+
+class BoundConflictUpdate(
+    BoundMutation[ConflictUpdate[*Values]],
+    Generic[*Values],
+):
+    """The SET and WHERE that belong to a conflict clause."""
+
+    __slots__ = ()
+
+    def set(
+        self,
+        column: Expression[AssignedValue],
+        value: AssignedValue | Expression[AssignedValue],
+        /,
+    ) -> BoundConflictUpdate[*Values]:
+        return BoundConflictUpdate(self._operations, self._statement.set(column, value))
+
+    def where(
+        self,
+        condition: Expression[bool],
+        /,
+    ) -> BoundConflictUpdate[*Values]:
+        return BoundConflictUpdate(self._operations, self._statement.where(condition))
+
+
+class BoundUpdate(BoundMutation[UpdateStatement]):
+    """An UPDATE, which has to say which rows it means."""
+
+    __slots__ = ()
+
+    def set(
+        self,
+        column: Expression[AssignedValue],
+        value: AssignedValue | Expression[AssignedValue],
+        /,
+    ) -> BoundUpdate:
+        return BoundUpdate(self._operations, self._statement.set(column, value))
+
+    def set_values(
+        self,
+        values: object,
+        /,
+        *columns: ColumnReference,
+    ) -> BoundUpdate:
+        return BoundUpdate(
+            self._operations, self._statement.set_values(values, *columns)
+        )
+
+    def where(self, condition: Expression[bool], /) -> BoundUpdate:
+        return BoundUpdate(self._operations, self._statement.where(condition))
+
+    def all_rows(self) -> BoundUpdate:
+        return BoundUpdate(self._operations, self._statement.all_rows())
+
+
+class BoundDelete(BoundMutation[DeleteStatement]):
+    """A DELETE, which has to say which rows it means."""
+
+    __slots__ = ()
+
+    def where(self, condition: Expression[bool], /) -> BoundDelete:
+        return BoundDelete(self._operations, self._statement.where(condition))
+
+    def all_rows(self) -> BoundDelete:
+        return BoundDelete(self._operations, self._statement.all_rows())
+
+
+__all__ = (
+    "BoundConflictUpdate",
+    "BoundDelete",
+    "BoundInsert",
+    "BoundMutation",
+    "BoundReturning",
+    "BoundUpdate",
+)

pyoq/errors.py

@@ -0,0 +1,317 @@
+"""Public exception hierarchy."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pyoq.naming import NameCollision
+
+
+class PyOQError(Exception):
+    """Base class for package errors."""
+
+
+class ConfigurationError(PyOQError):
+    """Base class for configuration failures."""
+
+
+class ConfigurationFileError(ConfigurationError):
+    """Raised when a configuration file cannot be read or parsed."""
+
+
+class ConfigurationValidationError(ConfigurationError, ValueError):
+    """Raised when configuration values violate the public contract."""
+
+
+class UnknownConfigurationSettingError(ConfigurationValidationError):
+    """Raised when a configuration table contains unsupported settings."""
+
+
+class PathContainmentError(ConfigurationValidationError):
+    """Raised when a configured path escapes its project root."""
+
+
+class SecretResolutionError(ConfigurationError, LookupError):
+    """Raised when a referenced secret is unavailable."""
+
+
+class RuntimeSelectionError(PyOQError, ValueError):
+    """Raised when runtime selection is invalid."""
+
+
+class NativeRuntimeUnavailableError(PyOQError, ImportError):
+    """Raised when native execution is required but unavailable."""
+
+
+class CommandError(PyOQError):
+    """Base class for command execution failures."""
+
+
+class OperationUnavailableError(CommandError):
+    """Raised when a command's service is not implemented."""
+
+
+class SchemaError(PyOQError):
+    """Base class for schema model failures."""
+
+
+class SchemaValidationError(SchemaError, ValueError):
+    """Raised when schema metadata violates model invariants."""
+
+
+class SchemaDriftError(SchemaError):
+    """Raised when a recorded schema no longer matches the database."""
+
+
+class SchemaSerializationError(SchemaError, ValueError):
+    """Raised when serialized schema metadata is invalid."""
+
+
+class SchemaInspectionError(SchemaError, CommandError):
+    """Raised when database metadata cannot be inspected safely."""
+
+
+class HydrationError(PyOQError):
+    """Base class for row hydration failures."""
+
+
+class RowIdentityError(HydrationError, ValueError):
+    """Raised when a result row cannot be identified."""
+
+
+class CollectionDecodeError(HydrationError, ValueError):
+    """Raised when a nested collection does not hold what it promised."""
+
+
+class RelationError(PyOQError):
+    """Base class for relation graph failures."""
+
+
+class RelationResolutionError(RelationError, LookupError):
+    """Raised when a relation names a table the graph does not hold."""
+
+
+class RelationNotLoadedError(RelationError):
+    """Raised when a relation that was never fetched is read."""
+
+
+class FetchPlanError(RelationError, ValueError):
+    """Raised when a fetch plan does not describe a possible fetch."""
+
+
+class NamingError(PyOQError):
+    """Base class for generated-name failures."""
+
+
+class NamingValidationError(NamingError, ValueError):
+    """Raised when a naming request violates the public contract."""
+
+
+class NamingCollisionError(NamingError):
+    """Raised with every generated-name collision in a naming batch."""
+
+    collisions: tuple[NameCollision, ...]
+
+    def __init__(
+        self,
+        message: str,
+        collisions: tuple[NameCollision, ...],
+    ) -> None:
+        super().__init__(message)
+        self.collisions = collisions
+
+
+class GenerationError(CommandError):
+    """Base class for generation pipeline failures."""
+
+
+class GenerationValidationError(GenerationError, ValueError):
+    """Raised when planned generated output is invalid."""
+
+
+class GenerationManifestError(GenerationError, ValueError):
+    """Raised when an ownership manifest is malformed or incompatible."""
+
+
+class GenerationOwnershipError(GenerationError):
+    """Raised when generation would modify a file it does not own."""
+
+
+class GenerationLockError(GenerationError):
+    """Raised when another generation operation owns the project lock."""
+
+
+class GenerationDriftError(GenerationError):
+    """Raised when checked generated output differs from its plan."""
+
+
+class GenerationWriteError(GenerationError):
+    """Raised when an atomic package replacement cannot complete safely."""
+
+
+class ExpressionError(PyOQError):
+    """Base class for query expression failures."""
+
+
+class ExpressionTypeError(ExpressionError, TypeError):
+    """Raised when expression operands are not compatible."""
+
+
+class RawExpressionError(ExpressionError, ValueError):
+    """Raised when an explicit raw expression template is invalid."""
+
+
+class QueryError(PyOQError):
+    """Base class for query model failures."""
+
+
+class QueryStateError(QueryError):
+    """Raised when a clause conflicts with the current query state."""
+
+
+class QueryBudgetExceededError(QueryError):
+    """Raised when a scope asks a database to do more than it was allowed."""
+
+
+class PolicyViolationError(PyOQError):
+    """A statement asked for something its policies do not allow."""
+
+
+class QueryValidationError(QueryError, ValueError):
+    """Raised when query structure violates a public invariant."""
+
+
+class CompilationError(QueryError):
+    """Base class for SQL compilation failures."""
+
+
+class UnsupportedQueryError(CompilationError):
+    """Raised when a query requires an unavailable dialect capability."""
+
+
+class ParameterLimitError(CompilationError):
+    """Raised when a compiled statement exceeds its parameter budget."""
+
+
+class ExecutionError(QueryError):
+    """Base class for query execution failures."""
+
+
+class QueryExecutionError(ExecutionError):
+    """Raised when a database driver cannot execute a query."""
+
+
+class QueryTimeoutError(ExecutionError, TimeoutError):
+    """Raised when query execution exceeds its configured duration."""
+
+
+class QueryCancelledError(ExecutionError):
+    """Raised when cooperative query cancellation is requested."""
+
+
+class ParameterBindingError(ExecutionError, TypeError):
+    """Raised when a value cannot be represented by a database driver."""
+
+
+class ResultCardinalityError(ExecutionError):
+    """Base class for result cardinality failures."""
+
+
+class NoResultError(ResultCardinalityError):
+    """Raised when exactly one row was required but none was returned."""
+
+
+class MultipleResultsError(ResultCardinalityError):
+    """Raised when at most one row was required but several were returned."""
+
+
+class ConnectionPoolError(ExecutionError):
+    """Base class for connection pool failures."""
+
+
+class ConnectionPoolClosedError(ConnectionPoolError):
+    """Raised when checkout is attempted after pool closure."""
+
+
+class ConnectionPoolTimeoutError(ConnectionPoolError, TimeoutError):
+    """Raised when a connection cannot be checked out within its budget."""
+
+
+class TransactionError(ExecutionError):
+    """Base class for transaction failures."""
+
+
+class TransactionStateError(TransactionError):
+    """Raised when a transaction operation violates ownership or state."""
+
+
+class StreamError(ExecutionError):
+    """Base class for streaming failures."""
+
+
+class StreamStateError(StreamError):
+    """Raised when a row stream violates its lifecycle or ownership contract."""
+
+
+__all__ = (
+    "CollectionDecodeError",
+    "CommandError",
+    "CompilationError",
+    "ConfigurationError",
+    "ConfigurationFileError",
+    "ConfigurationValidationError",
+    "ConnectionPoolClosedError",
+    "ConnectionPoolError",
+    "ConnectionPoolTimeoutError",
+    "ExecutionError",
+    "ExpressionError",
+    "ExpressionTypeError",
+    "FetchPlanError",
+    "GenerationDriftError",
+    "GenerationError",
+    "GenerationLockError",
+    "GenerationManifestError",
+    "GenerationOwnershipError",
+    "GenerationValidationError",
+    "GenerationWriteError",
+    "HydrationError",
+    "MultipleResultsError",
+    "NamingCollisionError",
+    "NamingError",
+    "NamingValidationError",
+    "NativeRuntimeUnavailableError",
+    "NoResultError",
+    "OperationUnavailableError",
+    "ParameterBindingError",
+    "ParameterLimitError",
+    "PathContainmentError",
+    "PolicyViolationError",
+    "PyOQError",
+    "QueryBudgetExceededError",
+    "QueryCancelledError",
+    "QueryError",
+    "QueryExecutionError",
+    "QueryStateError",
+    "QueryTimeoutError",
+    "QueryValidationError",
+    "RawExpressionError",
+    "RelationError",
+    "RelationNotLoadedError",
+    "RelationResolutionError",
+    "ResultCardinalityError",
+    "RowIdentityError",
+    "RuntimeSelectionError",
+    "SchemaDriftError",
+    "SchemaError",
+    "SchemaInspectionError",
+    "SchemaSerializationError",
+    "SchemaValidationError",
+    "SecretResolutionError",
+    "StreamError",
+    "StreamStateError",
+    "TransactionError",
+    "TransactionStateError",
+    "UnknownConfigurationSettingError",
+    "UnsupportedQueryError",
+)

pyoq/fastapi/__init__.py

@@ -0,0 +1,32 @@
+"""Running PyOQ inside a FastAPI application."""
+
+from pyoq.fastapi.dependencies import (
+    async_database,
+    async_scoped,
+    async_transaction,
+    database,
+    scoped,
+    transaction,
+)
+from pyoq.fastapi.lifespan import database_lifespan, databases_of
+from pyoq.serving import (
+    DEFAULT,
+    AsyncDatabase,
+    Databases,
+    SyncDatabase,
+)
+
+__all__ = (
+    "DEFAULT",
+    "AsyncDatabase",
+    "Databases",
+    "SyncDatabase",
+    "async_database",
+    "async_scoped",
+    "async_transaction",
+    "database",
+    "database_lifespan",
+    "databases_of",
+    "scoped",
+    "transaction",
+)