sqlakit 0.9.0__tar.gz → 0.9.1__tar.gz

{sqlakit-0.9.0 → sqlakit-0.9.1}/PKG-INFO

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

{sqlakit-0.9.0 → sqlakit-0.9.1}/pyproject.toml

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

{sqlakit-0.9.0 → sqlakit-0.9.1}/pyproject.toml.orig

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

{sqlakit-0.9.0 → sqlakit-0.9.1}/sqlakit/_base.py

@@ -39,6 +39,7 @@ from ._recording import (
 from ._routing import Router, as_router
 from .exceptions import (
     DEFAULT_ALIAS,
+    REGISTERED_DEFAULT,
     AliasInUseError,
     ConflictingDatabaseUrlError,
     DatabaseAlreadyConfiguredError,
@@ -703,6 +704,7 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
 
     def __init__(self) -> None:
         """Leave everything to [`configure`][sqlakit.Databases.configure]."""
+        self._default: DatabaseT | None = None
         self._aliased: dict[str, DatabaseT] = {}
         self._routers: tuple[Any, ...] = ()
         self._using: ContextVar[str | None] = ContextVar(
@@ -717,14 +719,15 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
     def __getitem__(self, alias: str) -> Self | DatabaseT:
         """Return the database configured as ``alias``.
 
-        ``db["default"]`` is this one: what the code reaches without an alias.
+        ``db["default"]`` is what the code reaches without an alias: this
+        registry, or the database `register` was given for that name.
 
         Raises:
             UnknownDatabaseError: if nothing is configured under that alias.
 
         """
         if alias == DEFAULT_ALIAS:
-            return self
+            return self if self._default is None else self._default
         try:
             return self._aliased[alias]
         except KeyError:
@@ -744,16 +747,25 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
         db.register("shard-7", Database(SHARD_URL))
         ```
 
+        `default` is the alias the code reaches without naming one, and a
+        database registered under it stands where `configure` would have built
+        one. The registry itself is then a registry alone: reach that database
+        as `db["default"]`, or through the models that live on it.
+
         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.
+            DefaultAliasError: if `default` is asked for and the registry
+                already has one.
 
         """
         if alias == DEFAULT_ALIAS:
-            raise DefaultAliasError
+            if self.is_configured:
+                raise DefaultAliasError
+            self._default = self._named(alias, db)
+            return
         if alias in self._aliased:
             raise AliasInUseError(alias)
         self._aliased[alias] = self._named(alias, db)
@@ -783,7 +795,7 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
         that one on its own.
         """
         together = Recording(label=label) if into is None else into
-        databases = (self, *self._aliased.values())
+        databases = tuple(self[alias] for alias in self.aliases)
         with ExitStack() as stack:
             for db in databases:
                 stack.enter_context(
@@ -888,7 +900,12 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
 
     @property
     def is_configured(self) -> bool:
-        """Whether [`configure`][sqlakit.Databases.configure] has been called."""
+        """Whether this registry has a default database to reach."""
+        return "url" in self.__dict__ or self._default is not None
+
+    @property
+    def _built_its_own(self) -> bool:
+        """Whether the default database is this registry, `configure` having built it."""
         return "url" in self.__dict__
 
     @overload
@@ -963,6 +980,8 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
                 ``InvalidDatabaseConfigError``.
 
         """
+        if self._default is not None:
+            raise DefaultAliasError
         if not isinstance(url, Mapping):
             self._reject_if_connected()
             super().__init__(url, engine_args, session_args, templates, **parts)
@@ -997,7 +1016,7 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
         self.route(*routers)
 
     def _reject_if_connected(self) -> None:
-        connected = self.is_configured and self._engine is not None
+        connected = self._built_its_own and self._engine is not None
         if connected or any(
             db._engine is not None  # noqa: SLF001
             for db in self._aliased.values()
@@ -1007,19 +1026,47 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
     if not TYPE_CHECKING:
         # Hidden from type checkers: seeing it, they would take every attribute
         # to exist and stop reporting typos. It is reached when normal lookup
-        # fails, which is what an unconfigured database looks like.
+        # fails, which is what a registry with no database of its own looks
+        # like, from the outside and from its own methods.
         def __getattr__(self, name: str) -> object:
-            # Only the database's own attributes are worth explaining. Anything
-            # else is a name that does not exist, and saying so is what lets
-            # `hasattr`, `copy` and every library that introspects work.
-            if (
-                not name.startswith("_")
-                and hasattr(type(self), name)
-                and not self.is_configured
-            ):
-                raise DatabaseNotConfiguredError from None
-            raise AttributeError(name)
-
+            # Only the database half is worth explaining. Anything else is a
+            # name that does not exist, and saying so is what lets `hasattr`,
+            # `copy` and every library that introspects work.
+            state = self.__dict__
+            if "url" in state:
+                raise AttributeError(name)
+            asked_as_a_database = name in DATABASE_STATE or (
+                not name.startswith("_") and hasattr(type(self), name)
+            )
+            if not asked_as_a_database:
+                raise AttributeError(name)
+            if state.get("_default") is not None:
+                raise DatabaseNotConfiguredError(REGISTERED_DEFAULT) from None
+            raise DatabaseNotConfiguredError from None
+
+
+DATABASE_STATE = frozenset(
+    # What `BaseDatabase.__init__` sets. A registry has these once it has a
+    # database of its own, and reaching for one before then is the question
+    # `DatabaseNotConfiguredError` answers, whichever method asked.
+    {
+        "url",
+        "templates",
+        "engine_args",
+        "session_args",
+        "_sessionmaker",
+        "_engine_lock",
+        "_scope",
+        "_outer",
+        "_recordings",
+        "_stacks",
+        "_skipped",
+        "_listening",
+        "_listened",
+        "_listening_lock",
+        "_name",
+    }
+)
 
 _CONTROL = frozenset(
     # Transaction control is not a query, and which of these reach a cursor

{sqlakit-0.9.0 → sqlakit-0.9.1}/sqlakit/_model.py

@@ -138,27 +138,29 @@ 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:
+        Without an alias it goes in as the default one, which is where a model
+        that names no database lives:
 
         ```python
         Base.register_db(Database(DB_URL))
         ```
 
+        The registry answers for it either way, so `dbs["default"]`,
+        `dbs.transactions()` and `using()` all reach what was registered.
+        [`set_db`][sqlakit.orm.ModelMixin.set_db] is the other way to name a
+        database, and it leaves the registry out of it.
+
         Raises:
             AliasInUseError: if another database holds that alias.
-            DefaultAliasError: if the alias is `default`.
+            DefaultAliasError: if the registry already has a default database.
 
         """
-        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
             # that already has its own registers into that one.
             cls.__dbs__ = type(cls.__dbs__)()
-        cast("DatabaseRegistry", cls.__dbs__).register(alias, db)
+        cast("DatabaseRegistry", cls.__dbs__).register(alias or DEFAULT_ALIAS, db)
 
     def update(self, values: Mapping[str, Any]) -> Self:
         """Set these fields on this instance, and return it.

{sqlakit-0.9.0 → sqlakit-0.9.1}/sqlakit/_registry.py

@@ -52,8 +52,10 @@ class Databases(_DatabaseRegistryMixin[Database], Database):
 
     def dispose(self, *, close: bool = True) -> None:
         """Dispose of every configured database, not just the default one."""
-        if self.is_configured:
+        if self._built_its_own:
             super().dispose(close=close)
+        elif self._default is not None:
+            self._default.dispose(close=close)
         for db in self._aliased.values():
             db.dispose(close=close)
 

{sqlakit-0.9.0 → sqlakit-0.9.1}/sqlakit/asyncio/_registry.py

@@ -47,8 +47,10 @@ class Databases(_DatabaseRegistryMixin[Database], Database):
 
     async def dispose(self, *, close: bool = True) -> None:
         """Dispose of every configured database, not just the default one."""
-        if self.is_configured:
+        if self._built_its_own:
             await super().dispose(close=close)
+        elif self._default is not None:
+            await self._default.dispose(close=close)
         for db in self._aliased.values():
             await db.dispose(close=close)
 

{sqlakit-0.9.0 → sqlakit-0.9.1}/sqlakit/exceptions.py

@@ -85,6 +85,13 @@ class RetryNotSupportedError(SQLAKitError, TypeError):
         super().__init__(message)
 
 
+REGISTERED_DEFAULT = (
+    "This registry did not build the default database, it was registered. "
+    "Reach that one as `db['default']`, or through the models that live on it."
+)
+"""What a registry says when it is asked for connections it does not have."""
+
+
 class DatabaseNotConfiguredError(SQLAKitError, RuntimeError):
     """Raised when the importable database is used before it has a URL."""
 
@@ -123,12 +130,13 @@ class AliasInUseError(SQLAKitError, ValueError):
 
 
 class DefaultAliasError(SQLAKitError, ValueError):
-    """Raised when registering a database as the default one."""
+    """Raised when a registry is given a second default database."""
 
     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."
+            f"This registry already has a `{DEFAULT_ALIAS}` database. "
+            "`configure()` builds one and `register()` hands one over, and a "
+            "registry keeps whichever came first."
         )
 
 

{sqlakit-0.9.0 → sqlakit-0.9.1}/sqlakit/pytest_plugin.py

@@ -172,8 +172,8 @@ def _before_the_test_s_own(item: pytest.Function) -> int:
 def sqlakit_db(sqlakit_base: Any) -> Any:  # noqa: ANN401
     """Return the database the marked tests run on.
 
-    The one the models live on, which is the importable registry unless they
-    were given a `Database` of their own. Override it for a project with no
+    The one the models live on: their registry, which knows every alias, or the
+    `Database` they were given in person. Override it for a project with no
     model layer.
     """
     if sqlakit_base is None:
@@ -185,6 +185,15 @@ def sqlakit_db(sqlakit_base: Any) -> Any:  # noqa: ANN401
                 pytrace=False,
             )
         return importable_db
+    registry = getattr(sqlakit_base, "dbs", None)
+    if (
+        isinstance(getattr(sqlakit_base, "__db__", None), str)
+        and registry is not None
+        and registry.is_configured
+    ):
+        # The models look their aliases up there, so the schema and the
+        # transactions cover every one of them, not the default alone.
+        return registry
     database = getattr(sqlakit_base, "db", None)
     if database is None:
         pytest.fail(