pyoq-sql 1.0.2__py3-none-any.whl

pyoq/query/vendor.py

@@ -0,0 +1,162 @@
+"""Calling a function this database has that PyOQ does not name itself.
+
+Every database grows functions the others have not got, and a toolkit that
+only offered what all three share would be a smaller toolkit than any of
+them. A vendor function is declared once with the type it answers with, and
+called like any other expression.
+
+This is the manual way, and what it promises is what the caller asserted: the
+result type is taken on trust, and the arguments are whatever was passed. A
+function the database itself declares is reflected and generated instead, and
+that one carries the database's own signature, so its arity and parameter
+types are checked rather than assumed. Reach for this when the function is not
+in the catalog, or when generation is not in use.
+
+The declaration can say which databases the function exists on. That turns a
+query nobody could run into one that is refused while it is being written,
+rather than one that fails at the server.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Generic, TypeVar
+
+from pyoq.errors import ExpressionTypeError
+from pyoq.query.expressions import ComputedExpression, Condition
+from pyoq.query.fields import family_for_type
+from pyoq.query.nodes import ScalarFamily, VendorFunctionNode
+
+if TYPE_CHECKING:
+    from collections.abc import Collection
+
+    from pyoq.config import DatabaseDialect
+    from pyoq.query.raw import NodeProvider
+
+Value = TypeVar("Value")
+
+_FORBIDDEN = ("\x00", "\n", "\r")
+"""What no identifier may hold, quoted or not."""
+
+PLAIN_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)?$")
+"""A name a database reads as written, needing no quoting to be safe."""
+
+
+class VendorFunction(Generic[Value]):
+    """A declared function, callable wherever an expression is."""
+
+    __slots__ = ("_catalog", "_dialects", "_family", "_name", "_schema", "_value_type")
+
+    def __init__(
+        self,
+        name: str,
+        family: ScalarFamily,
+        dialects: frozenset[str],
+        value_type: type[object] | None = None,
+        schema: str | None = None,
+        catalog: str | None = None,
+    ) -> None:
+        self._name = name
+        self._family = family
+        self._dialects = dialects
+        self._value_type = value_type
+        self._schema = schema
+        self._catalog = catalog
+
+    def __call__(self, *arguments: NodeProvider) -> ComputedExpression[Value]:
+        return ComputedExpression[Value](self._node(arguments), self._family)
+
+    def _node(self, arguments: tuple[NodeProvider, ...]) -> VendorFunctionNode:
+        return VendorFunctionNode(
+            self._name,
+            tuple(argument.node for argument in arguments),
+            self._family,
+            self._dialects,
+            value_type=self._value_type,
+            schema=self._schema,
+            catalog=self._catalog,
+        )
+
+
+class VendorPredicate(VendorFunction[bool]):
+    """A declared function that answers true or false."""
+
+    __slots__ = ()
+
+    def __call__(self, *arguments: NodeProvider) -> Condition:  # type: ignore[override]
+        return Condition(self._node(arguments))
+
+
+def vendor_function(
+    value_type: type[Value],
+    name: str,
+    /,
+    *,
+    dialects: Collection[DatabaseDialect] = (),
+    schema: str | None = None,
+    catalog: str | None = None,
+) -> VendorFunction[Value]:
+    """Declare a function this database has, and what it answers with.
+
+    Saying which schema keeps it is what makes a call reach that one rather
+    than whichever the search path happens to find first.
+    """
+    return VendorFunction[Value](
+        checked_routine_name(name),
+        family_for_type(value_type),
+        _named(dialects),
+        value_type,
+        checked_routine_qualifier(schema, "routine schema"),
+        checked_routine_qualifier(catalog, "routine catalog"),
+    )
+
+
+def checked_routine_qualifier(value: str | None, label: str) -> str | None:
+    """Where a routine is kept, held to being a name a database can hold."""
+    if value is None:
+        return None
+    if not value or "\x00" in value or "\n" in value or "\r" in value:
+        message = f"{label} cannot be empty or hold a line break"
+        raise ExpressionTypeError(message)
+    return value
+
+
+def vendor_predicate(
+    name: str,
+    /,
+    *,
+    dialects: Collection[DatabaseDialect] = (),
+) -> VendorPredicate:
+    """Declare a function that answers true or false."""
+    return VendorPredicate(
+        checked_routine_name(name), ScalarFamily.BOOLEAN, _named(dialects)
+    )
+
+
+def checked_routine_name(name: str) -> str:
+    """A routine name, checked because it is written into the SQL, not bound.
+
+    A database takes no routine name as a parameter, so the name is written
+    out. One that reads as an identifier is written as it stands; any other
+    is quoted by the dialect, which is what makes a name with a space in it
+    usable and a name with anything else in it harmless.
+    """
+    if not name or any(character in name for character in _FORBIDDEN):
+        message = f"{name!r} is not a routine name"
+        raise ExpressionTypeError(message)
+    return name
+
+
+def _named(dialects: Collection[DatabaseDialect]) -> frozenset[str]:
+    return frozenset(dialect.value for dialect in dialects)
+
+
+__all__ = (
+    "PLAIN_NAME",
+    "VendorFunction",
+    "VendorPredicate",
+    "checked_routine_name",
+    "checked_routine_qualifier",
+    "vendor_function",
+    "vendor_predicate",
+)

pyoq/query/windows.py

@@ -0,0 +1,424 @@
+"""Measuring a row against the rows around it.
+
+An aggregate collapses a group into one row. A window leaves the rows alone
+and gives each one an answer computed from its neighbours, so a running total,
+a rank, or the previous row's value can be selected beside the row itself.
+
+The clauses read in the order SQL writes them: the function, then the window
+it looks through, then how that window is divided and ordered.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING, Generic, TypeVar
+
+from pyoq.errors import QueryStateError, QueryValidationError
+from pyoq.query.expressions import ComputedExpression, Expression, operand
+from pyoq.query.nodes import (
+    EVERY_ROW,
+    FrameBound,
+    FrameBoundNode,
+    FrameExclusion,
+    FrameKind,
+    FrameNode,
+    NamedWindowNode,
+    ScalarFamily,
+    WindowFunctionNode,
+    WindowName,
+    WindowNode,
+    WindowReferenceNode,
+    WindowSpecificationNode,
+)
+from pyoq.query.projections import order_node
+from pyoq.query.raw import NodeProvider
+
+if TYPE_CHECKING:
+    from pyoq.query.nodes import ExpressionNode
+    from pyoq.query.select_nodes import OrderNode
+
+Value = TypeVar("Value")
+
+_WINDOW_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+"""A window is named by one identifier, and it is written as it is given."""
+
+
+@dataclass(frozen=True, slots=True)
+class WindowSpecification:
+    """How a window divides and orders the rows it covers.
+
+    The same vocabulary builds the window a single function looks through and
+    the one a query declares by name, so a frame means the same thing in both.
+    """
+
+    node: WindowSpecificationNode = EVERY_ROW
+    name: str | None = None
+
+    def partition_by(self, *expressions: NodeProvider) -> WindowSpecification:
+        """The groups the rows are divided into before they are measured."""
+        if not expressions:
+            message = "partition by requires at least one expression"
+            raise ValueError(message)
+        return self._with(
+            partition_by=tuple(expression.node for expression in expressions)
+        )
+
+    def order_by(self, *terms: object) -> WindowSpecification:
+        """The order the rows are read in, which is what makes a rank a rank.
+
+        A window orders rows the way a query does, so a bare column and a
+        term that names a direction are both accepted here.
+        """
+        if not terms:
+            message = "order by requires at least one term"
+            raise ValueError(message)
+        return self._with(order_by=tuple(order_node(term) for term in terms))
+
+    def rows(
+        self, start: FrameEdge, end: FrameEdge | None = None
+    ) -> WindowSpecification:
+        """Narrow the window by counting rows around the one being measured."""
+        return self._framed(FrameKind.ROWS, start, end)
+
+    def range_(
+        self, start: FrameEdge, end: FrameEdge | None = None
+    ) -> WindowSpecification:
+        """Narrow the window by value, so rows of equal value come together."""
+        return self._framed(FrameKind.RANGE, start, end)
+
+    def groups(
+        self, start: FrameEdge, end: FrameEdge | None = None
+    ) -> WindowSpecification:
+        """Narrow the window by counting peer groups rather than rows."""
+        return self._framed(FrameKind.GROUPS, start, end)
+
+    def exclude(self, exclusion: FrameExclusion, /) -> WindowSpecification:
+        """Leave rows out of a frame that it would otherwise reach."""
+        frame = self.node.frame
+        if frame is None:
+            message = "what a frame excludes is said after what it covers"
+            raise QueryStateError(message)
+        return self._replace_frame(replace(frame, exclusion=exclusion))
+
+    @property
+    def declaration(self) -> NamedWindowNode:
+        """This window as a query declares it, which needs it to be named."""
+        if self.name is None:
+            message = "only a named window is declared by a query"
+            raise QueryStateError(message)
+        return NamedWindowNode(self.name, self.node)
+
+    def _framed(
+        self,
+        kind: FrameKind,
+        start: FrameEdge,
+        end: FrameEdge | None,
+    ) -> WindowSpecification:
+        return self._replace_frame(
+            FrameNode(kind, start.node, None if end is None else end.node)
+        )
+
+    def _replace_frame(self, frame: FrameNode) -> WindowSpecification:
+        return replace(self, node=replace(self.node, frame=frame))
+
+    def _with(
+        self,
+        *,
+        partition_by: tuple[ExpressionNode, ...] | None = None,
+        order_by: tuple[OrderNode, ...] | None = None,
+    ) -> WindowSpecification:
+        current = self.node
+        return replace(
+            self,
+            node=WindowSpecificationNode(
+                current.partition_by if partition_by is None else partition_by,
+                current.order_by if order_by is None else order_by,
+                current.frame,
+            ),
+        )
+
+
+def named_window(name: str, /) -> WindowSpecification:
+    """A window written once in a query and looked through by several rows.
+
+    Repeating a partition and an order beside every function is how they come
+    to disagree. A named window is declared once, and each function says which
+    window it reads through.
+
+    The name is written into the SQL rather than bound, because no database
+    takes a window name as a parameter, so it is held to being a plain name.
+    """
+    if _WINDOW_NAME.match(name) is None:
+        message = "a window name is a plain identifier"
+        raise QueryValidationError(message)
+    return WindowSpecification(name=name)
+
+
+def looking_through(
+    node: ExpressionNode,
+    window: WindowSpecification | None,
+) -> WindowNode:
+    """One function and the window it reads, named by the query or written here.
+
+    The value the window answers with is the one the function already had, so
+    the caller keeps that and only the window is decided here.
+    """
+    if window is None:
+        return WindowNode(node)
+    if window.name is None:
+        message = "a window is declared with a name before it is read through"
+        raise QueryStateError(message)
+    return WindowNode(node, WindowReferenceNode(window.name))
+
+
+class Window(ComputedExpression[Value], Generic[Value]):
+    """A value already usable, which naming partitions or an order refines."""
+
+    __slots__ = ("_window_node",)
+    _window_node: WindowNode
+
+    def __init__(self, node: WindowNode, family: ScalarFamily) -> None:
+        super().__init__(node, family)
+        object.__setattr__(self, "_window_node", node)
+
+    def partition_by(self, *expressions: NodeProvider) -> Window[Value]:
+        """The groups the rows are divided into before they are measured."""
+        return self._refined(self._specification.partition_by(*expressions))
+
+    def order_by(self, *terms: object) -> Window[Value]:
+        """The order the rows are read in, which is what makes a rank a rank."""
+        return self._refined(self._specification.order_by(*terms))
+
+    def rows(self, start: FrameEdge, end: FrameEdge | None = None) -> Window[Value]:
+        """Narrow the window by counting rows around the one being measured."""
+        return self._refined(self._specification.rows(start, end))
+
+    def range_(self, start: FrameEdge, end: FrameEdge | None = None) -> Window[Value]:
+        """Narrow the window by value, so rows of equal value come together."""
+        return self._refined(self._specification.range_(start, end))
+
+    def groups(self, start: FrameEdge, end: FrameEdge | None = None) -> Window[Value]:
+        """Narrow the window by counting peer groups rather than rows."""
+        return self._refined(self._specification.groups(start, end))
+
+    def exclude(self, exclusion: FrameExclusion, /) -> Window[Value]:
+        """Leave rows out of a frame that it would otherwise reach."""
+        return self._refined(self._specification.exclude(exclusion))
+
+    @property
+    def _specification(self) -> WindowSpecification:
+        window = self._window_node.window
+        if isinstance(window, WindowReferenceNode):
+            message = "a window declared by the query is refined where it is declared"
+            raise QueryStateError(message)
+        return WindowSpecification(window)
+
+    def _refined(self, specification: WindowSpecification) -> Window[Value]:
+        return Window[Value](
+            replace(self._window_node, window=specification.node), self.family
+        )
+
+
+class WindowFunction(ComputedExpression[Value], Generic[Value]):
+    """A function that means nothing until it is given a window to look through."""
+
+    __slots__ = ()
+
+    def over(self, window: WindowSpecification | None = None, /) -> Window[Value]:
+        """The rows this reads, which is every row until it is partitioned.
+
+        Given a window the query declares, this reads through that one by
+        name and is not refined further here.
+        """
+        return Window[Value](looking_through(self.node, window), self.family)
+
+
+@dataclass(frozen=True, slots=True)
+class FrameEdge:
+    """One edge of a frame, built by the helpers below rather than by hand."""
+
+    node: FrameBoundNode
+
+
+def unbounded_preceding() -> FrameEdge:
+    """Every row before this one, however many there are."""
+    return FrameEdge(FrameBoundNode(FrameBound.UNBOUNDED_PRECEDING))
+
+
+def preceding(distance: int, /) -> FrameEdge:
+    """This far back from the row being measured."""
+    return FrameEdge(
+        FrameBoundNode(
+            FrameBound.PRECEDING, operand(_counted(distance), ScalarFamily.NUMERIC)
+        )
+    )
+
+
+def current_row() -> FrameEdge:
+    """The row being measured."""
+    return FrameEdge(FrameBoundNode(FrameBound.CURRENT_ROW))
+
+
+def following(distance: int, /) -> FrameEdge:
+    """This far ahead of the row being measured."""
+    return FrameEdge(
+        FrameBoundNode(
+            FrameBound.FOLLOWING, operand(_counted(distance), ScalarFamily.NUMERIC)
+        )
+    )
+
+
+def unbounded_following() -> FrameEdge:
+    """Every row after this one, however many there are."""
+    return FrameEdge(FrameBoundNode(FrameBound.UNBOUNDED_FOLLOWING))
+
+
+def _counted(distance: int) -> int:
+    if distance < 0:
+        message = "a frame edge counts forwards from the row it is measured against"
+        raise ValueError(message)
+    return distance
+
+
+def row_number() -> WindowFunction[int]:
+    """Which row this is in its window, counting from one, ties broken."""
+    return _ranking(WindowName.ROW_NUMBER)
+
+
+def rank() -> WindowFunction[int]:
+    """The position of this row, where ties share a position and leave a gap."""
+    return _ranking(WindowName.RANK)
+
+
+def dense_rank() -> WindowFunction[int]:
+    """The position of this row, where ties share a position and leave no gap."""
+    return _ranking(WindowName.DENSE_RANK)
+
+
+def ntile(buckets: int, /) -> WindowFunction[int]:
+    """Which of this many equal buckets the row falls in."""
+    if buckets < 1:
+        message = "ntile requires at least one bucket"
+        raise ValueError(message)
+    return WindowFunction[int](
+        WindowFunctionNode(WindowName.NTILE, (operand(buckets, ScalarFamily.NUMERIC),)),
+        ScalarFamily.NUMERIC,
+    )
+
+
+def lag(
+    expression: Expression[Value],
+    offset: int = 1,
+    /,
+) -> WindowFunction[Value | None]:
+    """The value this far back in the window, or null before its start."""
+    return _offset(WindowName.LAG, expression, offset)
+
+
+def lead(
+    expression: Expression[Value],
+    offset: int = 1,
+    /,
+) -> WindowFunction[Value | None]:
+    """The value this far ahead in the window, or null past its end."""
+    return _offset(WindowName.LEAD, expression, offset)
+
+
+def percent_rank() -> WindowFunction[float]:
+    """How far through its window this row sits, from zero to one."""
+    return WindowFunction[float](
+        WindowFunctionNode(WindowName.PERCENT_RANK), ScalarFamily.NUMERIC
+    )
+
+
+def cume_dist() -> WindowFunction[float]:
+    """The share of the window at or before this row, above zero to one."""
+    return WindowFunction[float](
+        WindowFunctionNode(WindowName.CUME_DIST), ScalarFamily.NUMERIC
+    )
+
+
+def first_value(expression: Expression[Value], /) -> WindowFunction[Value | None]:
+    """The value in the first row of the window, or null when it is empty."""
+    return _navigating(WindowName.FIRST_VALUE, expression)
+
+
+def last_value(expression: Expression[Value], /) -> WindowFunction[Value | None]:
+    """The value in the last row the frame reaches, which the frame decides.
+
+    Without a frame a window ends at the current row, so this answers with the
+    current row's value until the frame is widened to the whole partition.
+    """
+    return _navigating(WindowName.LAST_VALUE, expression)
+
+
+def nth_value(
+    expression: Expression[Value],
+    position: int,
+    /,
+) -> WindowFunction[Value | None]:
+    """The value this far into the window, counting from one."""
+    if position < 1:
+        message = "nth value counts from one"
+        raise ValueError(message)
+    return WindowFunction[Value | None](
+        WindowFunctionNode(
+            WindowName.NTH_VALUE,
+            (expression.node, operand(position, ScalarFamily.NUMERIC)),
+        ),
+        expression.family,
+    )
+
+
+def _navigating(
+    name: WindowName,
+    expression: Expression[Value],
+) -> WindowFunction[Value | None]:
+    return WindowFunction[Value | None](
+        WindowFunctionNode(name, (expression.node,)), expression.family
+    )
+
+
+def _offset(
+    name: WindowName,
+    expression: Expression[Value],
+    offset: int,
+) -> WindowFunction[Value | None]:
+    if offset < 1:
+        message = f"{name.value.replace('-', ' ')} requires a positive offset"
+        raise ValueError(message)
+    arguments = (expression.node, operand(offset, ScalarFamily.NUMERIC))
+    return WindowFunction[Value | None](
+        WindowFunctionNode(name, arguments), expression.family
+    )
+
+
+def _ranking(name: WindowName) -> WindowFunction[int]:
+    return WindowFunction[int](WindowFunctionNode(name), ScalarFamily.NUMERIC)
+
+
+__all__ = (
+    "FrameEdge",
+    "FrameExclusion",
+    "Window",
+    "WindowFunction",
+    "WindowSpecification",
+    "cume_dist",
+    "current_row",
+    "dense_rank",
+    "first_value",
+    "following",
+    "lag",
+    "last_value",
+    "lead",
+    "named_window",
+    "nth_value",
+    "ntile",
+    "percent_rank",
+    "preceding",
+    "rank",
+    "row_number",
+    "unbounded_following",
+    "unbounded_preceding",
+)