sqlakit 0.5.1__tar.gz → 0.7.0__tar.gz

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

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

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

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

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

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

{sqlakit-0.5.1 → sqlakit-0.7.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
@@ -25,6 +32,7 @@ from .exceptions import (
     MissingDatabaseUrlError,
     MissingDefaultDatabaseError,
     MissingDependencyError,
+    MissingRegistryError,
     MissingSessionError,
     MultipleInstancesFoundError,
     NullCursorValueError,
@@ -80,6 +88,7 @@ __all__ = [
     "MissingDatabaseUrlError",
     "MissingDefaultDatabaseError",
     "MissingDependencyError",
+    "MissingRegistryError",
     "MissingSessionError",
     "MultipleInstancesFoundError",
     "NullCursorValueError",
@@ -102,6 +111,7 @@ __all__ = [
     "Transaction",
     "TransactionRolledBackError",
     "UncomparableOrderingError",
+    "UncountedPage",
     "UnknownDatabaseError",
     "UnknownFieldError",
     "UnknownImportPathError",
@@ -111,4 +121,5 @@ __all__ = [
     "db",
     "import_models",
     "import_string",
+    "orderable_columns",
 ]

{sqlakit-0.5.1 → sqlakit-0.7.0}/sqlakit/_model.py

@@ -22,7 +22,7 @@ from sqlalchemy.orm.attributes import set_committed_value
 from .exceptions import (
     DEFAULT_ALIAS,
     DetachedInstanceError,
-    MissingDefaultDatabaseError,
+    MissingRegistryError,
     SQLAKitError,
     UnknownFieldError,
 )
@@ -120,7 +120,7 @@ class BaseModel(Generic[DatabaseT]):
         cls.__db__ = db
 
     @classmethod
-    def register_db(cls, db: DatabaseT, *, alias: str) -> None:
+    def register_db(cls, db: DatabaseT, *, alias: str | None = None) -> None:
         """Give this model a database under an alias, and the ones under it too.
 
         The registry it goes in belongs to this class, so nothing global is
@@ -138,11 +138,21 @@ class BaseModel(Generic[DatabaseT]):
         the open `using()` block, in that order. A model left on the default
         alias follows `using()`, which is what makes the switch above work.
 
+        Without an alias it points the model at that database, the same as
+        [`set_db`][sqlakit.orm.ModelMixin.set_db], for an application with one:
+
+        ```python
+        Base.register_db(Database(DB_URL))
+        ```
+
         Raises:
             AliasInUseError: if another database holds that alias.
             DefaultAliasError: if the alias is `default`.
 
         """
+        if alias is None:
+            cls.set_db(db)
+            return
         if _owns_no_registry(cls):
             # A registry of its own: registering into the importable one would
             # configure it for every model in the process. A class under one
@@ -257,16 +267,21 @@ def db_for(model: type[Any]) -> BaseDatabase[Any, Any]:
     placement = model.__db__
     if isinstance(placement, str):
         if source is None:
-            raise MissingDefaultDatabaseError
+            raise MissingRegistryError(model.__name__, placement)
         return source[placement]
     return placement
 
 
 def resolve_alias(model: type[Any], alias: str) -> BaseDatabase[Any, Any]:
-    """Return the database a model knows under that alias."""
+    """Return the database a model knows under that alias.
+
+    Raises:
+        MissingRegistryError: if the model looks aliases up nowhere.
+
+    """
     source = getattr(model, "__dbs__", None)
     if source is None:
-        raise MissingDefaultDatabaseError
+        raise MissingRegistryError(model.__name__, alias)
     return source[alias]
 
 

{sqlakit-0.5.1 → sqlakit-0.7.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:
@@ -278,10 +294,11 @@ class CursorPage(Generic[ModelT]):
 
 
 class OrderBy(NamedTuple):
-    """A field to order by that lives in another table.
+    """A field to order by that a foreign key cannot reach on its own.
 
-    Name the table, or the relationship that reaches it, and a query ordered by
-    that field joins it once, however many fields name it:
+    A plain column of another table needs none of this: naming it in
+    ``__orderable__`` joins its table on the key between them. This is for what
+    that cannot answer, an alias, a subquery, or two paths to one table:
 
     ```python
     {"team": OrderBy(Team.name, join=cls.team)}
@@ -290,11 +307,16 @@ class OrderBy(NamedTuple):
     Join what holds one row. A collection multiplies the rows, and a page of
     multiplied rows counts wrong: join a subquery that aggregates them instead,
     with the ``on`` it needs.
+
+    The join is an outer one, so ordering by the field returns the rows with
+    nothing on the other side as well. ``outer=False`` makes it an inner join,
+    which drops them, and ``nulls`` on `order_by` says where they go.
     """
 
     expression: Any
     join: Any = None
     on: Any = None
+    outer: bool = True
 
 
 class SupportsClause(Protocol):
@@ -921,6 +943,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 +975,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}
@@ -975,9 +1019,9 @@ def ordered(
         clause, join = _ordering_for(criterion, fields, ignore_case=folded)
         clauses.append(_with_nulls(clause, nulls))
         if join is not None:
-            target, onclause = join
+            target, onclause, outer = join
             if not _is_joined(select, target):
-                select = select.join(target, onclause)
+                select = select.join(target, onclause, isouter=outer)
     return select.order_by(*clauses)
 
 
@@ -989,16 +1033,16 @@ def _ordering_for(
 ) -> 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)
+        return criterion.expression, (criterion.join, criterion.on, criterion.outer)
     if not isinstance(criterion, str):
         return criterion, None
     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)
+        column, join = field.expression, (field.join, field.on, field.outer)
     else:
-        column, join = field, None
+        column, join = field, _join_for(field)
     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
@@ -1117,6 +1161,21 @@ def _flatten(criteria: Iterable[Any]) -> Iterator[Any]:
             yield criterion
 
 
+def _join_for(field: Any) -> tuple[Any, None, bool] | None:  # noqa: ANN401
+    """Return the table a field lives in, for a field that is a plain column.
+
+    A column of another table is reachable only through a join, and `SQLAlchemy`
+    works the condition out from the foreign key. An expression may name several
+    tables or none, so it is left alone: `OrderBy` says what to join for those,
+    as it does for an alias or a subquery.
+    """
+    column = _as_column(field)
+    if not isinstance(column, sa.Column):
+        return None
+    table = getattr(column, "table", None)
+    return None if table is None else (table, None, True)
+
+
 def _is_joined(select: sa.Select[Any], target: Any) -> bool:  # noqa: ANN401
     """Whether this statement already reaches what a field needs."""
     wanted = _join_identity(target)

{sqlakit-0.5.1 → sqlakit-0.7.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.7.0}/sqlakit/exceptions.py

@@ -22,6 +22,7 @@ __all__ = [
     "MissingDatabaseUrlError",
     "MissingDefaultDatabaseError",
     "MissingDependencyError",
+    "MissingRegistryError",
     "MissingSessionError",
     "MultipleInstancesFoundError",
     "NullCursorValueError",
@@ -140,6 +141,20 @@ class UnknownDatabaseError(SQLAKitError, KeyError):
         )
 
 
+class MissingRegistryError(SQLAKitError, ValueError):
+    """Raised when a model has nowhere to look a database alias up."""
+
+    def __init__(self, model: str, alias: str | None = None) -> None:
+        self.model = model
+        self.alias = alias
+        named = f"`{alias}`" if alias is not None else "an alias"
+        super().__init__(
+            f"`{model}` has no registry to look {named} up in. Pass the "
+            f"database itself instead of its name, or set `__dbs__` on the "
+            f"model to the registry that holds it."
+        )
+
+
 class MissingDefaultDatabaseError(SQLAKitError, ValueError):
     """Raised when a configuration keyed by alias carries no default."""
 

{sqlakit-0.5.1 → sqlakit-0.7.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