sqlakit 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlakit
-Version: 0.3.0
+Version: 0.4.0
 Summary: A toolkit for SQLAlchemy applications.
 Keywords: sqlalchemy,database,orm,sql,asyncio
 Author: Anton Ruhlov
@@ -185,44 +185,6 @@ feed.next_cursor
 feed.previous_cursor
 ```
 
-## Active Record
-
-An instance saves and deletes itself, and the query is available on the class:
-
-```python
-from sqlalchemy.orm import Mapped, mapped_column
-
-from sqlakit import Database
-from sqlakit.orm import Model
-
-db = Database("postgresql+psycopg://localhost/app")
-
-
-class Note(Model):
-    __tablename__ = "notes"
-
-    id: Mapped[int] = mapped_column(primary_key=True)
-    text: Mapped[str]
-
-
-Note.set_db(db)
-
-with db.transaction():
-    note = Note(text="ada")
-    note.save()
-
-    Note.query.where(Note.text == "ada").all()
-    note.delete()
-```
-
-`set_db()` binds a model to a database. Call it on a base class and every model
-under it inherits the binding. With the global `db` from the section below you
-don't need it at all: the model uses the global registry automatically.
-
-This layer is optional. Everything else works on plain `SQLAlchemy` models, so
-if saving belongs in your repositories or services, skip `sqlakit.orm`
-entirely.
-
 ## Testing
 
 A test runs inside a transaction that rolls back at the end, so nothing the
@@ -328,6 +290,42 @@ with db.using("replica").connect():
     list_users()  # the models read the replica
 ```
 
+## Active Record
+
+An instance saves and deletes itself, and the query is available on the class.
+A model on the registry needs no wiring of its own:
+
+```python
+from sqlalchemy.orm import Mapped, mapped_column
+
+from sqlakit import db
+from sqlakit.orm import Model
+
+
+class Note(Model):
+    __tablename__ = "notes"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    text: Mapped[str]
+
+
+with db.transaction():
+    note = Note(text="ada").save()
+
+    Note.query.where(Note.text == "ada").all()
+    note.delete()
+```
+
+A model that belongs on another database in the registry names its alias with
+`__db__ = "warehouse"`. With a `Database` of your own, `set_db()` binds the
+model to it. Either goes on a base class, and every model under it inherits
+the binding.
+
+This layer is optional. Everything else works on plain `SQLAlchemy` models, so
+if saving belongs in your repositories or services, skip `sqlakit.orm`
+entirely. `SQLModel` classes are `SQLAlchemy` models, and work either way: the
+[examples](examples/) show both.
+
 ## The async API
 
 The async API is identical: the same classes, the same methods. Only the import
@@ -408,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.0 → sqlakit-0.4.0}/README.md

@@ -153,44 +153,6 @@ feed.next_cursor
 feed.previous_cursor
 ```
 
-## Active Record
-
-An instance saves and deletes itself, and the query is available on the class:
-
-```python
-from sqlalchemy.orm import Mapped, mapped_column
-
-from sqlakit import Database
-from sqlakit.orm import Model
-
-db = Database("postgresql+psycopg://localhost/app")
-
-
-class Note(Model):
-    __tablename__ = "notes"
-
-    id: Mapped[int] = mapped_column(primary_key=True)
-    text: Mapped[str]
-
-
-Note.set_db(db)
-
-with db.transaction():
-    note = Note(text="ada")
-    note.save()
-
-    Note.query.where(Note.text == "ada").all()
-    note.delete()
-```
-
-`set_db()` binds a model to a database. Call it on a base class and every model
-under it inherits the binding. With the global `db` from the section below you
-don't need it at all: the model uses the global registry automatically.
-
-This layer is optional. Everything else works on plain `SQLAlchemy` models, so
-if saving belongs in your repositories or services, skip `sqlakit.orm`
-entirely.
-
 ## Testing
 
 A test runs inside a transaction that rolls back at the end, so nothing the
@@ -296,6 +258,42 @@ with db.using("replica").connect():
     list_users()  # the models read the replica
 ```
 
+## Active Record
+
+An instance saves and deletes itself, and the query is available on the class.
+A model on the registry needs no wiring of its own:
+
+```python
+from sqlalchemy.orm import Mapped, mapped_column
+
+from sqlakit import db
+from sqlakit.orm import Model
+
+
+class Note(Model):
+    __tablename__ = "notes"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    text: Mapped[str]
+
+
+with db.transaction():
+    note = Note(text="ada").save()
+
+    Note.query.where(Note.text == "ada").all()
+    note.delete()
+```
+
+A model that belongs on another database in the registry names its alias with
+`__db__ = "warehouse"`. With a `Database` of your own, `set_db()` binds the
+model to it. Either goes on a base class, and every model under it inherits
+the binding.
+
+This layer is optional. Everything else works on plain `SQLAlchemy` models, so
+if saving belongs in your repositories or services, skip `sqlakit.orm`
+entirely. `SQLModel` classes are `SQLAlchemy` models, and work either way: the
+[examples](examples/) show both.
+
 ## The async API
 
 The async API is identical: the same classes, the same methods. Only the import
@@ -376,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.0 → sqlakit-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.3.0"
+version = "0.4.0"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"
@@ -163,8 +163,8 @@ skip = "./.venv,./site,./uv.lock,./.git"
 [dependency-groups]
 dev = [
     "pytest>=9.1.1",
-    "ty>=0.0.72",
-    "ruff>=0.16.3",
+    "ty>=0.0.75",
+    "ruff>=0.16.5",
     "poethepoet>=0.48.0",
     "anyio>=4.14.2",
     "trio>=0.34.0",

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

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.3.0"
+version = "0.4.0"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"
@@ -30,8 +30,6 @@ Repository = "https://github.com/antonrh/sqlakit"
 Documentation = "https://github.com/antonrh/sqlakit"
 
 [project.optional-dependencies]
-# `greenlet`, which the async API runs on. `SQLAlchemy` installs it by itself
-# where a wheel exists, and this asks for it on the platforms where none does.
 asyncio = [
     "sqlalchemy[asyncio]>=2.0.22",
 ]
@@ -56,8 +54,8 @@ default-groups = ["dev", "docs"]
 [dependency-groups]
 dev = [
     "pytest>=9.1.1",
-    "ty>=0.0.72",
-    "ruff>=0.16.3",
+    "ty>=0.0.75",
+    "ruff>=0.16.5",
     "poethepoet>=0.48.0",
     "anyio>=4.14.2",
     "trio>=0.34.0",

{sqlakit-0.3.0 → sqlakit-0.4.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
@@ -43,6 +43,7 @@ from .exceptions import (
 from .types import DatabaseConfig, EngineArgs, QueryStats, SessionArgs, UrlParts
 
 __all__ = [
+    "CASE_INSENSITIVE_COLLATIONS",
     "DEFAULT_ALIAS",
     "DEFAULT_ENGINE_ARGS",
     "DEFAULT_SESSION_ARGS",

{sqlakit-0.3.0 → sqlakit-0.4.0}/sqlakit/_query.py

@@ -19,6 +19,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,
@@ -53,7 +54,9 @@ if TYPE_CHECKING:
     from sqlalchemy.sql.selectable import ForUpdateParameter
 
 __all__ = [
+    "CASE_INSENSITIVE_COLLATIONS",
     "BaseQuery",
+    "CaseInsensitive",
     "CursorPage",
     "OrderBy",
     "Page",
@@ -63,6 +66,21 @@ __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"
+```
+
+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 +96,33 @@ 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)
+
+
 @dataclass(frozen=True, slots=True)
 class Page(Generic[ModelT]):
     """One page of rows, and how many there are in total."""
@@ -420,7 +465,7 @@ class BaseQuery(Generic[ModelT]):
     def order_by(
         self,
         *criteria: Any,  # noqa: ANN401
-        ci_fields: Sequence[str] = (),
+        ignore_case: bool | Sequence[str] = False,
     ) -> Self:
         """Order the rows, by columns or by the sort strings a request carries.
 
@@ -437,9 +482,18 @@ 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.
@@ -451,7 +505,7 @@ class BaseQuery(Generic[ModelT]):
         """
         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)
         )
 
     def _directed(self, column: Any, *, descending: bool) -> Any:  # noqa: ANN401
@@ -836,7 +890,8 @@ def ordered(
     select: sa.Select[Any],
     fields: Mapping[str, Any],
     criteria: Iterable[Any],
-    ci_fields: Sequence[str] = (),
+    *,
+    ignore_case: bool | Sequence[str] = False,
 ) -> sa.Select[Any]:
     """Return the statement ordered by these criteria, joining what they need.
 
@@ -847,10 +902,9 @@ def ordered(
     named = list(_flatten(criteria))
     if not named:
         return select
-    ci = set(ci_fields)
     clauses = []
     for criterion in named:
-        clause, join = _ordering_for(criterion, fields, ci)
+        clause, join = _ordering_for(criterion, fields, ignore_case=ignore_case)
         clauses.append(clause)
         if join is not None:
             target, onclause = join
@@ -862,7 +916,8 @@ def ordered(
 def _ordering_for(
     criterion: Any,  # noqa: ANN401
     fields: Mapping[str, Any],
-    ci: set[str],
+    *,
+    ignore_case: bool | Sequence[str],
 ) -> tuple[Any, Any]:
     """Return the clause a criterion stands for, and the table it needs."""
     if isinstance(criterion, OrderBy):
@@ -877,7 +932,7 @@ def _ordering_for(
         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 and name in ignore_case):
         column = _case_insensitive(column)
     return _sort_clause(column, descending=descending, nulls=nulls), join
 
@@ -990,11 +1045,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":

{sqlakit-0.3.0 → sqlakit-0.4.0}/sqlakit/asyncio/orm.py

@@ -432,11 +432,16 @@ class ColumnQuery(Generic[RowT]):
     def order_by(
         self,
         *criteria: Any,  # noqa: ANN401
-        ci_fields: Sequence[str] = (),
+        ignore_case: bool | Sequence[str] = False,
     ) -> 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,
+            )
         )
 
     def distinct(self) -> Self:

{sqlakit-0.3.0 → sqlakit-0.4.0}/sqlakit/orm.py

@@ -420,11 +420,16 @@ class ColumnQuery(Generic[RowT]):
     def order_by(
         self,
         *criteria: Any,  # noqa: ANN401
-        ci_fields: Sequence[str] = (),
+        ignore_case: bool | Sequence[str] = False,
     ) -> 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,
+            )
         )
 
     def distinct(self) -> Self: