sqlakit 0.8.0__tar.gz → 0.9.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlakit
-Version: 0.8.0
+Version: 0.9.0
 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.0 → sqlakit-0.9.0}/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.0 → sqlakit-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.8.0"
+version = "0.9.0"
 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.0 → sqlakit-0.9.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.8.0"
+version = "0.9.0"
 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.0 → sqlakit-0.9.0}/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.0 → sqlakit-0.9.0}/sqlakit/_base.py

@@ -24,13 +24,17 @@ 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 (
@@ -51,6 +55,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 +101,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 +252,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 +301,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 +325,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 +341,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 +355,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 +405,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 +438,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)
@@ -721,14 +759,16 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
         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.
 
@@ -747,7 +787,13 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
         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 +802,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:

sqlakit-0.9.0/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())