sqlakit 0.9.0__tar.gz → 0.10.0__tar.gz

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

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

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

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

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

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

{sqlakit-0.9.0 → sqlakit-0.10.0}/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,
@@ -206,6 +207,7 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
         engine_args: EngineArgs | None = None,
         session_args: SessionArgs | None = None,
         templates: TemplatesLike | None = None,
+        alias: str | None = None,
         **parts: Unpack[UrlParts],
     ) -> None:
         """Build a database on ``url``, or on the parts to make one from.
@@ -220,8 +222,14 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
         )
 
         Database(DB_URL, templates="app/sql")  # where `sql` reads templates from
+        Database(WAREHOUSE_URL, alias="warehouse")  # what a recording calls it
         ```
 
+        ``alias`` is the name a recorded statement carries, for telling two
+        databases apart in a log or on the debug server's page. A registry
+        names the databases it holds after the aliases they are registered
+        under, so it is worth setting on a database you keep yourself.
+
         Raises:
             MissingDatabaseUrlError: if given neither a ``url`` nor the parts to
                 build one.
@@ -258,7 +266,7 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
         self._listening = 0
         self._listened: Any = None
         self._listening_lock = threading.Lock()
-        self._name = DEFAULT_ALIAS
+        self._name = alias or DEFAULT_ALIAS
 
     def __repr__(self) -> str:
         return f"{type(self).__name__}({self.url.render_as_string()!r})"
@@ -703,6 +711,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 +726,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 +754,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)
@@ -769,6 +788,7 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
         skip_queries_from: Sequence[str | PathLike[str]] = (),
         into: Recording | None = None,
         debugserver: DebugServer | tuple[str, int] | None = None,
+        using: str | DatabaseT | Sequence[str | DatabaseT] | None = None,
     ) -> Iterator[Recording]:
         """Record every database this registry has, not the default one alone.
 
@@ -779,11 +799,26 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
         record.databases  # ("default", "warehouse")
         ```
 
-        Statements say which database ran them. `db["warehouse"].recording()` records
-        that one on its own.
+        Statements say which database ran them. ``using`` narrows the block to
+        the databases named, by alias or in person, as `assert_queries` takes
+        them:
+
+        ```python
+        with db.recording(using="warehouse"):
+            move_the_reports()
+
+        with db.recording(using=["default", "warehouse"]):
+            move_the_reports()
+        ```
+
+        `db["warehouse"].recording()` records that one on its own.
+
+        Raises:
+            UnknownDatabaseError: if ``using`` names an alias nothing holds.
+
         """
         together = Recording(label=label) if into is None else into
-        databases = (self, *self._aliased.values())
+        databases = self._recorded(using)
         with ExitStack() as stack:
             for db in databases:
                 stack.enter_context(
@@ -805,6 +840,15 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
                 if debugserver is not None:
                     send_recording(together, debugserver)
 
+    def _recorded(
+        self, using: str | DatabaseT | Sequence[str | DatabaseT] | None
+    ) -> tuple[Any, ...]:
+        """Return the databases a recording watches: the ones named, or all of them."""
+        if using is None:
+            return tuple(self[alias] for alias in self.aliases)
+        asked = using if isinstance(using, (list, tuple, set, frozenset)) else (using,)
+        return tuple(self[one] if isinstance(one, str) else one for one in asked)
+
     @staticmethod
     def _named(alias: str, db: DatabaseT) -> DatabaseT:
         """Let a database say which alias it answers to, when it is recorded."""
@@ -888,7 +932,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 +1012,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 +1048,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 +1058,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.10.0}/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.10.0}/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.10.0}/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)