sqlakit 0.8.1__tar.gz → 0.9.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlakit
-Version: 0.8.1
+Version: 0.9.1
 Summary: A toolkit for SQLAlchemy applications.
 Keywords: sqlalchemy,database,orm,sql,asyncio
 Author: Anton Ruhlov
@@ -246,6 +246,33 @@ You can spot the N+1 right away: one query for the users and two identical
 ones for the teams. Formatting needs the `sqlakit[debug]` extra, and if the
 project has `rich`, the output is colored too.
 
+### The debug server
+
+`sqlakit debugserver` serves a page that fills as the recordings arrive:
+
+```console
+$ sqlakit debugserver
+
+SQLAKit debug server on http://localhost:5555
+
+Send recordings to it:
+
+  │  with db.recording("GET /users", debugserver=("localhost", 5555)):
+  │      list_users()
+```
+
+![The SQLAKit debug server](docs/assets/debugserver.png)
+
+The recordings are listed on the left, the one you pick opens on the right:
+the SQL highlighted, the parameters ready to paste, the repeats counted, and
+the line of your code behind every statement. Search by `table:`, `kind:`,
+`ms:>50` or `repeated:>0`, and one server watches as many applications as you
+point at it.
+
+`pytest --sqlakit-report` writes the same page for a test run, as a file that
+opens without a server: the test is the label, and each statement carries the
+line of the test that ran it.
+
 ## The registry
 
 To avoid passing a `Database` from module to module, configure the registry

{sqlakit-0.8.1 → sqlakit-0.9.1}/README.md

@@ -214,6 +214,33 @@ You can spot the N+1 right away: one query for the users and two identical
 ones for the teams. Formatting needs the `sqlakit[debug]` extra, and if the
 project has `rich`, the output is colored too.
 
+### The debug server
+
+`sqlakit debugserver` serves a page that fills as the recordings arrive:
+
+```console
+$ sqlakit debugserver
+
+SQLAKit debug server on http://localhost:5555
+
+Send recordings to it:
+
+  │  with db.recording("GET /users", debugserver=("localhost", 5555)):
+  │      list_users()
+```
+
+![The SQLAKit debug server](docs/assets/debugserver.png)
+
+The recordings are listed on the left, the one you pick opens on the right:
+the SQL highlighted, the parameters ready to paste, the repeats counted, and
+the line of your code behind every statement. Search by `table:`, `kind:`,
+`ms:>50` or `repeated:>0`, and one server watches as many applications as you
+point at it.
+
+`pytest --sqlakit-report` writes the same page for a test run, as a file that
+opens without a server: the test is the label, and each statement carries the
+line of the test that ran it.
+
 ## The registry
 
 To avoid passing a `Database` from module to module, configure the registry

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

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.8.1"
+version = "0.9.1"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"
@@ -32,6 +32,9 @@ dependencies = ["sqlalchemy>=2.0.22"]
 name = "Anton Ruhlov"
 email = "antonruhlov@gmail.com"
 
+[project.scripts]
+sqlakit = "sqlakit._cli:main"
+
 [project.entry-points.pytest11]
 sqlakit = "sqlakit.pytest_plugin"
 
@@ -117,6 +120,7 @@ ignore = [
     "PLW0108",
     "DTZ005",
     "S106",
+    "S310",
 ]
 "tools/**/*.py" = [
     "INP001",
@@ -171,7 +175,7 @@ default_item_type = "cmd"
 
 [tool.codespell]
 ignore-words-list = "froms"
-skip = "./.venv,./site,./uv.lock,./.git"
+skip = "./.venv,./site,./uv.lock,./.git,./debugserver/node_modules,./debugserver/bun.lock,./sqlakit/debugserver.html"
 
 [dependency-groups]
 dev = [

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

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.8.1"
+version = "0.9.1"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"
@@ -25,6 +25,9 @@ dependencies = [
     "sqlalchemy>=2.0.22",
 ]
 
+[project.scripts]
+sqlakit = "sqlakit._cli:main"
+
 [project.entry-points.pytest11]
 sqlakit = "sqlakit.pytest_plugin"
 
@@ -150,6 +153,7 @@ ignore = [
     "PLW0108",  # a lambda in a parameter table is deliberate
     "DTZ005",   # naive datetimes are fine as fixtures
     "S106",     # the passwords here are fake, and the point of the test
+    "S310",     # the URLs here are the tests' own server
 ]
 "tools/**/*.py" = [
     "INP001",   # a script, not a package
@@ -206,4 +210,4 @@ default_item_type = "cmd"
 [tool.codespell]
 # `froms` is SQLAlchemy's own word for what a SELECT selects from.
 ignore-words-list = "froms"
-skip = "./.venv,./site,./uv.lock,./.git"
+skip = "./.venv,./site,./uv.lock,./.git,./debugserver/node_modules,./debugserver/bun.lock,./sqlakit/debugserver.html"

{sqlakit-0.8.1 → sqlakit-0.9.1}/sqlakit/__init__.py

@@ -1,5 +1,6 @@
 from ._base import DEFAULT_ENGINE_ARGS, DEFAULT_SESSION_ARGS
 from ._db import Database, RetryingTransaction, Transaction
+from ._debugserver import DebugServer
 from ._discovery import import_models, import_string
 from ._query import (
     CASE_INSENSITIVE_COLLATIONS,
@@ -77,6 +78,7 @@ __all__ = [
     "DatabaseConfig",
     "DatabaseNotConfiguredError",
     "Databases",
+    "DebugServer",
     "DefaultAliasError",
     "DetachedInstanceError",
     "EngineArgs",

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

@@ -24,17 +24,22 @@ import sqlalchemy as sa
 import sqlalchemy.event
 from typing_extensions import Unpack
 
+from ._debugserver import DebugServer, send_recording
 from ._discovery import import_string
 from ._recording import (
+    KEEP,
+    WIDE,
     Recording,
     Statement,
     caller_stack,
     check,
     require_expectation,
+    resolved,
 )
 from ._routing import Router, as_router
 from .exceptions import (
     DEFAULT_ALIAS,
+    REGISTERED_DEFAULT,
     AliasInUseError,
     ConflictingDatabaseUrlError,
     DatabaseAlreadyConfiguredError,
@@ -51,6 +56,7 @@ from .exceptions import (
 if TYPE_CHECKING:
     import logging
     from collections.abc import Iterator, Sequence
+    from os import PathLike
 
     from sqlalchemy.engine import Engine
 
@@ -96,6 +102,12 @@ RetryOn = (
 
 _random = random.SystemRandom()
 
+
+def _elsewhere(frames: tuple[str, ...], skipped: tuple[str, ...]) -> bool:
+    """Whether one of the files a recording leaves out ran this statement."""
+    return bool(skipped) and bool(frames) and frames[0].startswith(skipped)
+
+
 ConnectionT = TypeVar("ConnectionT")
 SessionT = TypeVar("SessionT")
 
@@ -241,7 +253,11 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
         self._stacks: ContextVar[bool] = ContextVar(
             f"{type(self).__name__}.stacks", default=False
         )
+        self._skipped: ContextVar[tuple[str, ...]] = ContextVar(
+            f"{type(self).__name__}.skipped", default=()
+        )
         self._listening = 0
+        self._listened: Any = None
         self._listening_lock = threading.Lock()
         self._name = DEFAULT_ALIAS
 
@@ -286,14 +302,16 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
         return scope.session
 
     @contextmanager
-    def recording(
+    def recording(  # noqa: PLR0913 - what a recording may report to, one each
         self,
         label: str | None = None,
         *,
         logger: logging.Logger | None = None,
         echo: bool = False,
         stacks: bool = False,
+        skip_queries_from: Sequence[str | PathLike[str]] = (),
         into: Recording | None = None,
+        debugserver: DebugServer | tuple[str, int] | None = None,
     ) -> Iterator[Recording]:
         """Record the statements of this block, and what they add up to.
 
@@ -308,8 +326,13 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
 
         ``logger`` writes a summary when the block ends, at a level the numbers
         choose. ``echo`` prints the statements instead, coloured where `rich` is
-        installed. ``stacks`` has every statement remember the frames that led to it,
-        at the cost of a stack walk each time.
+        installed. ``debugserver`` sends the recording to a `sqlakit debugserver`
+        listening there, and says nothing when none is. ``stacks`` has every
+        statement remember the frames that led to it, at the cost of a stack walk
+        each time. ``skip_queries_from`` names the files whose statements are none of
+        your business: what those run is not recorded at all, which leaves a test's
+        report showing the code under test rather than the rows a factory of the tests
+        wrote to set the scene.
 
         Blocks nest, each recording what runs inside it, and the listeners come off
         after. `with` is right on either side, awaited or not: it listens, it does
@@ -319,9 +342,13 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
         self._listen()
         recordings = self._recordings.set((*self._recordings.get(), recording))
         asked = self._stacks.set(stacks or self._stacks.get())
+        skipped = self._skipped.set(
+            (*self._skipped.get(), *resolved(skip_queries_from))
+        )
         try:
             yield recording
         finally:
+            self._skipped.reset(skipped)
             self._stacks.reset(asked)
             self._recordings.reset(recordings)
             self._silence()
@@ -329,6 +356,8 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
                 recording.log(logger)
             if echo:
                 recording.echo()
+            if debugserver is not None:
+                send_recording(recording, debugserver)
 
     @contextmanager
     def assert_queries(
@@ -377,13 +406,16 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
                 engine = getattr(self.engine, "sync_engine", self.engine)
                 sa.event.listen(engine, "before_cursor_execute", self._statement_began)
                 sa.event.listen(engine, "after_cursor_execute", self._statement_ended)
+                # Held, rather than looked up again: a block that disposes the
+                # database gets a new engine, and the listeners are on the old.
+                self._listened = engine
             self._listening += 1
 
     def _silence(self) -> None:
         with self._listening_lock:
             self._listening -= 1
-            if self._listening == 0:
-                engine = getattr(self.engine, "sync_engine", self.engine)
+            if self._listening == 0 and self._listened is not None:
+                engine, self._listened = self._listened, None
                 sa.event.remove(engine, "before_cursor_execute", self._statement_began)
                 sa.event.remove(engine, "after_cursor_execute", self._statement_ended)
 
@@ -407,12 +439,19 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
         recordings = self._recordings.get()
         if not recordings or statement.split(None, 1)[0].upper() in _CONTROL:
             return
+        stacks = self._stacks.get()
+        skipped = self._skipped.get()
+        frames = caller_stack(keep=WIDE) if stacks or skipped else ()
+        if _elsewhere(frames, skipped):
+            # A row a factory of the tests wrote, not what the block is about.
+            return
         record = Statement(
             sql=statement,
             parameters=parameters,
             duration=time.perf_counter() - started,
             database=self._name,
-            stack=caller_stack() if self._stacks.get() else (),
+            dialect=connection.dialect.name,
+            stack=frames[:KEEP] if stacks else (),
         )
         for recording in recordings:
             recording.statements.append(record)
@@ -665,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(
@@ -679,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:
@@ -706,29 +747,40 @@ 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)
 
     @contextmanager
-    def recording(
+    def recording(  # noqa: PLR0913 - what a recording may report to, one each
         self,
         label: str | None = None,
         *,
         logger: logging.Logger | None = None,
         echo: bool = False,
         stacks: bool = False,
+        skip_queries_from: Sequence[str | PathLike[str]] = (),
         into: Recording | None = None,
+        debugserver: DebugServer | tuple[str, int] | None = None,
     ) -> Iterator[Recording]:
         """Record every database this registry has, not the default one alone.
 
@@ -743,11 +795,17 @@ 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(
-                    BaseDatabase.recording(db, label, stacks=stacks, into=together)
+                    BaseDatabase.recording(
+                        db,
+                        label,
+                        stacks=stacks,
+                        skip_queries_from=skip_queries_from,
+                        into=together,
+                    )
                 )
             try:
                 yield together
@@ -756,6 +814,8 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
                     together.log(logger)
                 if echo:
                     together.echo()
+                if debugserver is not None:
+                    send_recording(together, debugserver)
 
     @staticmethod
     def _named(alias: str, db: DatabaseT) -> DatabaseT:
@@ -840,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
@@ -915,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)
@@ -949,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()
@@ -959,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.1/sqlakit/_cli.py

@@ -0,0 +1,101 @@
+"""`sqlakit`, the command line."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from ._debugserver import create_server
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run a command, and return what the shell should make of it."""
+    parser = argparse.ArgumentParser(prog="sqlakit", description="SQLAKit.")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    debugserver = commands.add_parser(
+        "debugserver", help="watch the recordings an application sends"
+    )
+    debugserver.add_argument("-H", "--host", default="localhost")
+    debugserver.add_argument("-p", "--port", type=int, default=5555)
+
+    arguments = parser.parse_args(argv)
+    if arguments.command == "debugserver":
+        return _debugserver(arguments.host, arguments.port)
+    return 1
+
+
+def _debugserver(host: str, port: int) -> int:
+    """Serve the recordings until the terminal says otherwise."""
+    try:
+        server = create_server(host, port)
+    except OSError as error:
+        _say(f"\n{_paint('cannot listen', BOLD, RED)} on {host}:{port} — {error}\n")
+        return 1
+    _greeting(host, port)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        _say(_paint("\nstopped", DIM))
+    finally:
+        server.server_close()
+    return 0
+
+
+BOLD = "1"
+DIM = "2"
+TEAL = "36"
+RED = "31"
+GREEN = "32"
+VIOLET = "35"
+
+
+def _colours() -> bool:
+    """Whether to paint: a terminal that wants it, and was not told otherwise."""
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("FORCE_COLOR"):
+        return True
+    return sys.stdout.isatty()
+
+
+def _paint(text: str, *codes: str) -> str:
+    """Return the text in those colours, or as it is where colour is unwanted."""
+    if not codes or not _colours():
+        return text
+    return f"\033[{';'.join(codes)}m{text}\033[0m"
+
+
+def _say(text: str) -> None:
+    """Print, and flush: the server then blocks, and a pipe would hold this."""
+    print(text, flush=True)  # noqa: T201
+
+
+def _block(*lines: str) -> str:
+    """Return these lines set off by a rule, the way a page sets off code."""
+    rule = _paint("│", DIM)
+    return "".join(f"\n  {rule}  {line}" for line in lines) + "\n"
+
+
+def _greeting(host: str, port: int) -> None:
+    """Print where the page is, and the block that fills it."""
+    where = _paint(f"http://{host}:{port}", TEAL, BOLD)
+    label = _paint('"GET /users"', GREEN)
+    named = _paint(f'"{host}"', GREEN)
+    number = _paint(str(port), VIOLET)
+    _say(
+        f"\nSQLAKit debug server on {where}\n\n"
+        + _paint(
+            "Send recordings to it:\n",
+            DIM,
+        )
+        + _block(
+            f"with db.recording({label}, debugserver=({named}, {number})):",
+            "    list_users()",
+        )
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())