sqlakit 0.10.0__tar.gz → 0.10.2__tar.gz

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

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

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

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

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

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

{sqlakit-0.10.0 → sqlakit-0.10.2}/sqlakit/_base.py

@@ -193,7 +193,7 @@ class _Outer(Generic[ConnectionT]):
 
 
 class BaseDatabase(Generic[ConnectionT, SessionT]):
-    """What the sync and async databases share: everything that is not IO.
+    """The sync and async databases share this: everything that is not IO.
 
     Binding to the context lives here. Opening and closing connections and
     sessions is left to the subclass.
@@ -578,9 +578,9 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
     ) -> Iterator[_Outer[ConnectionT] | None]:
         """Make ``connection`` the outer one for this context. See `_Outer`.
 
-        ``None`` leaves this context without an outer transaction at all, which
-        is what ``autocommit()`` needs: blocks under it must not join a
-        transaction its own connection is not part of.
+        ``None`` leaves this context without an outer transaction at all, as
+        ``autocommit()`` needs: blocks under it must not join a transaction
+        its own connection is not part of.
         """
         outer = (
             _Outer(
@@ -605,9 +605,9 @@ DatabaseT = TypeVar("DatabaseT", bound="BaseDatabase[Any, Any]")
 class _Using:
     """A database standing in for the default one, while a block of it is open.
 
-    What `db.using(alias)` returns. Everything a database does, it does; what
-    it adds is the redirection: for as long as one of its blocks is open, a
-    model that lives on the default database resolves here instead.
+    `db.using(alias)` returns one of these. Everything a database does, it
+    does, and it adds the redirection: for as long as one of its blocks is
+    open, a model that lives on the default database resolves here instead.
     """
 
     def __init__(
@@ -726,7 +726,7 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
     def __getitem__(self, alias: str) -> Self | DatabaseT:
         """Return the database configured as ``alias``.
 
-        ``db["default"]`` is what the code reaches without an alias: this
+        ``db["default"]`` is the database the code reaches without an alias: this
         registry, or the database `register` was given for that name.
 
         Raises:
@@ -882,7 +882,7 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
         """Say which database a model lives on, for models that do not say it.
 
         Each router takes a model and returns an alias, or None to leave the question
-        to the next one. A dotted path is imported, which is what settings hand over:
+        to the next one. A dotted path is imported, since settings carry paths:
 
         ```python
         db.route(lambda model: "warehouse" if is_report(model) else None)
@@ -1058,11 +1058,11 @@ 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 a registry with no database of its own looks
-        # like, from the outside and from its own methods.
+        # fails, as it does on a registry with no database of its own, from
+        # the outside and from its own methods.
         def __getattr__(self, name: str) -> object:
             # Only the database half is worth explaining. Anything else is a
-            # name that does not exist, and saying so is what lets `hasattr`,
+            # name that does not exist, and saying so lets `hasattr`,
             # `copy` and every library that introspects work.
             state = self.__dict__
             if "url" in state:
@@ -1078,9 +1078,9 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
 
 
 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.
+    # The attributes `BaseDatabase.__init__` sets. A registry has these once
+    # it has a database of its own, and reaching for one before then raises
+    # `DatabaseNotConfiguredError`, whichever method asked.
     {
         "url",
         "templates",
@@ -1164,7 +1164,7 @@ def lazy_session_class(base: type) -> type:
 
 
 class BaseRetryingTransaction:
-    """What ``transaction()`` returns when given ``retry_on``.
+    """``transaction()`` returns this when given ``retry_on``.
 
     A decorator, and deliberately not a context manager: retrying re-runs the
     block, which a ``with`` statement cannot do. Entering one is rejected by

{sqlakit-0.10.0 → sqlakit-0.10.2}/sqlakit/_db.py

@@ -281,7 +281,7 @@ class Database(BaseDatabase[sa.Connection, Session]):
                 let them reach the database on their own, seeing nothing of this
                 block and surviving its rollback.
             rollback: Roll back on the way out rather than commit. Implies
-                ``savepoint``, and is what wraps a test.
+                ``savepoint``, and wraps a test.
             commit_on_error: Exception types whose escape still commits. The
                 exception propagates; what was written before it stays.
             retry_on: Exception types, or a predicate over the exception, worth
@@ -375,7 +375,7 @@ class Database(BaseDatabase[sa.Connection, Session]):
     ) -> Iterator[None]:
         """Create these tables here, and drop them when the block ends.
 
-        What a test session opens once, around everything that needs a schema:
+        A test session opens this once, around everything that needs a schema:
 
         ```python
         @pytest.fixture(scope="session")
@@ -384,8 +384,8 @@ class Database(BaseDatabase[sa.Connection, Session]):
                 yield
         ```
 
-        Every table of the metadata unless ``tables`` names fewer, which is what a
-        second database wants.
+        Every table of the metadata unless ``tables`` names fewer, as a second
+        database wants.
         """
         with self.transaction() as connection:
             metadata.create_all(connection, tables=tables)
@@ -434,10 +434,10 @@ def _owned(
 
 
 class Transaction(ContextDecorator, AbstractContextManager["sa.Connection"]):
-    """What [`Database.transaction`][sqlakit.Database.transaction] returns.
+    """[`Database.transaction`][sqlakit.Database.transaction] returns this.
 
     A class rather than a generator, so that it works as a decorator and can be
-    entered more than once, which is what decorating a function does.
+    entered more than once, as decorating a function does.
     """
 
     def __init__(
@@ -595,8 +595,8 @@ class Transaction(ContextDecorator, AbstractContextManager["sa.Connection"]):
 class RetryingTransaction(BaseRetryingTransaction):
     """A transaction that runs its block again.
 
-    What [`Database.transaction`][sqlakit.Database.transaction] returns when it is
-    given ``retry_on``.
+    [`Database.transaction`][sqlakit.Database.transaction] returns this when
+    it is given ``retry_on``.
     """
 
     def __call__(self, func: _FuncT) -> _FuncT:

{sqlakit-0.10.0 → sqlakit-0.10.2}/sqlakit/_debugserver.py

@@ -57,16 +57,33 @@ class Records:
     def __init__(self, history: int = HISTORY) -> None:
         self._lock = threading.Lock()
         self._records: deque[dict[str, Any]] = deque(maxlen=history)
+        self._held: set[str] = set()
         self._watchers: list[queue.Queue[dict[str, Any]]] = []
 
     def add(self, record: dict[str, Any]) -> None:
-        """Keep a recording, and hand it to every page that is watching."""
+        """Keep a recording, and hand it to every page that is watching.
+
+        A recording is kept once. Several blocks may report one recording,
+        and each of them sends it, which is how databases outside a registry
+        report under a single label.
+        """
         with self._lock:
+            sent = record.get("id")
+            if sent is not None:
+                if sent in self._held:
+                    return
+                self._held.add(sent)
+            if len(self._records) == self._records.maxlen:
+                self._forget(self._records[0])
             self._records.append(record)
             watchers = list(self._watchers)
         for watcher in watchers:
             watcher.put(record)
 
+    def _forget(self, record: dict[str, Any]) -> None:
+        """Drop the id of a recording the history no longer holds."""
+        self._held.discard(record.get("id", ""))
+
     def all(self) -> list[dict[str, Any]]:
         """Every recording held, oldest first."""
         with self._lock:
@@ -76,6 +93,7 @@ class Records:
         """Forget them."""
         with self._lock:
             self._records.clear()
+            self._held.clear()
 
     def watch(self) -> queue.Queue[dict[str, Any]]:
         """Return a queue that every later recording arrives on."""
@@ -93,7 +111,7 @@ class Records:
 
 @dataclass(frozen=True, slots=True)
 class DebugServer:
-    """Where recordings go, and who is sending them.
+    """The address recordings go to, and the application sending them.
 
     A server watches several applications at once, so a recording says which
     one it came from:
@@ -126,7 +144,22 @@ class DebugServer:
     @property
     def sender(self) -> str:
         """The name the page groups this application under."""
-        return self.app or pathlib.Path(sys.argv[0]).name or "python"
+        return self.app or _program()
+
+
+def _program() -> str:
+    """Name the running program, for a sender that named no application.
+
+    `python -m myapp` runs a file called `__main__.py`, which says nothing on
+    a page, so the module it was started as is the name instead.
+    """
+    started = getattr(sys.modules.get("__main__"), "__spec__", None)
+    if started is not None and started.name:
+        return started.name.removesuffix(".__main__")
+    script = pathlib.Path(sys.argv[0])
+    if script.name in ("", "__main__.py"):
+        return script.parent.name or "python"
+    return script.name
 
 
 def as_payload(
@@ -134,6 +167,7 @@ def as_payload(
 ) -> dict[str, Any]:
     """Return what travels: the recording, flattened to what a page shows."""
     return {
+        "id": recording.id,
         "app": app,
         "tags": list(tags),
         "label": recording.label,
@@ -160,6 +194,10 @@ def send_recording(recording: Recording, to: DebugServer | tuple[str, int]) -> N
 
     A thread of its own does the sending, so the block that recorded pays
     nothing for a server that is slow, or down, or not there at all.
+
+    A recording carries an id, and a server keeps the first that arrives under
+    it. Two blocks writing into one recording, which is how several databases
+    report under a single label, would otherwise show up twice.
     """
     server = DebugServer.of(to)
     body = json.dumps(

{sqlakit-0.10.0 → sqlakit-0.10.2}/sqlakit/_discovery.py

@@ -15,7 +15,7 @@ __all__ = ["import_models", "import_string"]
 def import_string(path: str) -> Any:  # noqa: ANN401
     """Return what a dotted path names, importing what it has to.
 
-    What settings hand over instead of the thing itself:
+    Settings carry a path instead of the thing itself:
 
     ```python
     db.configure(

{sqlakit-0.10.0 → sqlakit-0.10.2}/sqlakit/_model.py

@@ -50,7 +50,7 @@ DatabaseT = TypeVar("DatabaseT", bound="BaseDatabase[Any, Any]")
 
 
 class DatabaseSource(Protocol):
-    """Where an alias is looked up: the importable registry, or a stand-in."""
+    """The registry an alias is looked up in: the importable one, or a stand-in."""
 
     def __getitem__(self, alias: str) -> BaseDatabase[Any, Any]: ...
 
@@ -82,7 +82,7 @@ class RegistryDescriptor:
 
 
 class BaseModel(Generic[DatabaseT]):
-    """What the sync and async models share: everything that is not IO.
+    """The sync and async models share this: everything that is not IO.
 
     A model works on the database named by ``__db__``: an alias in the
     importable registry, or a database of its own.
@@ -95,7 +95,7 @@ class BaseModel(Generic[DatabaseT]):
     """Where an alias in ``__db__`` is looked up."""
 
     # Declared, not assigned: the declarative base a model is built on brings
-    # them, and saying so here is what lets the helpers below read them.
+    # them, and saying so here lets the helpers below read them.
     registry: ClassVar[sa.orm.registry]
     metadata: ClassVar[sa.MetaData]
 
@@ -134,9 +134,9 @@ class BaseModel(Generic[DatabaseT]):
             User(name="ada").save()
         ```
 
-        Which database a model resolves to is still `__db__`, the routers and
-        the open `using()` block, in that order. A model left on the default
-        alias follows `using()`, which is what makes the switch above work.
+        A model still resolves through `__db__`, the routers and the open
+        `using()` block, in that order. A model left on the default alias
+        follows `using()`, and that makes the switch above work.
 
         Without an alias it goes in as the default one, which is where a model
         that names no database lives:
@@ -196,7 +196,7 @@ class BaseModel(Generic[DatabaseT]):
         campaign.set_loaded("thumbnail", None)  # known to be empty
         ```
 
-        What a `lazy="raise"` relationship needs when the value is already in hand:
+        A `lazy="raise"` relationship needs this when the value is in hand:
         rows fetched for a whole page at once, a row this block created, or an
         instance that outlives the session that loaded it.
 
@@ -293,7 +293,7 @@ def tables_for(
 ) -> list[sa.Table] | None:
     """Return the tables of this model's metadata that live on that database.
 
-    None when they all do, which is what `create_all` wants for the ordinary
+    None when they all do, as `create_all` wants for the ordinary
     case of one database. Otherwise the tables of the models pointed at it,
     and the tables that only reference those. An association table belongs
     with the rows it joins.

{sqlakit-0.10.0 → sqlakit-0.10.2}/sqlakit/_query.py

@@ -221,7 +221,7 @@ class Page(Generic[ModelT, TotalT]):
     def with_items(self, items: Sequence[OtherT]) -> Page[OtherT, TotalT]:
         """Return the page carrying these rows instead, counts unchanged.
 
-        What an asynchronous transform needs: `page.with_items(await serialize(...))`.
+        An asynchronous transform needs this: `page.with_items(await serialize(...))`.
 
         Raises:
             PageItemsMismatchError: if there is not one item per row.
@@ -385,7 +385,7 @@ class BaseQuery(Generic[ModelT]):
     def with_select(self, select: sa.Select[Any]) -> Self:
         """Return a query like this one, over the given select.
 
-        This is what every builder is made of. Use it in a method of your own
+        Every builder is made of this. Use it in a method of your own
         when the statement needs SQLAlchemy the builders do not cover.
 
         Raises:
@@ -415,7 +415,7 @@ class BaseQuery(Generic[ModelT]):
     def is_ordered(self) -> bool:
         """Whether this query carries an ordering.
 
-        What a method of your own asks before it adds a default one, since
+        A method of your own asks this before it adds a default one, since
         `page` and `cursor_page` refuse a query with no ordering.
         """
         return bool(self._select._order_by_clauses)  # noqa: SLF001
@@ -458,7 +458,7 @@ class BaseQuery(Generic[ModelT]):
         ```
 
         Nothing can be added afterwards, and ``__query_filter__`` is not applied:
-        what the statement selects is what comes back.
+        the statement selects the rows that come back.
         """
         query = self._copy()
         query._statement = self._select.from_statement(  # noqa: SLF001
@@ -561,7 +561,7 @@ class BaseQuery(Generic[ModelT]):
         User.query.order_by(request.sort, ignore_case=["name"])
         ```
 
-        Which SQL that becomes is the dialect's to decide, and
+        The dialect decides which SQL that becomes, and
         `CASE_INSENSITIVE_COLLATIONS` names the collation. A cursor cannot page
         it: use it with `page`.
 
@@ -948,7 +948,7 @@ class BaseQuery(Generic[ModelT]):
 def orderable_columns(model: type[Any]) -> Mapping[str, Any]:
     """Return every mapped column of a model, by name.
 
-    What a model orders by when it declares no ``__orderable__``, and what an
+    A model orders by these when it declares no ``__orderable__``, and an
     ``__orderable__`` that adds to the columns rather than replacing them starts
     from:
 
@@ -1174,7 +1174,7 @@ def _join_for(
     """Return what to join for a field that is a plain column of another table.
 
     A relationship of the model that reaches that table is the join, condition
-    and all, which is what a view with no foreign key needs. Failing that, the
+    and all, as a view with no foreign key needs. Failing that, the
     table itself, and `SQLAlchemy` works the condition out from the key.
 
     An expression may name several tables or none, so it is left alone:
@@ -1409,7 +1409,7 @@ def _from_json(value: Any, type_: sa.types.TypeEngine[Any]) -> Any:  # noqa: ANN
 
 
 class _Rows(Protocol[RowT_co]):
-    """What the helpers below need of a result: one row, or none."""
+    """The helpers below take one row of a result, or none."""
 
     def one(self) -> RowT_co: ...
 

{sqlakit-0.10.0 → sqlakit-0.10.2}/sqlakit/_recording.py

@@ -4,6 +4,7 @@ import logging
 import sys
 import sysconfig
 import traceback
+import uuid
 from dataclasses import dataclass, field
 from itertools import islice
 from pathlib import Path
@@ -106,7 +107,7 @@ class Statement:
 class Recording:
     """The statements of a block, and what they add up to.
 
-    What `Database.recording()` hands back:
+    `Database.recording()` hands this back:
 
     ```python
     with db.recording() as record:
@@ -118,6 +119,8 @@ class Recording:
 
     label: str | None = None
     statements: list[Statement] = field(default_factory=list)
+    id: str = field(default_factory=lambda: uuid.uuid4().hex, repr=False, compare=False)
+    """A unique id, so a recording several blocks sent is kept once."""
 
     @property
     def count(self) -> int:
@@ -261,7 +264,7 @@ class Recording:
     def pretty(self) -> str:
         """The statements, numbered, each laid out over several lines.
 
-        What `print()` shows when the one-line listing has run out of room.
+        `print()` shows this when the one-line listing has run out of room.
         """
         if not self.statements:
             return "no queries"
@@ -360,7 +363,7 @@ def check(
     at_most: int | None,
     duplicates: bool,
 ) -> None:
-    """Fail unless the recording is what the block said it would be.
+    """Fail unless the recording matches what the block said.
 
     Args:
         recording: What the block ran.
@@ -402,8 +405,8 @@ def resolved(paths: Sequence[str | PathLike[str]]) -> tuple[str, ...]:
 def caller_stack(skip: Sequence[str] = (), keep: int = KEEP) -> tuple[str, ...]:
     """Return the frames of your own code that led to a statement.
 
-    Ours and SQLAlchemy's are left out by directory rather than by name: a
-    project of yours may well live in a path that has our name in it. So is
+    This library's and SQLAlchemy's are left out by directory rather than by
+    name: a project may well live in a path carrying the library's name. So is
     generated code, `<string>`: SQLAlchemy builds wrappers that way, and the
     line numbers lead nowhere.
 

{sqlakit-0.10.0 → sqlakit-0.10.2}/sqlakit/_registry.py

@@ -37,7 +37,7 @@ class Databases(_DatabaseRegistryMixin[Database], Database):
     ) -> Iterator[None]:
         """Open a transaction on every database, not the default one alone.
 
-        Where a single database needs `transaction(rollback=True)`, a test harness
+        A single database needs `transaction(rollback=True)`. A test harness
         with several needs this:
 
         ```python

{sqlakit-0.10.0 → sqlakit-0.10.2}/sqlakit/_sql.py

@@ -58,7 +58,7 @@ PathLike = str | Path
 
 
 class Templates:
-    """Where a database's SQL templates live, and how they are rendered.
+    """The directory a database's SQL templates live in, and how they render.
 
     A path is enough; the object is for the rest:
 
@@ -173,7 +173,7 @@ class Templates:
 
 
 class BaseSQLQuery(Generic[RowT, DatabaseT]):
-    """Where the SQL comes from, its context, and what its rows become.
+    """The source of the SQL, its context, and the type its rows become.
 
     Built by `db.sql(...)`. Nothing can be narrowed: what the SQL selects is
     what comes back.

{sqlakit-0.10.0 → sqlakit-0.10.2}/sqlakit/asyncio/_db.py

@@ -315,7 +315,7 @@ class Database(BaseDatabase[AsyncConnection, AsyncSession]):
                 let them reach the database on their own, seeing nothing of this
                 block and surviving its rollback.
             rollback: Roll back on the way out rather than commit. Implies
-                ``savepoint``, and is what wraps a test.
+                ``savepoint``, and wraps a test.
             commit_on_error: Exception types whose escape still commits. The
                 exception propagates; what was written before it stays.
             retry_on: Exception types, or a predicate over the exception, worth
@@ -409,7 +409,7 @@ class Database(BaseDatabase[AsyncConnection, AsyncSession]):
     ) -> AsyncIterator[None]:
         """Create these tables here, and drop them when the block ends.
 
-        What a test session opens once, around everything that needs a schema:
+        A test session opens this once, around everything that needs a schema:
 
         ```python
         @pytest.fixture(scope="session")
@@ -418,8 +418,8 @@ class Database(BaseDatabase[AsyncConnection, AsyncSession]):
                 yield
         ```
 
-        Every table of the metadata unless ``tables`` names fewer, which is what a
-        second database wants.
+        Every table of the metadata unless ``tables`` names fewer, as a second
+        database wants.
         """
         async with self.transaction() as connection:
             await connection.run_sync(metadata.create_all, tables=tables)
@@ -473,11 +473,11 @@ class Transaction(
 ):
     """The transaction an awaited block runs, as an object.
 
-    What [`Database.transaction`][sqlakit.asyncio.Database.transaction] returns.
+    [`Database.transaction`][sqlakit.asyncio.Database.transaction] returns this.
 
     Kept as a class rather than a generator so that it also works as a
     decorator, and so that a single instance can be entered more than once,
-    which is what ``@db.transaction()`` on a coroutine function does.
+    as ``@db.transaction()`` on a coroutine function does.
     """
 
     def __init__(
@@ -637,8 +637,8 @@ class Transaction(
 class RetryingTransaction(BaseRetryingTransaction):
     """A transaction that runs its block again.
 
-    What [`Database.transaction`][sqlakit.asyncio.Database.transaction] returns
-    when it is given ``retry_on``.
+    [`Database.transaction`][sqlakit.asyncio.Database.transaction] returns
+    this when it is given ``retry_on``.
     """
 
     def __call__(self, func: _FuncT) -> _FuncT:

{sqlakit-0.10.0 → sqlakit-0.10.2}/sqlakit/asyncio/_registry.py

@@ -37,8 +37,8 @@ class Databases(_DatabaseRegistryMixin[Database], Database):
     ) -> AsyncIterator[None]:
         """Open a transaction on every database, not the default one alone.
 
-        What a test harness with more than one database needs, in the place a
-        single database needs `transaction(rollback=True)`.
+        A test harness with more than one database needs this, where a single
+        database needs `transaction(rollback=True)`.
         """
         async with AsyncExitStack() as stack:
             for alias in self.aliases:

{sqlakit-0.10.0 → sqlakit-0.10.2}/sqlakit/asyncio/orm.py

@@ -559,7 +559,7 @@ class ModelMixin(BaseModel[Database]):
     async def provisioned_tables(cls, alias: str | None = None) -> AsyncIterator[None]:
         """Create the tables that belong on this model's database, and drop them after.
 
-        What a test session opens once, around everything that needs a schema:
+        A test session opens this once, around everything that needs a schema:
 
         ```python
         @pytest.fixture(scope="session")

{sqlakit-0.10.0 → sqlakit-0.10.2}/sqlakit/asyncio/sql.py

@@ -95,7 +95,7 @@ class SQL:
 
     @property
     def templates(self) -> Templates:
-        """Where this database looks for its templates."""
+        """The directory this database looks in for its templates."""
         return templates_of(self.db)
 
     def check(self) -> None:
@@ -110,7 +110,7 @@ class SQL:
 class SQLRows(BaseSQLQuery[RowT, "Database"]):
     """The rows of a SQL template, on the connection of the block it runs in.
 
-    What the rows are is settled: reading them is all that is left.
+    The rows are settled: reading them is all that is left.
     """
 
     async def all(self) -> Sequence[RowT]:
@@ -196,7 +196,7 @@ class SQLQuery(SQLRows[sa.Row[Any]]):
         await db.sql("reports/by_team.sql", since=since).typed(TeamReport).all()
         ```
 
-        The type is what one row becomes, and the terminal decides the container.
+        The type says what one row becomes, and the terminal decides the container.
         Anything pydantic can validate works: a model, a dataclass, a
         `TypedDict`. The type also says how much of the row it takes: one built
         from columns is given the whole row, and anything else is given the