sqlakit 0.6.0__tar.gz → 0.7.1__tar.gz

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

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

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

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

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

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

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

@@ -18,6 +18,7 @@ from .exceptions import (
     AsyncFilterError,
     BulkQueryError,
     ConflictingDatabaseUrlError,
+    ConflictingJoinError,
     DatabaseAlreadyConfiguredError,
     DatabaseNotConfiguredError,
     DefaultAliasError,
@@ -32,6 +33,7 @@ from .exceptions import (
     MissingDatabaseUrlError,
     MissingDefaultDatabaseError,
     MissingDependencyError,
+    MissingRegistryError,
     MissingSessionError,
     MultipleInstancesFoundError,
     NullCursorValueError,
@@ -68,6 +70,7 @@ __all__ = [
     "AsyncFilterError",
     "BulkQueryError",
     "ConflictingDatabaseUrlError",
+    "ConflictingJoinError",
     "CursorPage",
     "Database",
     "DatabaseAlreadyConfiguredError",
@@ -87,6 +90,7 @@ __all__ = [
     "MissingDatabaseUrlError",
     "MissingDefaultDatabaseError",
     "MissingDependencyError",
+    "MissingRegistryError",
     "MissingSessionError",
     "MultipleInstancesFoundError",
     "NullCursorValueError",

{sqlakit-0.6.0 → sqlakit-0.7.1}/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.6.0 → sqlakit-0.7.1}/sqlakit/_query.py

@@ -37,6 +37,7 @@ from typing_extensions import TypeVar
 from ._model import resolve_alias, soft_delete_column
 from .exceptions import (
     BulkQueryError,
+    ConflictingJoinError,
     InstanceNotFoundError,
     InvalidCursorError,
     InvalidNullsError,
@@ -294,10 +295,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)}
@@ -306,11 +308,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):
@@ -1009,13 +1016,15 @@ def ordered(
         else {_field_named(one, fields) for one in ignore_case}
     )
     clauses = []
+    joined: dict[str, Any] = {}
     for criterion in named:
         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
+            _reject_conflicting_join(joined, target, onclause)
             if not _is_joined(select, target):
-                select = select.join(target, onclause)
+                select = select.join(target, onclause, isouter=outer)
     return select.order_by(*clauses)
 
 
@@ -1027,16 +1036,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
@@ -1155,6 +1164,48 @@ 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 _reject_conflicting_join(
+    joined: dict[str, Any],
+    target: Any,  # noqa: ANN401
+    onclause: Any,  # noqa: ANN401
+) -> None:
+    """Refuse a second join of one table on another condition.
+
+    A statement joins a table once, so the second condition would be dropped
+    and the field would order by the first one's rows.
+
+    Raises:
+        ConflictingJoinError: if the table is already joined on something else.
+
+    """
+    identity = _join_identity(target)
+    if identity is None:
+        return
+    if identity not in joined:
+        joined[identity] = onclause
+        return
+    first = joined[identity]
+    if first is None or onclause is None:
+        return
+    if not first.compare(onclause):
+        raise ConflictingJoinError(identity)
+
+
 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.6.0 → sqlakit-0.7.1}/sqlakit/exceptions.py

@@ -9,6 +9,7 @@ __all__ = [
     "AsyncFilterError",
     "BulkQueryError",
     "ConflictingDatabaseUrlError",
+    "ConflictingJoinError",
     "DatabaseAlreadyConfiguredError",
     "DatabaseNotConfiguredError",
     "DefaultAliasError",
@@ -22,6 +23,7 @@ __all__ = [
     "MissingDatabaseUrlError",
     "MissingDefaultDatabaseError",
     "MissingDependencyError",
+    "MissingRegistryError",
     "MissingSessionError",
     "MultipleInstancesFoundError",
     "NullCursorValueError",
@@ -140,6 +142,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."""
 
@@ -411,6 +427,18 @@ class InvalidOrderFieldError(SQLAKitError, TypeError):
         )
 
 
+class ConflictingJoinError(SQLAKitError, TypeError):
+    """Raised when two ordering fields join one table on different conditions."""
+
+    def __init__(self, table: str) -> None:
+        self.table = table
+        super().__init__(
+            f"Two ordering fields join `{table}` on different conditions, and a "
+            f"statement joins it once. Alias it with `sqlalchemy.orm.aliased` so "
+            f"that each field joins an alias of its own."
+        )
+
+
 class InvalidNullsError(SQLAKitError, ValueError):
     """Raised when ``order_by`` is told to put the nulls somewhere else.