sqlakit 0.5.0__tar.gz → 0.6.0__tar.gz

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

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

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

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

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

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

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

@@ -1,17 +1,26 @@
 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
 from .exceptions import (
     DEFAULT_ALIAS,
+    AliasInUseError,
     AsyncFilterError,
     BulkQueryError,
     ConflictingDatabaseUrlError,
     DatabaseAlreadyConfiguredError,
     DatabaseNotConfiguredError,
+    DefaultAliasError,
     DetachedInstanceError,
     InstanceNotFoundError,
     InvalidCursorError,
@@ -55,6 +64,7 @@ __all__ = [
     "DEFAULT_ALIAS",
     "DEFAULT_ENGINE_ARGS",
     "DEFAULT_SESSION_ARGS",
+    "AliasInUseError",
     "AsyncFilterError",
     "BulkQueryError",
     "ConflictingDatabaseUrlError",
@@ -64,6 +74,7 @@ __all__ = [
     "DatabaseConfig",
     "DatabaseNotConfiguredError",
     "Databases",
+    "DefaultAliasError",
     "DetachedInstanceError",
     "EngineArgs",
     "InstanceNotFoundError",
@@ -98,6 +109,7 @@ __all__ = [
     "Transaction",
     "TransactionRolledBackError",
     "UncomparableOrderingError",
+    "UncountedPage",
     "UnknownDatabaseError",
     "UnknownFieldError",
     "UnknownImportPathError",
@@ -107,4 +119,5 @@ __all__ = [
     "db",
     "import_models",
     "import_string",
+    "orderable_columns",
 ]

{sqlakit-0.5.0 → sqlakit-0.6.0}/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,
@@ -693,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.5.0 → sqlakit-0.6.0}/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.5.0 → 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.0 → 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.0 → sqlakit-0.6.0}/sqlakit/exceptions.py

@@ -5,11 +5,13 @@ from sqlalchemy.orm import exc as sa_exc
 DEFAULT_ALIAS = "default"
 
 __all__ = [
+    "AliasInUseError",
     "AsyncFilterError",
     "BulkQueryError",
     "ConflictingDatabaseUrlError",
     "DatabaseAlreadyConfiguredError",
     "DatabaseNotConfiguredError",
+    "DefaultAliasError",
     "DetachedInstanceError",
     "InstanceNotFoundError",
     "InvalidCursorError",
@@ -107,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."""
 

{sqlakit-0.5.0 → 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