sqlakit 0.5.1__tar.gz → 0.6.0__tar.gz

{sqlakit-0.5.1 → sqlakit-0.6.0}/PKG-INFO

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

{sqlakit-0.5.1 → sqlakit-0.6.0}/pyproject.toml

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

{sqlakit-0.5.1 → sqlakit-0.6.0}/pyproject.toml.orig

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

{sqlakit-0.5.1 → sqlakit-0.6.0}/sqlakit/__init__.py

@@ -1,7 +1,14 @@
 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 CASE_INSENSITIVE_COLLATIONS, CursorPage, OrderBy, Page
+from ._query import (
+    CASE_INSENSITIVE_COLLATIONS,
+    CursorPage,
+    OrderBy,
+    Page,
+    UncountedPage,
+    orderable_columns,
+)
 from ._recording import Recording, Statement
 from ._registry import Databases, db
 from ._routing import Router
@@ -102,6 +109,7 @@ __all__ = [
     "Transaction",
     "TransactionRolledBackError",
     "UncomparableOrderingError",
+    "UncountedPage",
     "UnknownDatabaseError",
     "UnknownFieldError",
     "UnknownImportPathError",
@@ -111,4 +119,5 @@ __all__ = [
     "db",
     "import_models",
     "import_string",
+    "orderable_columns",
 ]

{sqlakit-0.5.1 → sqlakit-0.6.0}/sqlakit/_query.py

@@ -14,7 +14,7 @@ from typing import (
     NamedTuple,
     Protocol,
     Self,
-    TypeVar,
+    TypeAlias,
     cast,
 )
 
@@ -31,6 +31,9 @@ from sqlalchemy.orm import (
 from sqlalchemy.orm.exc import MultipleResultsFound, NoResultFound
 from sqlalchemy.sql import operators
 
+# `TypeVar` from here, for the default that keeps `Page[User]` the counted one.
+from typing_extensions import TypeVar
+
 from ._model import resolve_alias, soft_delete_column
 from .exceptions import (
     BulkQueryError,
@@ -63,9 +66,11 @@ __all__ = [
     "NullsPlacement",
     "OrderBy",
     "Page",
+    "UncountedPage",
     "one_row",
     "one_row_or_none",
     "orderable",
+    "orderable_columns",
     "ordered",
 ]
 
@@ -100,6 +105,8 @@ ONLY = "only"
 
 ModelT = TypeVar("ModelT")
 OtherT = TypeVar("OtherT")
+TotalT = TypeVar("TotalT", bound="int | None", default=int)
+"""What a page knows about its total: an `int`, or `None` when nobody counted."""
 RowT = TypeVar("RowT")
 RowT_co = TypeVar("RowT_co", covariant=True)
 
@@ -170,18 +177,19 @@ def _compile_nulls_for_mysql(
 
 
 @dataclass(frozen=True, slots=True)
-class Page(Generic[ModelT]):
-    """One page of rows, and how many there are in total."""
+class Page(Generic[ModelT, TotalT]):
+    """One page of rows, and how many there are in total.
 
-    items: Sequence[ModelT]
-    total: int | None
-    """How many rows match, or None for a page read without counting them."""
+    ``Page[User]`` is the counted page, whose ``total`` is an `int`.
+    ``page(total=False)`` returns a `Page[User, None]` instead, so the code
+    reading it is not asked about a total nobody counted.
+    """
 
+    items: Sequence[ModelT]
+    total: TotalT
     limit: int
     offset: int
-
     has_next: bool = False
-    """Whether a page follows this one."""
 
     def __post_init__(self) -> None:
         if self.total is not None:
@@ -189,7 +197,7 @@ class Page(Generic[ModelT]):
                 self, "has_next", self.offset + len(self.items) < self.total
             )
 
-    def map(self, transform: Callable[[ModelT], OtherT]) -> Page[OtherT]:
+    def map(self, transform: Callable[[ModelT], OtherT]) -> Page[OtherT, TotalT]:
         """Return the page with every row put through ``transform``.
 
         ```python
@@ -201,7 +209,7 @@ class Page(Generic[ModelT]):
     def map_all(
         self,
         transform: Callable[[Sequence[ModelT]], Sequence[OtherT]],
-    ) -> Page[OtherT]:
+    ) -> Page[OtherT, TotalT]:
         """Return the page with the rows put through ``transform`` together.
 
         For work that reads better in one go than row by row: one query for
@@ -209,7 +217,7 @@ class Page(Generic[ModelT]):
         """
         return self.with_items(transform(self.items))
 
-    def with_items(self, items: Sequence[OtherT]) -> Page[OtherT]:
+    def with_items(self, items: Sequence[OtherT]) -> Page[OtherT, TotalT]:
         """Return the page carrying these rows instead, counts unchanged.
 
         What an asynchronous transform needs: `page.with_items(await serialize(...))`.
@@ -229,16 +237,24 @@ class Page(Generic[ModelT]):
         )
 
 
+UncountedPage: TypeAlias = Page[ModelT, None]
+"""A page read with ``total=False``, which counted nothing.
+
+The same class, named for what a signature means by it:
+
+```python
+def feed(page: UncountedPage[User]) -> Response: ...
+```
+"""
+
+
 @dataclass(frozen=True, slots=True)
 class CursorPage(Generic[ModelT]):
     """One page of rows, and the cursors that read the ones either side."""
 
     items: Sequence[ModelT]
     next_cursor: str | None = None
-    """Hand it back as ``cursor`` to read on."""
-
     previous_cursor: str | None = None
-    """Hand it back as ``cursor`` to read the page in front of this one."""
 
     @property
     def has_next(self) -> bool:
@@ -921,6 +937,29 @@ class BaseQuery(Generic[ModelT]):
         return _encode(values, backwards=backwards, ordering=ordering_key)
 
 
+def orderable_columns(model: type[Any]) -> Mapping[str, Any]:
+    """Return every mapped column of a model, by name.
+
+    What a model orders by when it declares no ``__orderable__``, and what an
+    ``__orderable__`` that adds to the columns rather than replacing them starts
+    from:
+
+    ```python
+    @classmethod
+    def __orderable__(cls) -> Mapping[str, Any]:
+        return {
+            **orderable_columns(cls),
+            "team": OrderBy(Team.name, join=cls.team),
+        }
+    ```
+
+    Calling `orderable` there instead recurses: it reads the very
+    ``__orderable__`` that is running.
+    """
+    mapper = sa.inspect(model, raiseerr=True)
+    return {attr.key: getattr(model, attr.key) for attr in mapper.column_attrs}
+
+
 def orderable(model: type[Any]) -> Mapping[str, Any]:
     """Return the fields a model can be ordered by name.
 
@@ -930,8 +969,7 @@ def orderable(model: type[Any]) -> Mapping[str, Any]:
     """
     fields = getattr(model, "__orderable__", None)
     if fields is None:
-        mapper = sa.inspect(model, raiseerr=True)
-        return {attr.key: getattr(model, attr.key) for attr in mapper.column_attrs}
+        return orderable_columns(model)
     if callable(fields):
         return fields()
     return {name: _mapped_column(model, name) for name in fields}

{sqlakit-0.5.1 → sqlakit-0.6.0}/sqlakit/asyncio/orm.py

@@ -197,9 +197,19 @@ class Query(BaseQuery[ModelT]):
         """Check whether any row matches."""
         return bool(await self.db.session.scalar(self._exists_statement()))
 
+    @overload
+    async def page(
+        self, *, limit: int, offset: int = 0, total: Literal[True] = True
+    ) -> Page[ModelT]: ...
+
+    @overload
+    async def page(
+        self, *, limit: int, offset: int = 0, total: Literal[False]
+    ) -> Page[ModelT, None]: ...
+
     async def page(
         self, *, limit: int, offset: int = 0, total: bool = True
-    ) -> Page[ModelT]:
+    ) -> Page[ModelT] | Page[ModelT, None]:
         """Read one page of rows, with the total.
 
         The model's key is appended to the ordering, so a row that ties with another

{sqlakit-0.5.1 → sqlakit-0.6.0}/sqlakit/orm.py

@@ -190,7 +190,19 @@ class Query(BaseQuery[ModelT]):
         """Check whether any row matches."""
         return bool(self.db.session.scalar(self._exists_statement()))
 
-    def page(self, *, limit: int, offset: int = 0, total: bool = True) -> Page[ModelT]:
+    @overload
+    def page(
+        self, *, limit: int, offset: int = 0, total: Literal[True] = True
+    ) -> Page[ModelT]: ...
+
+    @overload
+    def page(
+        self, *, limit: int, offset: int = 0, total: Literal[False]
+    ) -> Page[ModelT, None]: ...
+
+    def page(
+        self, *, limit: int, offset: int = 0, total: bool = True
+    ) -> Page[ModelT] | Page[ModelT, None]:
         """Read one page of rows, with the total.
 
         The model's key is appended to the ordering, so a row that ties with another