fix(py): restore server(data_source=) for Shiny/R parity

[cpsievert]

Part 1 of 4

This is the first PR in a stack restoring safe per-session data source registration:

1. fix(py): restore server(data_source=) for Shiny/R parity #301 (this PR): restore server(data_source=)
2. fix(py): let server(data_source=) survive a second session #302: let it survive a second session
3. fix(py): don't clean up a table replaced via server(data_source=) #303: don't corrupt an earlier session's still-in-use resource
4. fix(py): greeting reflects the session that registered its table #304: fix the welcome greeting leaking between sessions

Each PR is reviewable independently; #302-#304 build on this one.

The problem

Some deployments can only create a table's data source inside the Shiny server function — for example, on Posit Connect, a per-user database connection depends on that user's session-scoped OAuth credentials, which don't exist until the server function runs. querychat supports this "deferred" pattern: construct QueryChat without a data source, then register one per session via .server(data_source=...).

Python's server() used to accept data_source= for exactly this, but it was dropped in a multi-table redesign (#195), so this pattern currently requires building a second, fully-duplicate QueryChat instance per session, kept manually in sync with a UI-only global one:

# Before this PR: awkward workaround
qc_ui = QueryChat(None, table_name="orders")  # for .ui()/.sidebar() only

def server(input, output, session):
    conn = get_per_user_connection(session)  # depends on this session's OAuth token
    qc_session = QueryChat(conn, table_name="orders", client=chat_client, ...)  # duplicate config
    qc_session.server()

The fix

QueryChat.server() gains data_source and table_name:

qc = QueryChat(None, table_name="orders")

def server(input, output, session):
    conn = get_per_user_connection(session)
    qc.server(data_source=conn, client=chat_client)

• table_name is optional — it falls back to the name given to the constructor, or to the first already-registered table, matching R's equivalent behavior.
• Registered via the existing add_table(replace=True, include_in_greeting=True) machinery.

This PR intentionally matches R's current $server(data_source = ) behavior exactly, guard included: a second session's call still raises RuntimeError("Cannot add tables after server initialization."), same as R does today. That's a real limitation — R's version has never actually worked for more than one session either — but it's a separate, focused problem from "restore the parameter," and is fixed in #302.

Test plan

• New unit tests cover: registering the deferred table by its constructor name, an explicit table_name override, falling back to the first registered table, a clear error when no name can be inferred, and greeting inclusion.
• A test also locks in the current single-session limitation described above, so fix(py): let server(data_source=) survive a second session #302's fix has something concrete to flip.
• make py-check-format, make py-check-types, make py-check-tests all pass.

Part of #300.

[Copilot]

🟡 Changes recommended

Per-session registration can close an executor still used by an earlier session; two naming nits also remain.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (2)

pkg-py/src/querychat/_querychat_base.py:474

• This new helper is defined in _querychat_base.py, which is already a private module, so the leading underscore is redundant and violates the package's Python naming convention. Rename it to add_or_replace_table and update its callers.

    def _add_or_replace_table(

pkg-py/src/querychat/_querychat_greeter.py:74

• This new method is defined in _querychat_greeter.py, which is already a private module, so the leading underscore is redundant and violates the package's Python naming convention. Rename it to generate_async_snapshot and update its callers.

    async def _generate_async_snapshot(

• Files reviewed: 8/8 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

Broaden the server(data_source=...) annotation to include supported BaseBoard sources.

Review details

Suppressed comments (1)

pkg-py/src/querychat/_shiny.py:636

• This new annotation is narrower than the data-source contract used by the rest of the API: QueryChatBase.add_table() accepts pins.boards.BaseBoard (_querychat_base.py:456-458), and the public docs show QueryChat(board, "my_pin") (docs/data-sources.qmd:341-354), but a typed deferred call such as qc.server(data_source=board, table_name="my_pin") is rejected by type checkers even though normalize_data_source() supports it at runtime. Include the same supported source type (ideally via a shared input alias) in the new server() annotation.

        data_source: IntoFrame | sqlalchemy.Engine | ibis.Table | None = None,

• Files reviewed: 4/4 changed files
• Comments generated: 0 new
• Review effort level: Lite