sqlakit 0.10.9__tar.gz → 0.11.1__tar.gz

{sqlakit-0.10.9 → sqlakit-0.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlakit
-Version: 0.10.9
+Version: 0.11.1
 Summary: A toolkit for SQLAlchemy applications.
 Keywords: sqlalchemy,database,orm,sql,asyncio
 Author: Anton Ruhlov
@@ -19,6 +19,7 @@ Classifier: Topic :: Database
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Dist: sqlalchemy>=2.0.22
+Requires-Dist: typing-extensions>=4.13
 Requires-Dist: sqlalchemy[asyncio]>=2.0.22 ; extra == 'asyncio'
 Requires-Dist: sqlparse>=0.6.0 ; extra == 'debug'
 Requires-Dist: jinja2sql>=0.11.0 ; extra == 'sql'

{sqlakit-0.10.9 → sqlakit-0.11.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.10.9"
+version = "0.11.1"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"
@@ -26,7 +26,10 @@ classifiers = [
     "Typing :: Typed",
 ]
 requires-python = ">=3.11"
-dependencies = ["sqlalchemy>=2.0.22"]
+dependencies = [
+    "sqlalchemy>=2.0.22",
+    "typing-extensions>=4.13",
+]
 
 [[project.authors]]
 name = "Anton Ruhlov"
@@ -180,8 +183,8 @@ skip = "./.venv,./site,./uv.lock,./.git,./debugserver/node_modules,./debugserver
 [dependency-groups]
 dev = [
     "pytest>=9.1.1",
-    "ty>=0.0.75",
-    "ruff>=0.16.5",
+    "ty>=0.0.79",
+    "ruff>=0.16.6",
     "poethepoet>=0.48.0",
     "anyio>=4.14.2",
     "trio>=0.34.0",
@@ -208,5 +211,5 @@ docs = [
     "mkdocs>=1.6.1,<2",
     "mkdocs-material>=9.7.7",
     "mkdocstrings[python]>=1.0.6",
-    "ruff>=0.16.3",
+    "ruff>=0.16.6",
 ]

{sqlakit-0.10.9 → sqlakit-0.11.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.10.9"
+version = "0.11.1"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"
@@ -23,6 +23,7 @@ classifiers = [
 requires-python = ">=3.11"
 dependencies = [
     "sqlalchemy>=2.0.22",
+    "typing-extensions>=4.13",
 ]
 
 [project.scripts]
@@ -60,8 +61,8 @@ default-groups = ["dev", "docs"]
 [dependency-groups]
 dev = [
     "pytest>=9.1.1",
-    "ty>=0.0.75",
-    "ruff>=0.16.5",
+    "ty>=0.0.79",
+    "ruff>=0.16.6",
     "poethepoet>=0.48.0",
     "anyio>=4.14.2",
     "trio>=0.34.0",
@@ -88,7 +89,7 @@ docs = [
     "mkdocs>=1.6.1,<2",
     "mkdocs-material>=9.7.7",
     "mkdocstrings[python]>=1.0.6",
-    "ruff>=0.16.3",
+    "ruff>=0.16.6",
 ]
 
 [tool.pytest.ini_options]

{sqlakit-0.10.9 → sqlakit-0.11.1}/sqlakit/_base.py

@@ -470,6 +470,32 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
         """
         return self._outer.get(None) is not None
 
+    @property
+    def aliases(self) -> tuple[str, ...]:
+        """The names this database goes by, which for one database is its own.
+
+        A registry has one for each database it holds. Both carry this, so code
+        that takes either does not have to ask which it was given.
+        """
+        return (self._name,)
+
+    def __getitem__(self, alias: str) -> Any:  # noqa: ANN401
+        """Return this database, under the name it carries.
+
+        `Any` rather than `Self`, so a registry can narrow it to the databases
+        it holds.
+
+        Raises:
+            UnknownDatabaseError: if the alias is another database's.
+
+        """
+        if alias == self._name:
+            return self
+        raise UnknownDatabaseError(alias, self.aliases)
+
+    def __contains__(self, alias: str) -> bool:
+        return alias == self._name
+
     def in_session(self) -> bool:
         """Whether a session is open in the current context.
 
@@ -910,11 +936,15 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
         opened with `using()` stands in for the default database.
         """
         placement = self._routed(model) or model.__db__
+        override = self._using.get()
         if isinstance(placement, str):
-            override = self._using.get()
             if override is not None and placement == DEFAULT_ALIAS:
                 placement = override
             return self[placement]
+        # A model pinned to the database itself follows `using()` as one on the
+        # default alias does, when that database is the one being stood in for.
+        if override is not None and self[DEFAULT_ALIAS] is placement:
+            return self[override]
         return placement
 
     def _routed(self, model: type[Any]) -> str | None:
@@ -940,6 +970,41 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
         """Whether the default database is this registry, `configure` having built it."""
         return "url" in self.__dict__
 
+    if not TYPE_CHECKING:
+        # Hidden from type checkers, which keep reading these off `Database`
+        # and its asyncio twin, signatures and all.
+        def _proxy(name: str, *, attribute: bool = False) -> Any:  # noqa: ANN401, N805
+            """Proxy to the database this registry holds, or call its own.
+
+            A registry handed a default proxies to that database. One that
+            `configure` built calls what it inherits, which `super()` reaches.
+            """
+
+            def reach(self: Any, *args: Any, **kwargs: Any) -> Any:  # noqa: ANN401
+                held = self._default
+                found = (
+                    getattr(held, name) if held is not None else getattr(super(), name)
+                )
+                return found if attribute else found(*args, **kwargs)
+
+            return property(reach) if attribute else reach
+
+        connection = _proxy("connection", attribute=True)
+        engine = _proxy("engine", attribute=True)
+        session = _proxy("session", attribute=True)
+        sql = _proxy("sql", attribute=True)
+        assert_queries = _proxy("assert_queries")
+        autocommit = _proxy("autocommit")
+        connect = _proxy("connect")
+        in_session = _proxy("in_session")
+        in_transaction = _proxy("in_transaction")
+        ping = _proxy("ping")
+        provisioned_tables = _proxy("provisioned_tables")
+        query = _proxy("query")
+        session_factory = _proxy("session_factory")
+        transaction = _proxy("transaction")
+        del _proxy
+
     @overload
     def configure(
         self,

{sqlakit-0.10.9 → sqlakit-0.11.1}/sqlakit/_model.py

@@ -145,7 +145,7 @@ class BaseModel(Generic[DatabaseT]):
         Base.register_db(Database(DB_URL))
         ```
 
-        The registry answers for it either way, so `dbs["default"]`,
+        The registry holds 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.

{sqlakit-0.10.9 → sqlakit-0.11.1}/sqlakit/exceptions.py

@@ -86,10 +86,10 @@ class RetryNotSupportedError(SQLAKitError, TypeError):
 
 
 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."
+    "This registry did not build the default database, it was registered, so "
+    "the settings it was built from live on it. Read them from `db['default']`."
 )
-"""What a registry says when it is asked for connections it does not have."""
+"""What a registry says when asked for settings the database it holds carries."""
 
 
 class DatabaseNotConfiguredError(SQLAKitError, RuntimeError):

{sqlakit-0.10.9 → sqlakit-0.11.1}/sqlakit/pytest_plugin.py

@@ -1,25 +1,23 @@
 """The `db` marker, and the fixtures behind it.
 
-Installed with the library, so a project writes the two lines that say which
-database and which tables, and nothing else:
+Installed with the library, so a project says which models it has and nothing
+else:
 
 ```python title="conftest.py"
 import pytest
 
-from app.db import db
 from app.models import Model
 
 
 @pytest.fixture(scope="session")
-def sqlakit_db() -> Databases:
-    return db
-
-
-@pytest.fixture(scope="session")
-def sqlakit_metadata() -> sa.MetaData:
-    return Model.metadata
+def sqlakit_base() -> type[Model]:
+    return Model
 ```
 
+The database comes from the base: the registry its models look their aliases
+up in, or the one they were given in person. A project with no model layer
+defines `sqlakit_db` and `sqlakit_metadata` instead.
+
 A test marked `db` runs in a transaction that rolls back, on every database.
 `using` narrows that to the ones a test works on:
 
@@ -361,7 +359,9 @@ def _schema_blocks(
     database to put it on.
     """
     if base is not None:
-        aliases = getattr(db, "aliases", None) or (None,)
+        # A database of its own is where the models are pinned, and the alias
+        # a registry knows it by is not how the base reaches it.
+        aliases = db.aliases if hasattr(db, "transactions") else (None,)
         return [base.provisioned_tables(alias) for alias in aliases]
     if metadata is not None:
         return [db.provisioned_tables(metadata)]
@@ -393,11 +393,11 @@ def _rolled_back(db: Any, using: tuple[Any, ...]) -> list[Any]:  # noqa: ANN401
     a connection to each in the tests that read one.
     """
     if not using:
-        # A registry goes through `transactions`, one alias or many: with one
-        # it has a database of its own only when `configure` built it.
+        # A registry opens every database it holds, and one database opens
+        # itself. `transactions` is the one a registry has.
         return [
             db.transactions(rollback=True)
-            if hasattr(db, "aliases")
+            if hasattr(db, "transactions")
             else db.transaction(rollback=True)
         ]
     return [

{sqlakit-0.10.9 → sqlakit-0.11.1}/sqlakit/types.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Literal, TypeAlias, TypedDict
+from typing import TYPE_CHECKING, Any, Literal, TypeAlias
+
+from typing_extensions import TypedDict
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping, Sequence
@@ -27,8 +29,11 @@ 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):
-    """Keyword arguments accepted by [`sqlalchemy.create_engine`](https://docs.sqlalchemy.org/en/20/core/engines.html#sqlalchemy.create_engine)."""
+class EngineArgs(TypedDict, total=False, extra_items=Any):
+    """Keyword arguments accepted by [`sqlalchemy.create_engine`](https://docs.sqlalchemy.org/en/20/core/engines.html#sqlalchemy.create_engine).
+
+    The portable ones are listed. A dialect keyword is allowed too.
+    """
 
     connect_args: dict[str, Any]
     echo: bool | Literal["debug"]
@@ -61,10 +66,11 @@ class EngineArgs(TypedDict, total=False):
     use_insertmanyvalues: bool
 
 
-class SessionArgs(TypedDict, total=False):
+class SessionArgs(TypedDict, total=False, extra_items=Any):
     """Keyword arguments accepted by `sqlalchemy.orm.sessionmaker`.
 
-    No ``bind``: sessions bind to the connection of the surrounding block.
+    No ``bind``: sessions bind to the connection of the surrounding block. A
+    keyword this list does not have is allowed too.
     """
 
     autobegin: bool