sqlakit 0.5.0__tar.gz → 0.5.1__tar.gz

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

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

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

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

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

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

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

@@ -7,11 +7,13 @@ 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 +57,7 @@ __all__ = [
     "DEFAULT_ALIAS",
     "DEFAULT_ENGINE_ARGS",
     "DEFAULT_SESSION_ARGS",
+    "AliasInUseError",
     "AsyncFilterError",
     "BulkQueryError",
     "ConflictingDatabaseUrlError",
@@ -64,6 +67,7 @@ __all__ = [
     "DatabaseConfig",
     "DatabaseNotConfiguredError",
     "Databases",
+    "DefaultAliasError",
     "DetachedInstanceError",
     "EngineArgs",
     "InstanceNotFoundError",

{sqlakit-0.5.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,
@@ -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.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.5.0 → sqlakit-0.5.1}/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."""