sqlakit 0.4.0__tar.gz → 0.5.1__tar.gz

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

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

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

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

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

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

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

@@ -7,15 +7,18 @@ from ._registry import Databases, db
 from ._routing import Router
 from .exceptions import (
     DEFAULT_ALIAS,
+    AliasInUseError,
     AsyncFilterError,
     BulkQueryError,
     ConflictingDatabaseUrlError,
     DatabaseAlreadyConfiguredError,
     DatabaseNotConfiguredError,
+    DefaultAliasError,
     DetachedInstanceError,
     InstanceNotFoundError,
     InvalidCursorError,
     InvalidDatabaseConfigError,
+    InvalidNullsError,
     InvalidOrderFieldError,
     KeyLookupError,
     MissingConnectionError,
@@ -40,13 +43,21 @@ 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",
     "DEFAULT_ALIAS",
     "DEFAULT_ENGINE_ARGS",
     "DEFAULT_SESSION_ARGS",
+    "AliasInUseError",
     "AsyncFilterError",
     "BulkQueryError",
     "ConflictingDatabaseUrlError",
@@ -56,11 +67,13 @@ __all__ = [
     "DatabaseConfig",
     "DatabaseNotConfiguredError",
     "Databases",
+    "DefaultAliasError",
     "DetachedInstanceError",
     "EngineArgs",
     "InstanceNotFoundError",
     "InvalidCursorError",
     "InvalidDatabaseConfigError",
+    "InvalidNullsError",
     "InvalidOrderFieldError",
     "KeyLookupError",
     "MissingConnectionError",
@@ -85,6 +98,7 @@ __all__ = [
     "Statement",
     "StrayParameterError",
     "TemplateNotFoundError",
+    "TemplatesLike",
     "Transaction",
     "TransactionRolledBackError",
     "UncomparableOrderingError",

{sqlakit-0.4.0 → sqlakit-0.5.1}/sqlakit/_base.py

@@ -35,9 +35,11 @@ from ._recording import (
 from ._routing import Router, as_router
 from .exceptions import (
     DEFAULT_ALIAS,
+    AliasInUseError,
     ConflictingDatabaseUrlError,
     DatabaseAlreadyConfiguredError,
     DatabaseNotConfiguredError,
+    DefaultAliasError,
     MissingConnectionError,
     MissingDatabaseUrlError,
     MissingDefaultDatabaseError,
@@ -49,16 +51,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",
@@ -691,6 +695,31 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
     def __contains__(self, alias: str) -> bool:
         return alias == DEFAULT_ALIAS or alias in self._aliased
 
+    def register(self, alias: str, db: DatabaseT) -> None:
+        """Put a database already built under an alias.
+
+        `configure` takes settings and builds the databases. This takes one you
+        built yourself, for a shard that only exists once the application is
+        running, or for a registry that never reads settings at all:
+
+        ```python
+        db.register("shard-7", Database(SHARD_URL))
+        ```
+
+        The alias has to be free. Replacing one under a name already in use
+        would leave the code that holds the old database talking to it.
+
+        Raises:
+            AliasInUseError: if another database holds that alias.
+            DefaultAliasError: if the alias is `default`, which this registry is.
+
+        """
+        if alias == DEFAULT_ALIAS:
+            raise DefaultAliasError
+        if alias in self._aliased:
+            raise AliasInUseError(alias)
+        self._aliased[alias] = self._named(alias, db)
+
     @contextmanager
     def recording(
         self,

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

@@ -37,7 +37,9 @@ __all__ = [
     "BaseModel",
     "BaseSoftDeletes",
     "DatabaseDescriptor",
+    "DatabaseRegistry",
     "DatabaseSource",
+    "RegistryDescriptor",
     "db_for",
     "resolve_alias",
     "soft_delete_column",
@@ -66,6 +68,19 @@ class DatabaseDescriptor(Generic[DatabaseT]):
         return cast("DatabaseT", db_for(owner))
 
 
+class DatabaseRegistry(DatabaseSource, Protocol):
+    """A source that also takes a database under an alias it does not have."""
+
+    def register(self, alias: str, db: Any) -> None: ...  # noqa: ANN401
+
+
+class RegistryDescriptor:
+    """Reads ``__dbs__``, on the class as well as on an instance."""
+
+    def __get__(self, instance: object | None, owner: type[Any]) -> Any:  # noqa: ANN401
+        return owner.__dbs__
+
+
 class BaseModel(Generic[DatabaseT]):
     """What the sync and async models share: everything that is not IO.
 
@@ -87,6 +102,7 @@ class BaseModel(Generic[DatabaseT]):
     # Unannotated on purpose: an annotation here reads as a field to
     # pydantic, and SQLModel models would refuse to build.
     db = DatabaseDescriptor[DatabaseT]()
+    dbs = RegistryDescriptor()
 
     @classmethod
     def set_db(cls, db: str | DatabaseT) -> None:
@@ -103,6 +119,37 @@ class BaseModel(Generic[DatabaseT]):
         """
         cls.__db__ = db
 
+    @classmethod
+    def register_db(cls, db: DatabaseT, *, alias: str) -> 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
+        configured and two sets of models can each have their own `shard`:
+
+        ```python
+        Base.register_db(Database(DB1_URL), alias="db1")
+        Base.register_db(Database(DB2_URL), alias="db2")
+
+        with Base.dbs.using("db2").transaction():
+            User(name="ada").save()
+        ```
+
+        Which database a model resolves to is still `__db__`, the routers and
+        the open `using()` block, in that order. A model left on the default
+        alias follows `using()`, which is what makes the switch above work.
+
+        Raises:
+            AliasInUseError: if another database holds that alias.
+            DefaultAliasError: if the alias is `default`.
+
+        """
+        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
+            # that already has its own registers into that one.
+            cls.__dbs__ = type(cls.__dbs__)()
+        cast("DatabaseRegistry", cls.__dbs__).register(alias, db)
+
     def update(self, values: Mapping[str, Any]) -> Self:
         """Set these fields on this instance, and return it.
 
@@ -187,6 +234,16 @@ class BaseModel(Generic[DatabaseT]):
             self.db.session.add(self)
 
 
+def _owns_no_registry(model: type[Any]) -> bool:
+    """Whether this model still looks its aliases up in the importable registry."""
+    declared = next(
+        (klass for klass in model.__mro__ if "__dbs__" in klass.__dict__), None
+    )
+    return (
+        declared is None or declared.__module__.split(".")[0] == __name__.split(".")[0]
+    )
+
+
 def db_for(model: type[Any]) -> BaseDatabase[Any, Any]:
     """Return the database a model lives on.
 

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

@@ -5,15 +5,18 @@ from sqlalchemy.orm import exc as sa_exc
 DEFAULT_ALIAS = "default"
 
 __all__ = [
+    "AliasInUseError",
     "AsyncFilterError",
     "BulkQueryError",
     "ConflictingDatabaseUrlError",
     "DatabaseAlreadyConfiguredError",
     "DatabaseNotConfiguredError",
+    "DefaultAliasError",
     "DetachedInstanceError",
     "InstanceNotFoundError",
     "InvalidCursorError",
     "InvalidDatabaseConfigError",
+    "InvalidNullsError",
     "InvalidOrderFieldError",
     "MissingConnectionError",
     "MissingDatabaseUrlError",
@@ -106,6 +109,27 @@ class DatabaseAlreadyConfiguredError(SQLAKitError, RuntimeError):
         super().__init__(message)
 
 
+class AliasInUseError(SQLAKitError, ValueError):
+    """Raised when registering a database under an alias another one holds."""
+
+    def __init__(self, alias: str) -> None:
+        self.alias = alias
+        super().__init__(
+            f"`{alias}` is already registered. Dispose of that database before "
+            "registering another under the same name."
+        )
+
+
+class DefaultAliasError(SQLAKitError, ValueError):
+    """Raised when registering a database as the default one."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            f"`{DEFAULT_ALIAS}` is the registry itself. Configure it with "
+            "`configure()`, and register the others under their own names."
+        )
+
+
 class UnknownDatabaseError(SQLAKitError, KeyError):
     """Raised when asking for a database alias that was never configured."""
 
@@ -387,6 +411,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.1}/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.1}/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):