pyoq-sql 1.0.2__py3-none-any.whl

pyoq/query/select_nodes.py

@@ -0,0 +1,277 @@
+"""Immutable structural nodes for SELECT queries."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TypeAlias
+
+from pyoq.query.nodes import ExpressionNode, NamedWindowNode
+
+
+class JoinKind(StrEnum):
+    INNER = "inner"
+    LEFT = "left"
+    RIGHT = "right"
+    FULL = "full"
+    CROSS = "cross"
+
+
+class OrderDirection(StrEnum):
+    ASCENDING = "ascending"
+    DESCENDING = "descending"
+
+
+class NullOrder(StrEnum):
+    FIRST = "first"
+    LAST = "last"
+
+
+class SetOperator(StrEnum):
+    UNION = "union"
+    UNION_ALL = "union-all"
+    INTERSECT = "intersect"
+    EXCEPT = "except"
+
+
+@dataclass(frozen=True, slots=True)
+class TableSourceNode:
+    name: str
+    schema: str | None = None
+    catalog: str | None = None
+    alias: str | None = None
+
+    def __post_init__(self) -> None:
+        _require_identifier(self.name, "table")
+        _require_optional_identifier(self.schema, "schema")
+        _require_optional_identifier(self.catalog, "catalog")
+        _require_optional_identifier(self.alias, "table alias")
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectionNode:
+    expression: ExpressionNode
+    alias: str | None = None
+
+    def __post_init__(self) -> None:
+        _require_optional_identifier(self.alias, "projection alias")
+
+
+@dataclass(frozen=True, slots=True)
+class OrderNode:
+    expression: ExpressionNode
+    direction: OrderDirection
+    nulls: NullOrder | None = None
+
+
+class LockStrength(StrEnum):
+    """How much of a row a lock holds, from the whole row down to its key."""
+
+    UPDATE = "update"
+    NO_KEY_UPDATE = "no-key-update"
+    SHARE = "share"
+    KEY_SHARE = "key-share"
+
+
+class LockWait(StrEnum):
+    """What a statement does about rows somebody else has already locked."""
+
+    WAIT = "wait"
+    NOWAIT = "nowait"
+    SKIP_LOCKED = "skip-locked"
+
+
+@dataclass(frozen=True, slots=True)
+class LockNode:
+    """Rows held for this transaction, so nobody else changes them first.
+
+    ``tables`` narrows the lock to some of what the query reads, which is
+    what keeps a join from locking rows it only looked at.
+    """
+
+    strength: LockStrength
+    wait: LockWait = LockWait.WAIT
+    tables: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class SelectNode:
+    projections: tuple[ProjectionNode, ...]
+    source: SourceNode | None = None
+    joins: tuple[JoinNode, ...] = ()
+    condition: ExpressionNode | None = None
+    matches: tuple[ExpressionNode, ...] = ()
+    """What a semi or anti join asks of each row.
+
+    Kept apart from the condition so that `where` stays a clause a caller
+    defines once, and a semi join neither collides with it nor depends on
+    having been written after it.
+    """
+
+    groups: tuple[ExpressionNode, ...] = ()
+    having: ExpressionNode | None = None
+    orders: tuple[OrderNode, ...] = ()
+    limit: int | None = None
+    offset: int | None = None
+    common_tables: tuple[CommonTableNode, ...] = ()
+    windows: tuple[NamedWindowNode, ...] = ()
+    """Windows written once here and looked through by name."""
+
+    distinct: bool = False
+    lock: LockNode | None = None
+    every_column: bool = False
+    """Whether the projection is written as a star.
+
+    The columns are still carried, because they are what names a row's fields
+    and says what type each one reads back as. Only the SQL is shorter.
+    """
+
+    def __post_init__(self) -> None:
+        if not self.projections:
+            message = "SELECT requires at least one projection"
+            raise ValueError(message)
+
+
+@dataclass(frozen=True, slots=True)
+class SetNode:
+    left: QueryNode
+    operator: SetOperator
+    right: QueryNode
+    orders: tuple[OrderNode, ...] = ()
+    limit: int | None = None
+    offset: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class SubquerySourceNode:
+    query: QueryNode
+    alias: str
+    lateral: bool = False
+    """Whether the subquery may read the rows to its left.
+
+    An ordinary subquery in a FROM clause is evaluated on its own. A lateral
+    one is evaluated per row of what came before it, which is the whole point
+    and also why not every dialect has it.
+    """
+
+    def __post_init__(self) -> None:
+        _require_identifier(self.alias, "subquery alias")
+
+
+@dataclass(frozen=True, slots=True)
+class CommonTableSourceNode:
+    name: str
+
+    def __post_init__(self) -> None:
+        _require_identifier(self.name, "common table")
+
+
+@dataclass(frozen=True, slots=True)
+class CommonTableNode:
+    name: str
+    query: QueryNode
+    columns: tuple[str, ...] = ()
+    recursive: bool = False
+
+    def __post_init__(self) -> None:
+        _require_identifier(self.name, "common table")
+        for column in self.columns:
+            _require_identifier(column, "common table column")
+
+
+@dataclass(frozen=True, slots=True)
+class JoinNode:
+    kind: JoinKind
+    source: SourceNode
+    condition: ExpressionNode | None = None
+    using: tuple[str, ...] = ()
+    natural: bool = False
+
+    def __post_init__(self) -> None:
+        _validate_join(self)
+
+
+def _validate_join(node: JoinNode) -> None:
+    """A join is qualified once, by the one clause SQL allows it.
+
+    `ON`, `USING`, and `NATURAL` each say how two tables line up, and a join
+    that named two of them would be asking the database to decide which.
+    """
+    for column in node.using:
+        _require_identifier(column, "join column")
+    qualifiers = (
+        node.condition is not None,
+        bool(node.using),
+        node.natural,
+    )
+    named = sum(qualifiers)
+    if node.kind is JoinKind.CROSS:
+        if named:
+            message = "cross join cannot be qualified"
+            raise ValueError(message)
+        return
+    if named == 0:
+        message = "qualified join requires ON, USING, or NATURAL"
+        raise ValueError(message)
+    if named > 1:
+        message = "qualified join takes one of ON, USING, or NATURAL"
+        raise ValueError(message)
+
+
+QueryNode: TypeAlias = SelectNode | SetNode
+
+
+@dataclass(frozen=True, slots=True)
+class JsonElementsSourceNode:
+    """The elements of a JSON array, read one row at a time.
+
+    Every dialect can turn an array into rows, and each spells it so
+    differently that only the alias and the one column are shared.
+    """
+
+    expression: ExpressionNode
+    alias: str
+
+
+ELEMENT_COLUMN = "value"
+"""What the one column of an expanded JSON array is called on every dialect."""
+
+
+SourceNode: TypeAlias = (
+    TableSourceNode
+    | SubquerySourceNode
+    | CommonTableSourceNode
+    | JsonElementsSourceNode
+)
+
+
+def _require_identifier(value: str, label: str) -> None:
+    if not value or "\x00" in value:
+        message = f"{label} identifier cannot be empty or contain a null character"
+        raise ValueError(message)
+
+
+def _require_optional_identifier(value: str | None, label: str) -> None:
+    if value is not None:
+        _require_identifier(value, label)
+
+
+__all__ = (
+    "ELEMENT_COLUMN",
+    "CommonTableNode",
+    "CommonTableSourceNode",
+    "JoinKind",
+    "JoinNode",
+    "JsonElementsSourceNode",
+    "NullOrder",
+    "OrderDirection",
+    "OrderNode",
+    "ProjectionNode",
+    "QueryNode",
+    "SelectNode",
+    "SetNode",
+    "SetOperator",
+    "SourceNode",
+    "SubquerySourceNode",
+    "TableSourceNode",
+)

pyoq/query/sources.py

@@ -0,0 +1,236 @@
+"""Typed query sources and write targets for generated table descriptors."""
+
+from __future__ import annotations
+
+from typing import ClassVar, Generic, Protocol, TypeVar, cast, runtime_checkable
+
+from pyoq.errors import QueryValidationError
+from pyoq.query.fields import Field, field
+from pyoq.query.nodes import FieldNode
+from pyoq.query.raw import NodeProvider
+from pyoq.query.select_nodes import (
+    ELEMENT_COLUMN,
+    CommonTableNode,
+    CommonTableSourceNode,
+    JsonElementsSourceNode,
+    QueryNode,
+    SourceNode,
+    SubquerySourceNode,
+    TableSourceNode,
+)
+from pyoq.query.write_nodes import WriteTargetNode
+
+SourceRow = TypeVar("SourceRow", covariant=True)
+FieldValue = TypeVar("FieldValue")
+
+
+@runtime_checkable
+class TableLike(Protocol):
+    @property
+    def database_name(self) -> str: ...
+
+    @property
+    def schema_name(self) -> str | None: ...
+
+    @property
+    def catalog_name(self) -> str | None: ...
+
+
+@runtime_checkable
+class ColumnedTable(TableLike, Protocol):
+    """A table that names its own columns, which a generated table does."""
+
+    COLUMNS: ClassVar[tuple[object, ...]]
+
+
+class SourceBase:
+    __slots__ = ("_node", "_qualifier")
+    _node: SourceNode
+    _qualifier: str
+
+    def __init__(self, node: SourceNode, qualifier: str) -> None:
+        object.__setattr__(self, "_node", node)
+        object.__setattr__(self, "_qualifier", qualifier)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        message = "query sources are immutable"
+        raise AttributeError(message)
+
+    @property
+    def node(self) -> SourceNode:
+        return self._node
+
+
+class Source(SourceBase, Generic[SourceRow]):
+    __slots__ = ()
+
+    def field(
+        self,
+        value_type: type[FieldValue],
+        database_name: str,
+        /,
+    ) -> Field[FieldValue]:
+        schema_name, catalog_name = _source_qualification(self.node)
+        return field(
+            value_type,
+            database_name,
+            table_name=self._qualifier,
+            schema_name=schema_name,
+            catalog_name=catalog_name,
+        )
+
+
+class Subquery(Source[SourceRow], Generic[SourceRow]):
+    __slots__ = ()
+
+
+class CommonTable(Source[SourceRow], Generic[SourceRow]):
+    __slots__ = ("_definition",)
+    _definition: CommonTableNode
+
+    def __init__(self, definition: CommonTableNode) -> None:
+        super().__init__(CommonTableSourceNode(definition.name), definition.name)
+        object.__setattr__(self, "_definition", definition)
+
+    @property
+    def definition(self) -> CommonTableNode:
+        return self._definition
+
+
+def table_source(table: TableLike, /, *, alias: str | None = None) -> Source[object]:
+    _require_table_instance(table)
+    require_identifier(table.database_name, "table")
+    _require_optional_identifier(table.schema_name, "schema")
+    _require_optional_identifier(table.catalog_name, "catalog")
+    _require_optional_identifier(alias, "table alias")
+    qualifier = alias or table.database_name
+    return Source(
+        TableSourceNode(
+            table.database_name,
+            table.schema_name,
+            table.catalog_name,
+            alias,
+        ),
+        qualifier,
+    )
+
+
+def json_elements(
+    document: NodeProvider,
+    /,
+    *,
+    alias: str,
+) -> Source[object]:
+    """The elements of a JSON array, read one row at a time.
+
+    The rows have one column, named the same on every dialect, so a document
+    is joined to and filtered like any other source.
+    """
+    require_identifier(alias, "json elements alias")
+    return Source(JsonElementsSourceNode(document.node, alias), alias)
+
+
+def write_target(table: TableLike, /) -> WriteTargetNode:
+    _require_table_instance(table)
+    require_identifier(table.database_name, "table")
+    _require_optional_identifier(table.schema_name, "schema")
+    _require_optional_identifier(table.catalog_name, "catalog")
+    return WriteTargetNode(
+        table.database_name,
+        table.schema_name,
+        table.catalog_name,
+        _declared_columns(table),
+    )
+
+
+def _declared_columns(table: TableLike) -> tuple[str, ...]:
+    """What a generated table names, and nothing for one written by hand."""
+    declared: object = getattr(table, "COLUMNS", ())
+    if not isinstance(declared, tuple):
+        return ()
+    columns = cast("tuple[object, ...]", declared)
+    names: list[str] = []
+    for column in columns:
+        node = getattr(column, "node", None)
+        if isinstance(node, FieldNode):
+            names.append(node.name)
+    return tuple(names)
+
+
+def subquery_source(
+    query: QueryNode,
+    alias: str,
+    /,
+    *,
+    lateral: bool = False,
+) -> Subquery[object]:
+    require_identifier(alias, "subquery alias")
+    return Subquery(SubquerySourceNode(query, alias, lateral=lateral), alias)
+
+
+def common_table(
+    name: str,
+    query: QueryNode,
+    /,
+    *,
+    columns: tuple[str, ...] = (),
+    recursive: bool = False,
+) -> CommonTable[object]:
+    require_identifier(name, "common table")
+    for column in columns:
+        require_identifier(column, "common table column")
+    return CommonTable(CommonTableNode(name, query, columns, recursive))
+
+
+def resolve_source(value: object) -> SourceNode:
+    if isinstance(value, SourceBase):
+        return value.node
+    if isinstance(value, TableLike):
+        return table_source(value).node
+    message = "query source must be a table, subquery, or common table"
+    raise TypeError(message)
+
+
+def _require_table_instance(table: TableLike) -> None:
+    if isinstance(table, type):
+        message = (
+            "query source must be a table descriptor instance; a generated table "
+            "class is the typed column and builder namespace, and the generated "
+            "table constant beside it is the query source"
+        )
+        raise QueryValidationError(message)
+
+
+def _source_qualification(node: SourceNode) -> tuple[str | None, str | None]:
+    if isinstance(node, TableSourceNode) and node.alias is None:
+        return node.schema, node.catalog
+    return None, None
+
+
+def require_identifier(value: str, label: str) -> None:
+    """A name written into the SQL, held to being one a database can hold."""
+    if not value or "\x00" in value:
+        message = f"{label} identifier cannot be empty or contain a null character"
+        raise ValueError(message)
+
+
+def _require_optional_identifier(value: str | None, label: str) -> None:
+    if value is not None:
+        require_identifier(value, label)
+
+
+__all__ = (
+    "ELEMENT_COLUMN",
+    "ColumnedTable",
+    "CommonTable",
+    "Source",
+    "SourceBase",
+    "Subquery",
+    "TableLike",
+    "common_table",
+    "json_elements",
+    "resolve_source",
+    "subquery_source",
+    "table_source",
+    "write_target",
+)

pyoq/query/sqlite/__init__.py

@@ -0,0 +1,43 @@
+"""SQLite query compilation."""
+
+from pyoq.query.sqlite.compiler import QueryProvider, SQLiteCompiler
+from pyoq.query.sqlite.executor import SQLiteExecutor
+from pyoq.query.sqlite.factory import SQLiteConnectionFactory
+from pyoq.query.sqlite.model import CompiledQuery, SQLiteCapabilities
+from pyoq.query.sqlite.parameters import (
+    SQLiteParameter,
+    adapt_parameter,
+    adapt_parameters,
+)
+from pyoq.query.sqlite.planning import SQLiteBulkPlanner
+from pyoq.query.sqlite.pool import (
+    SQLiteConnectionFactoryProtocol,
+    SQLiteConnectionLease,
+    SQLitePool,
+    SQLitePoolPolicy,
+    SQLitePoolStats,
+)
+from pyoq.query.sqlite.streaming import SQLiteRowStream, SQLiteStreamPolicy
+from pyoq.query.sqlite.transactions import SQLiteTransaction, TransactionMode
+
+__all__ = (
+    "CompiledQuery",
+    "QueryProvider",
+    "SQLiteBulkPlanner",
+    "SQLiteCapabilities",
+    "SQLiteCompiler",
+    "SQLiteConnectionFactory",
+    "SQLiteConnectionFactoryProtocol",
+    "SQLiteConnectionLease",
+    "SQLiteExecutor",
+    "SQLiteParameter",
+    "SQLitePool",
+    "SQLitePoolPolicy",
+    "SQLitePoolStats",
+    "SQLiteRowStream",
+    "SQLiteStreamPolicy",
+    "SQLiteTransaction",
+    "TransactionMode",
+    "adapt_parameter",
+    "adapt_parameters",
+)