sqlakit 0.4.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlakit
-Version: 0.4.0
+Version: 0.5.0
 Summary: A toolkit for SQLAlchemy applications.
 Keywords: sqlalchemy,database,orm,sql,asyncio
 Author: Anton Ruhlov

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

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

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

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

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

@@ -16,6 +16,7 @@ from .exceptions import (
     InstanceNotFoundError,
     InvalidCursorError,
     InvalidDatabaseConfigError,
+    InvalidNullsError,
     InvalidOrderFieldError,
     KeyLookupError,
     MissingConnectionError,
@@ -40,7 +41,14 @@ 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",
@@ -61,6 +69,7 @@ __all__ = [
     "InstanceNotFoundError",
     "InvalidCursorError",
     "InvalidDatabaseConfigError",
+    "InvalidNullsError",
     "InvalidOrderFieldError",
     "KeyLookupError",
     "MissingConnectionError",
@@ -85,6 +94,7 @@ __all__ = [
     "Statement",
     "StrayParameterError",
     "TemplateNotFoundError",
+    "TemplatesLike",
     "Transaction",
     "TransactionRolledBackError",
     "UncomparableOrderingError",

{sqlakit-0.4.0 → 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.4.0 → sqlakit-0.5.0}/sqlakit/_query.py

@@ -10,6 +10,7 @@ from typing import (
     TYPE_CHECKING,
     Any,
     Generic,
+    Literal,
     NamedTuple,
     Protocol,
     Self,
@@ -35,6 +36,7 @@ from .exceptions import (
     BulkQueryError,
     InstanceNotFoundError,
     InvalidCursorError,
+    InvalidNullsError,
     InvalidOrderFieldError,
     KeyLookupError,
     MultipleInstancesFoundError,
@@ -58,6 +60,7 @@ __all__ = [
     "BaseQuery",
     "CaseInsensitive",
     "CursorPage",
+    "NullsPlacement",
     "OrderBy",
     "Page",
     "one_row",
@@ -76,6 +79,11 @@ Name the collation you created, once, before any query runs:
 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")`.
@@ -123,6 +131,44 @@ def _compile_case_insensitive(
     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."""
@@ -466,6 +512,7 @@ class BaseQuery(Generic[ModelT]):
         self,
         *criteria: Any,  # noqa: ANN401
         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.
 
@@ -498,14 +545,26 @@ class BaseQuery(Generic[ModelT]):
         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, ignore_case=ignore_case)
+            ordered(
+                self._select,
+                self._orderable(),
+                criteria,
+                ignore_case=ignore_case,
+                nulls=nulls,
+            )
         )
 
     def _directed(self, column: Any, *, descending: bool) -> Any:  # noqa: ANN401
@@ -892,20 +951,29 @@ def ordered(
     criteria: Iterable[Any],
     *,
     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
+    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, ignore_case=ignore_case)
-        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):
@@ -917,26 +985,50 @@ def _ordering_for(
     criterion: Any,  # noqa: ANN401
     fields: Mapping[str, Any],
     *,
-    ignore_case: bool | Sequence[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 ignore_case is True or (ignore_case and name in ignore_case):
+    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:]:
@@ -952,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
@@ -989,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:
@@ -1059,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.4.0 → sqlakit-0.5.0}/sqlakit/asyncio/orm.py

@@ -6,6 +6,7 @@ from typing import (
     Any,
     ClassVar,
     Generic,
+    Literal,
     Self,
     TypeVar,
     cast,
@@ -433,6 +434,7 @@ class ColumnQuery(Generic[RowT]):
         self,
         *criteria: Any,  # noqa: ANN401
         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(
@@ -441,6 +443,7 @@ class ColumnQuery(Generic[RowT]):
                 orderable(self.model),
                 criteria,
                 ignore_case=ignore_case,
+                nulls=nulls,
             )
         )
 

{sqlakit-0.4.0 → 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.4.0 → sqlakit-0.5.0}/sqlakit/orm.py

@@ -6,6 +6,7 @@ from typing import (
     Any,
     ClassVar,
     Generic,
+    Literal,
     Self,
     TypeVar,
     cast,
@@ -421,6 +422,7 @@ class ColumnQuery(Generic[RowT]):
         self,
         *criteria: Any,  # noqa: ANN401
         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(
@@ -429,6 +431,7 @@ class ColumnQuery(Generic[RowT]):
                 orderable(self.model),
                 criteria,
                 ignore_case=ignore_case,
+                nulls=nulls,
             )
         )
 

{sqlakit-0.4.0 → 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):