sqlakit 0.3.1__tar.gz → 0.5.0__tar.gz

{sqlakit-0.3.1 → sqlakit-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlakit
-Version: 0.3.1
+Version: 0.5.0
 Summary: A toolkit for SQLAlchemy applications.
 Keywords: sqlalchemy,database,orm,sql,asyncio
 Author: Anton Ruhlov
@@ -406,3 +406,5 @@ test from an empty file. The rest is under [`docs/`](docs/):
 [debugging](docs/debugging.md), [multiple databases](docs/routing.md) and
 [the reference](docs/reference.md). Complete example apps live in
 [`examples/`](examples/), and each one is run by the test suite.
+
+What changed in each version is in the [changelog](CHANGELOG.md).

{sqlakit-0.3.1 → sqlakit-0.5.0}/README.md

@@ -374,3 +374,5 @@ test from an empty file. The rest is under [`docs/`](docs/):
 [debugging](docs/debugging.md), [multiple databases](docs/routing.md) and
 [the reference](docs/reference.md). Complete example apps live in
 [`examples/`](examples/), and each one is run by the test suite.
+
+What changed in each version is in the [changelog](CHANGELOG.md).

{sqlakit-0.3.1 → sqlakit-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.3.1"
+version = "0.5.0"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"

{sqlakit-0.3.1 → sqlakit-0.5.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.3.1"
+version = "0.5.0"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"

{sqlakit-0.3.1 → sqlakit-0.5.0}/sqlakit/__init__.py

@@ -1,7 +1,7 @@
 from ._base import DEFAULT_ENGINE_ARGS, DEFAULT_SESSION_ARGS
 from ._db import Database, RetryingTransaction, Transaction
 from ._discovery import import_models, import_string
-from ._query import CursorPage, OrderBy, Page
+from ._query import CASE_INSENSITIVE_COLLATIONS, CursorPage, OrderBy, Page
 from ._recording import Recording, Statement
 from ._registry import Databases, db
 from ._routing import Router
@@ -16,6 +16,7 @@ from .exceptions import (
     InstanceNotFoundError,
     InvalidCursorError,
     InvalidDatabaseConfigError,
+    InvalidNullsError,
     InvalidOrderFieldError,
     KeyLookupError,
     MissingConnectionError,
@@ -40,9 +41,17 @@ from .exceptions import (
     UnknownOrderFieldError,
     UnorderedPageError,
 )
-from .types import DatabaseConfig, EngineArgs, QueryStats, SessionArgs, UrlParts
+from .types import (
+    DatabaseConfig,
+    EngineArgs,
+    QueryStats,
+    SessionArgs,
+    TemplatesLike,
+    UrlParts,
+)
 
 __all__ = [
+    "CASE_INSENSITIVE_COLLATIONS",
     "DEFAULT_ALIAS",
     "DEFAULT_ENGINE_ARGS",
     "DEFAULT_SESSION_ARGS",
@@ -60,6 +69,7 @@ __all__ = [
     "InstanceNotFoundError",
     "InvalidCursorError",
     "InvalidDatabaseConfigError",
+    "InvalidNullsError",
     "InvalidOrderFieldError",
     "KeyLookupError",
     "MissingConnectionError",
@@ -84,6 +94,7 @@ __all__ = [
     "Statement",
     "StrayParameterError",
     "TemplateNotFoundError",
+    "TemplatesLike",
     "Transaction",
     "TransactionRolledBackError",
     "UncomparableOrderingError",

{sqlakit-0.3.1 → sqlakit-0.5.0}/sqlakit/_base.py

@@ -49,16 +49,18 @@ from .exceptions import (
 if TYPE_CHECKING:
     import logging
     from collections.abc import Iterator, Sequence
-    from pathlib import Path
 
     from sqlalchemy.engine import Engine
 
-    from ._sql import Templates
-    from .types import DatabaseConfig, EngineArgs, SessionArgs, UrlParts
+    from .types import (
+        DatabaseConfig,
+        EngineArgs,
+        SessionArgs,
+        TemplatesLike,
+        UrlParts,
+    )
 
     RouterFunction = Callable[[type[Any]], str | None]
-    TemplatesLike = str | Path | Sequence[str | Path] | Templates
-    """Where a database's SQL templates are: a path, several, or the object."""
 
 __all__ = [
     "DEFAULT_ALIAS",

{sqlakit-0.3.1 → sqlakit-0.5.0}/sqlakit/_query.py

@@ -10,6 +10,7 @@ from typing import (
     TYPE_CHECKING,
     Any,
     Generic,
+    Literal,
     NamedTuple,
     Protocol,
     Self,
@@ -19,6 +20,7 @@ from typing import (
 
 import sqlalchemy as sa
 from sqlalchemy import exc as sa_exc
+from sqlalchemy.ext.compiler import compiles
 from sqlalchemy.orm import (
     InstrumentedAttribute,
     contains_eager,
@@ -34,6 +36,7 @@ from .exceptions import (
     BulkQueryError,
     InstanceNotFoundError,
     InvalidCursorError,
+    InvalidNullsError,
     InvalidOrderFieldError,
     KeyLookupError,
     MultipleInstancesFoundError,
@@ -53,8 +56,11 @@ if TYPE_CHECKING:
     from sqlalchemy.sql.selectable import ForUpdateParameter
 
 __all__ = [
+    "CASE_INSENSITIVE_COLLATIONS",
     "BaseQuery",
+    "CaseInsensitive",
     "CursorPage",
+    "NullsPlacement",
     "OrderBy",
     "Page",
     "one_row",
@@ -63,6 +69,26 @@ __all__ = [
     "ordered",
 ]
 
+CASE_INSENSITIVE_COLLATIONS: dict[str, str] = {"sqlite": "NOCASE"}
+"""The collation `ignore_case` orders by, per dialect.
+
+A dialect with no entry orders by `lower(...)`, which every database has.
+Name the collation you created, once, before any query runs:
+
+```python
+sqlakit.CASE_INSENSITIVE_COLLATIONS["postgresql"] = "und-ci-ai"
+```
+
+`lower()` folds the case and leaves the accents, so it orders differently
+from a collation like `und-ci-ai`, and it cannot read an index built on the
+column. A column that already carries a case-insensitive collation needs no
+`ignore_case` at all: name the same collation here, or leave it off.
+
+A collation decides the whole order, the alphabet and the accents along with
+the case. This one is asked for only by `ignore_case`. To sort by another,
+name it on the column: `User.name.collate("de-DE")`.
+"""
+
 HIDDEN = "hidden"
 """The rows a soft delete marked are left out, as a read does by default."""
 
@@ -78,6 +104,71 @@ RowT = TypeVar("RowT")
 RowT_co = TypeVar("RowT_co", covariant=True)
 
 
+class CaseInsensitive(sa.ColumnElement[Any]):
+    """A column compared without regard to case, however the dialect does it.
+
+    The dialect is the one the query runs on, not the one it was built against,
+    so a model ordered this way works on `SQLite` under test and on the server
+    it ships to.
+    """
+
+    inherit_cache = True
+
+    def __init__(self, element: sa.ColumnElement[Any]) -> None:
+        self.element = element
+        self.type = element.type
+
+
+@compiles(CaseInsensitive)
+def _compile_case_insensitive(
+    element: CaseInsensitive,
+    compiler: Any,  # noqa: ANN401
+    **kw: Any,  # noqa: ANN401
+) -> str:
+    collation = CASE_INSENSITIVE_COLLATIONS.get(compiler.dialect.name)
+    if collation is None:
+        return compiler.process(sa.func.lower(element.element), **kw)
+    return compiler.process(sa.collate(element.element, collation), **kw)
+
+
+class NullsPlacement(sa.ColumnElement[Any]):
+    """An ordering clause that says where the rows with no value go.
+
+    `MySQL` and `MariaDB` have no `NULLS FIRST` or `NULLS LAST`, so there the
+    clause comes out as the two the standard is short for: whether the value is
+    null, and then the ordering itself.
+    """
+
+    inherit_cache = True
+
+    def __init__(self, clause: Any, *, last: bool) -> None:  # noqa: ANN401
+        self.clause = clause
+        self.last = last
+        self.type = sa.Boolean()
+
+
+@compiles(NullsPlacement)
+def _compile_nulls(
+    element: NullsPlacement,
+    compiler: Any,  # noqa: ANN401
+    **kw: Any,  # noqa: ANN401
+) -> str:
+    placed = sa.nulls_last if element.last else sa.nulls_first
+    return compiler.process(placed(element.clause), **kw)
+
+
+@compiles(NullsPlacement, "mysql")
+def _compile_nulls_for_mysql(
+    element: NullsPlacement,
+    compiler: Any,  # noqa: ANN401
+    **kw: Any,  # noqa: ANN401
+) -> str:
+    column, _ = _direction(element.clause)
+    empty = column.is_(None)
+    first = compiler.process(empty.asc() if element.last else empty.desc(), **kw)
+    return f"{first}, {compiler.process(element.clause, **kw)}"
+
+
 @dataclass(frozen=True, slots=True)
 class Page(Generic[ModelT]):
     """One page of rows, and how many there are in total."""
@@ -420,7 +511,8 @@ class BaseQuery(Generic[ModelT]):
     def order_by(
         self,
         *criteria: Any,  # noqa: ANN401
-        ci_fields: Sequence[str] = (),
+        ignore_case: bool | Sequence[str] = False,
+        nulls: Literal["first", "last"] | None = None,
     ) -> Self:
         """Order the rows, by columns or by the sort strings a request carries.
 
@@ -437,21 +529,42 @@ class BaseQuery(Generic[ModelT]):
         A `None` is skipped and a list is taken apart, so a request that names no
         sort, or several, passes straight through.
 
-        ``ci_fields`` names the fields to compare without regard to case. It sorts by
-        `lower(...)`, which a cursor cannot page: use it with `page`, or fold the case
-        in ``__orderable__`` and index it.
+        ``ignore_case`` compares text without regard to case: `True` for every
+        field of this call, or the names of the ones it applies to, for a sort
+        that arrived as a list:
+
+        ```python
+        User.query.order_by("name", ignore_case=True)
+        User.query.order_by(request.sort, ignore_case=["name"])
+        ```
+
+        Which SQL that becomes is the dialect's to decide, and
+        `CASE_INSENSITIVE_COLLATIONS` names the collation. A cursor cannot page
+        it: use it with `page`.
 
         A model sorts by its own mapped columns. `orderable` says how to offer
         others, including fields that are not columns at all.
 
+        ``nulls`` says where the rows with no value go, `first` or `last`. It
+        fills in only what neither the sort string nor the model said, which the
+        database would otherwise answer for itself, differently by dialect and
+        by direction.
+
         Raises:
             UnknownOrderFieldError: if a string names a field the model does not
                 offer.
+            InvalidNullsError: if ``nulls`` is neither `first` nor `last`.
 
         """
         self._reject_statement("order_by")
         return self.with_select(
-            ordered(self._select, self._orderable(), criteria, ci_fields)
+            ordered(
+                self._select,
+                self._orderable(),
+                criteria,
+                ignore_case=ignore_case,
+                nulls=nulls,
+            )
         )
 
     def _directed(self, column: Any, *, descending: bool) -> Any:  # noqa: ANN401
@@ -836,22 +949,31 @@ def ordered(
     select: sa.Select[Any],
     fields: Mapping[str, Any],
     criteria: Iterable[Any],
-    ci_fields: Sequence[str] = (),
+    *,
+    ignore_case: bool | Sequence[str] = False,
+    nulls: str | None = None,
 ) -> sa.Select[Any]:
     """Return the statement ordered by these criteria, joining what they need.
 
     Raises:
         UnknownOrderFieldError: if a name is not one of the fields.
+        InvalidNullsError: if ``nulls`` is neither "first" nor "last".
 
     """
     named = list(_flatten(criteria))
     if not named:
         return select
-    ci = set(ci_fields)
+    if nulls not in (None, "first", "last"):
+        raise InvalidNullsError(nulls)
+    folded = (
+        ignore_case
+        if isinstance(ignore_case, bool)
+        else {_field_named(one, fields) for one in ignore_case}
+    )
     clauses = []
     for criterion in named:
-        clause, join = _ordering_for(criterion, fields, ci)
-        clauses.append(clause)
+        clause, join = _ordering_for(criterion, fields, ignore_case=folded)
+        clauses.append(_with_nulls(clause, nulls))
         if join is not None:
             target, onclause = join
             if not _is_joined(select, target):
@@ -862,26 +984,51 @@ def ordered(
 def _ordering_for(
     criterion: Any,  # noqa: ANN401
     fields: Mapping[str, Any],
-    ci: set[str],
+    *,
+    ignore_case: bool | set[str],
 ) -> tuple[Any, Any]:
     """Return the clause a criterion stands for, and the table it needs."""
     if isinstance(criterion, OrderBy):
         return criterion.expression, (criterion.join, criterion.on)
     if not isinstance(criterion, str):
         return criterion, None
-    name, descending, nulls = _parse_sort_field(criterion)
-    if name not in fields:
-        raise UnknownOrderFieldError(name, list(fields))
+    asked, descending, nulls = _parse_sort_field(criterion)
+    name = _field_named(asked, fields)
     field = fields[name]
     if isinstance(field, OrderBy):
         column, join = field.expression, (field.join, field.on)
     else:
         column, join = field, None
-    if name in ci:
+    if ignore_case is True or (ignore_case is not False and name in ignore_case):
         column = _case_insensitive(column)
     return _sort_clause(column, descending=descending, nulls=nulls), join
 
 
+def _field_named(asked: str, fields: Mapping[str, Any]) -> str:
+    """Return the field a request means, whichever case convention it uses.
+
+    An API sends `userName` for a `user_name` the model declares. The spelling
+    is a matter of convention on either side, so it is not what tells a field
+    from one nobody offers.
+
+    Raises:
+        UnknownOrderFieldError: if no field, or more than one, answers to it.
+
+    """
+    if asked in fields:
+        return asked
+    folded = _fold_name(asked)
+    matches = [name for name in fields if _fold_name(name) == folded]
+    if len(matches) != 1:
+        raise UnknownOrderFieldError(asked, list(fields))
+    return matches[0]
+
+
+def _fold_name(name: str) -> str:
+    """Return a name with the case and the separators taken out of it."""
+    return name.replace("_", "").replace("-", "").lower()
+
+
 def _chain(loader: Any, keys: Sequence[Any]) -> Any:  # noqa: ANN401
     option = loader(keys[0])
     for key in keys[1:]:
@@ -897,6 +1044,8 @@ def _direction(clause: Any) -> tuple[sa.ColumnElement[Any], bool]:  # noqa: ANN4
     """
     descending = False
     element = clause
+    while isinstance(element, NullsPlacement):
+        element = element.clause
     while isinstance(element, sa.UnaryExpression):
         if element.modifier is operators.desc_op:
             descending = True
@@ -934,12 +1083,27 @@ def _sort_clause(column: Any, *, descending: bool, nulls: str | None) -> Any:  #
     clause = sa.desc(column) if descending else sa.asc(column)
     nulls = nulls or wrapped
     if nulls == "nulls_first":
-        return clause.nulls_first()
+        return NullsPlacement(clause, last=False)
     if nulls == "nulls_last":
-        return clause.nulls_last()
+        return NullsPlacement(clause, last=True)
     return clause
 
 
+def _with_nulls(clause: Any, nulls: str | None) -> Any:  # noqa: ANN401
+    """Return the clause with the nulls it was told to put where it asked for none.
+
+    A sort string and a field the model declared each say where their nulls go.
+    This fills in only what neither of them said, which the database would
+    otherwise answer for itself, differently by dialect and by direction.
+    """
+    if nulls is None:
+        return clause
+    _, already = _split_nulls(clause)
+    if already is not None:
+        return clause
+    return NullsPlacement(clause, last=nulls == "last")
+
+
 def _flatten(criteria: Iterable[Any]) -> Iterator[Any]:
     """Yield the ordering criteria, taking lists apart and dropping the Nones."""
     for criterion in criteria:
@@ -990,11 +1154,11 @@ def _selectable_of(target: Any) -> Any:  # noqa: ANN401
 
 
 def _case_insensitive(column: Any) -> Any:  # noqa: ANN401
-    """Return the column folded to one case, if it holds text at all."""
+    """Return the column compared without regard to case, if it holds text."""
     inner, nulls = _split_nulls(column)
     if not isinstance(getattr(inner, "type", None), sa.String):
         return column
-    folded = sa.func.lower(inner)
+    folded = CaseInsensitive(inner)
     if nulls == "nulls_last":
         return sa.nulls_last(folded)
     if nulls == "nulls_first":
@@ -1004,6 +1168,8 @@ def _case_insensitive(column: Any) -> Any:  # noqa: ANN401
 
 def _split_nulls(column: Any) -> tuple[Any, str | None]:  # noqa: ANN401
     """Separate a column from the nulls modifier wrapped around it."""
+    if isinstance(column, NullsPlacement):
+        return column.clause, "nulls_last" if column.last else "nulls_first"
     if isinstance(column, sa.UnaryExpression):
         if column.modifier is operators.nulls_last_op:
             return column.element, "nulls_last"

{sqlakit-0.3.1 → sqlakit-0.5.0}/sqlakit/asyncio/orm.py

@@ -6,6 +6,7 @@ from typing import (
     Any,
     ClassVar,
     Generic,
+    Literal,
     Self,
     TypeVar,
     cast,
@@ -432,11 +433,18 @@ class ColumnQuery(Generic[RowT]):
     def order_by(
         self,
         *criteria: Any,  # noqa: ANN401
-        ci_fields: Sequence[str] = (),
+        ignore_case: bool | Sequence[str] = False,
+        nulls: Literal["first", "last"] | None = None,
     ) -> Self:
         """Order the rows, by columns or by the names the model offers."""
         return self.with_select(
-            ordered(self._select, orderable(self.model), criteria, ci_fields)
+            ordered(
+                self._select,
+                orderable(self.model),
+                criteria,
+                ignore_case=ignore_case,
+                nulls=nulls,
+            )
         )
 
     def distinct(self) -> Self:

{sqlakit-0.3.1 → sqlakit-0.5.0}/sqlakit/exceptions.py

@@ -14,6 +14,7 @@ __all__ = [
     "InstanceNotFoundError",
     "InvalidCursorError",
     "InvalidDatabaseConfigError",
+    "InvalidNullsError",
     "InvalidOrderFieldError",
     "MissingConnectionError",
     "MissingDatabaseUrlError",
@@ -387,6 +388,18 @@ class InvalidOrderFieldError(SQLAKitError, TypeError):
         )
 
 
+class InvalidNullsError(SQLAKitError, ValueError):
+    """Raised when ``order_by`` is told to put the nulls somewhere else.
+
+    ``nulls`` says where the rows with no value go, and SQL has two answers to
+    that.
+    """
+
+    def __init__(self, nulls: object) -> None:
+        self.nulls = nulls
+        super().__init__(f"`nulls` is `first` or `last`, not `{nulls!r}`.")
+
+
 class KeyLookupError(SQLAKitError, TypeError):
     """Raised when a lookup by primary key is asked to honour what it cannot."""
 

{sqlakit-0.3.1 → sqlakit-0.5.0}/sqlakit/orm.py

@@ -6,6 +6,7 @@ from typing import (
     Any,
     ClassVar,
     Generic,
+    Literal,
     Self,
     TypeVar,
     cast,
@@ -420,11 +421,18 @@ class ColumnQuery(Generic[RowT]):
     def order_by(
         self,
         *criteria: Any,  # noqa: ANN401
-        ci_fields: Sequence[str] = (),
+        ignore_case: bool | Sequence[str] = False,
+        nulls: Literal["first", "last"] | None = None,
     ) -> Self:
         """Order the rows, by columns or by the names the model offers."""
         return self.with_select(
-            ordered(self._select, orderable(self.model), criteria, ci_fields)
+            ordered(
+                self._select,
+                orderable(self.model),
+                criteria,
+                ignore_case=ignore_case,
+                nulls=nulls,
+            )
         )
 
     def distinct(self) -> Self:

{sqlakit-0.3.1 → sqlakit-0.5.0}/sqlakit/types.py

@@ -1,16 +1,30 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Literal, TypedDict
+from typing import TYPE_CHECKING, Any, Literal, TypeAlias, TypedDict
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping, Sequence
+    from pathlib import Path
 
     import sqlalchemy as sa
     from sqlalchemy.engine import Connection, Engine
     from sqlalchemy.orm import Query, Session
     from sqlalchemy.pool import Pool
 
-__all__ = ["DatabaseConfig", "EngineArgs", "SessionArgs", "UrlParts"]
+    from ._sql import Templates
+
+__all__ = [
+    "DatabaseConfig",
+    "EngineArgs",
+    "SessionArgs",
+    "TemplatesLike",
+    "UrlParts",
+]
+
+# Quoted, so importing this module never reaches `Templates` and the
+# `jinja2sql` behind it.
+TemplatesLike: TypeAlias = "str | Path | Sequence[str | Path] | Templates"
+"""Where a database's SQL templates are: a path, several, or the object."""
 
 
 class EngineArgs(TypedDict, total=False):