fix(pkg-py): organize docstrings in place where quartodoc expects; add missing arg

cpsievert · cpsievert · commit 94fbd75ba812 · 2025-11-26T09:02:13.000-06:00
diff --git a/pkg-py/src/querychat/_querychat.py b/pkg-py/src/querychat/_querychat.py
@@ -25,12 +25,6 @@
 
 
 class QueryChatBase:
-    """
-    Create a QueryChat instance.
-
-    This is the main entry point for using querychat.
-    """
-
     def __init__(
         self,
         data_source: IntoFrame | sqlalchemy.Engine,
@@ -44,70 +38,6 @@ def __init__(
         extra_instructions: Optional[str | Path] = None,
         prompt_template: Optional[str | Path] = None,
     ):
-        """
-        Initialize QueryChat.
-
-        Parameters
-        ----------
-        data_source
-            Either a Narwhals-compatible data frame (e.g., Polars or Pandas) or a
-            SQLAlchemy engine containing the table to query against.
-        table_name
-            If a data_source is a data frame, a name to use to refer to the table in
-            SQL queries (usually the variable name of the data frame, but it doesn't
-            have to be). If a data_source is a SQLAlchemy engine, the table_name is
-            the name of the table in the database to query against.
-        id
-            An optional ID for the QueryChat module. If not provided, an ID will be
-            generated based on the table_name.
-        greeting
-            A string in Markdown format, containing the initial message. If a
-            pathlib.Path object is passed, querychat will read the contents of the
-            path into a string with `.read_text()`. You can use
-            `querychat.greeting()` to help generate a greeting from a querychat
-            configuration. If no greeting is provided, one will be generated at the
-            start of every new conversation.
-        client
-            A `chatlas.Chat` object or a string to be passed to
-            `chatlas.ChatAuto()`'s `provider_model` parameter, describing the
-            provider and model combination to use (e.g. `"openai/gpt-4.1"`,
-            "anthropic/claude-sonnet-4-5", "google/gemini-2.5-flash". etc).
-
-            If `client` is not provided, querychat consults the
-            `QUERYCHAT_CLIENT` environment variable. If that is not set, it
-            defaults to `"openai"`.
-        data_description
-            Description of the data in plain text or Markdown. If a pathlib.Path
-            object is passed, querychat will read the contents of the path into a
-            string with `.read_text()`.
-        categorical_threshold
-            Threshold for determining if a column is categorical based on number of
-            unique values.
-        extra_instructions
-            Additional instructions for the chat model. If a pathlib.Path object is
-            passed, querychat will read the contents of the path into a string with
-            `.read_text()`.
-        prompt_template
-            Path to or a string of a custom prompt file. If not provided, the default querychat
-            template will be used. This should be a Markdown file that contains the
-            system prompt template. The mustache template can use the following
-            variables:
-            - `{{db_engine}}`: The database engine used (e.g., "DuckDB")
-            - `{{schema}}`: The schema of the data source, generated by
-              `data_source.get_schema()`
-            - `{{data_description}}`: The optional data description provided
-            - `{{extra_instructions}}`: Any additional instructions provided
-
-        Examples
-        --------
-        ```python
-        from querychat import QueryChat
-
-        qc = QueryChat(my_dataframe, "my_data")
-        qc.app()
-        ```
-
-        """
         self._data_source = normalize_data_source(data_source, table_name)
 
         # Validate table name (must begin with letter, contain only letters, numbers, underscores)
@@ -481,6 +411,71 @@ def data_source(self):
 
 
 class QueryChat(QueryChatBase):
+    """
+    Create a QueryChat instance.
+
+    Examples
+    --------
+    ```python
+    from querychat import QueryChat
+
+    qc = QueryChat(my_dataframe, "my_data")
+    qc.app()
+    ```
+
+    Parameters
+    ----------
+    data_source
+        Either a Narwhals-compatible data frame (e.g., Polars or Pandas) or a
+        SQLAlchemy engine containing the table to query against.
+    table_name
+        If a data_source is a data frame, a name to use to refer to the table in
+        SQL queries (usually the variable name of the data frame, but it doesn't
+        have to be). If a data_source is a SQLAlchemy engine, the table_name is
+        the name of the table in the database to query against.
+    id
+        An optional ID for the QueryChat module. If not provided, an ID will be
+        generated based on the table_name.
+    greeting
+        A string in Markdown format, containing the initial message. If a
+        pathlib.Path object is passed, querychat will read the contents of the
+        path into a string with `.read_text()`. You can use
+        `querychat.greeting()` to help generate a greeting from a querychat
+        configuration. If no greeting is provided, one will be generated at the
+        start of every new conversation.
+    client
+        A `chatlas.Chat` object or a string to be passed to
+        `chatlas.ChatAuto()`'s `provider_model` parameter, describing the
+        provider and model combination to use (e.g. `"openai/gpt-4.1"`,
+        "anthropic/claude-sonnet-4-5", "google/gemini-2.5-flash". etc).
+
+        If `client` is not provided, querychat consults the
+        `QUERYCHAT_CLIENT` environment variable. If that is not set, it
+        defaults to `"openai"`.
+    data_description
+        Description of the data in plain text or Markdown. If a pathlib.Path
+        object is passed, querychat will read the contents of the path into a
+        string with `.read_text()`.
+    categorical_threshold
+        Threshold for determining if a column is categorical based on number of
+        unique values.
+    extra_instructions
+        Additional instructions for the chat model. If a pathlib.Path object is
+        passed, querychat will read the contents of the path into a string with
+        `.read_text()`.
+    prompt_template
+        Path to or a string of a custom prompt file. If not provided, the default querychat
+        template will be used. This should be a Markdown file that contains the
+        system prompt template. The mustache template can use the following
+        variables:
+        - `{{db_engine}}`: The database engine used (e.g., "DuckDB")
+        - `{{schema}}`: The schema of the data source, generated by
+          `data_source.get_schema()`
+        - `{{data_description}}`: The optional data description provided
+        - `{{extra_instructions}}`: Any additional instructions provided
+
+    """
+
     def server(self, *, enable_bookmarking: bool = False) -> None:
         """
         Initialize Shiny server logic.
@@ -545,7 +540,7 @@ def title():
 
 class QueryChatExpress(QueryChatBase):
     """
-    Use QueryChat with Shiny Express mode.
+    Use QueryChat with Shiny Express.
 
     This class makes it easy to use querychat within Shiny Express apps --
     it automatically calls `.server()` during initialization, so you don't
@@ -583,6 +578,57 @@ def data_table():
     app_opts(bookmark_store="url")
     ```
 
+    Parameters
+    ----------
+    data_source
+        Either a Narwhals-compatible data frame (e.g., Polars or Pandas) or a
+        SQLAlchemy engine containing the table to query against.
+    table_name
+        If a data_source is a data frame, a name to use to refer to the table in
+        SQL queries (usually the variable name of the data frame, but it doesn't
+        have to be). If a data_source is a SQLAlchemy engine, the table_name is
+        the name of the table in the database to query against.
+    id
+        An optional ID for the QueryChat module. If not provided, an ID will be
+        generated based on the table_name.
+    greeting
+        A string in Markdown format, containing the initial message. If a
+        pathlib.Path object is passed, querychat will read the contents of the
+        path into a string with `.read_text()`. You can use
+        `querychat.greeting()` to help generate a greeting from a querychat
+        configuration. If no greeting is provided, one will be generated at the
+        start of every new conversation.
+    client
+        A `chatlas.Chat` object or a string to be passed to
+        `chatlas.ChatAuto()`'s `provider_model` parameter, describing the
+        provider and model combination to use (e.g. `"openai/gpt-4.1"`,
+        "anthropic/claude-sonnet-4-5", "google/gemini-2.5-flash". etc).
+
+        If `client` is not provided, querychat consults the
+        `QUERYCHAT_CLIENT` environment variable. If that is not set, it
+        defaults to `"openai"`.
+    data_description
+        Description of the data in plain text or Markdown. If a pathlib.Path
+        object is passed, querychat will read the contents of the path into a
+        string with `.read_text()`.
+    categorical_threshold
+        Threshold for determining if a column is categorical based on number of
+        unique values.
+    extra_instructions
+        Additional instructions for the chat model. If a pathlib.Path object is
+        passed, querychat will read the contents of the path into a string with
+        `.read_text()`.
+    prompt_template
+        Path to or a string of a custom prompt file. If not provided, the default querychat
+        template will be used. This should be a Markdown file that contains the
+        system prompt template. The mustache template can use the following
+        variables:
+        - `{{db_engine}}`: The database engine used (e.g., "DuckDB")
+        - `{{schema}}`: The schema of the data source, generated by
+          `data_source.get_schema()`
+        - `{{data_description}}`: The optional data description provided
+        - `{{extra_instructions}}`: Any additional instructions provided
+
     """
 
     def __init__(
@@ -594,6 +640,7 @@ def __init__(
         greeting: Optional[str | Path] = None,
         client: Optional[str | chatlas.Chat] = None,
         data_description: Optional[str | Path] = None,
+        categorical_threshold: int = 10,
         extra_instructions: Optional[str | Path] = None,
         prompt_template: Optional[str | Path] = None,
         enable_bookmarking: Literal["auto", True, False] = "auto",
@@ -605,6 +652,7 @@ def __init__(
             greeting=greeting,
             client=client,
             data_description=data_description,
+            categorical_threshold=categorical_threshold,
             extra_instructions=extra_instructions,
             prompt_template=prompt_template,
         )
