Add session.clientdata; allow access to input names via dir()

CHANGELOG.md

@@ -17,6 +17,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * `shiny create` includes new and improved `ui.Chat()` template options. Most of these templates leverage the new [`{chatlas}` package](https://posit-dev.github.io/chatlas/), our opinionated approach to interfacing with various LLM. (#1806)
 
+* Client data values (e.g., url info, output sizes/styles, etc.) can now be accessed in the server-side Python code via `session.clientdata`. For example, `session.clientdata.url_search()` reactively reads the URL search parameters. (#1832)
+
+* Available `input` ids can now be listed via `dir(input)`. This also works on the new `session.clientdata` object. (#1832)
+
 ### Bug fixes
 
 * `ui.Chat()` now correctly handles new `ollama.chat()` return value introduced in `ollama` v0.4. (#1787)

docs/_quartodoc-core.yml

@@ -233,19 +233,21 @@ quartodoc:
           path: Session
           summary:
             name: "Session"
-            desc: ""
+            desc: "Tools for managing user sessions and accessing session-related information."
           flatten: true
           contents:
             - session.get_current_session
             - session.require_active_session
             - session.session_context
             - reactive.get_current_context
+            - session.ClientData
             - session.Session.send_custom_message
             - session.Session.send_input_message
             - session.Session.on_flush
             - session.Session.on_flushed
             - session.Session.on_ended
             - session.Session.dynamic_route
+            - session.Session.close
             - input_handler.input_handlers
         - kind: page
           path: Renderer

docs/_quartodoc-express.yml

@@ -168,6 +168,14 @@ quartodoc:
         - express.ui.panel_conditional
         - express.ui.insert_ui
         - express.ui.remove_ui
+    - title: User Session
+      desc: Tools for managing user sessions and accessing session-related information.
+      contents:
+        - session.Session
+    - title: Client Data
+      desc: Access (client-side) information about the user session (e.g., URL, output info, etc).
+      contents:
+        - session.ClientData
     - title: UI as HTML
       desc: Tools for creating HTML/CSS/JS
       contents:

shiny/api-examples/ClientData/app-core.py

@@ -0,0 +1,60 @@
+import textwrap
+
+# pyright: reportUnknownMemberType=false, reportUnknownVariableType=false
+import matplotlib.pyplot as plt
+import numpy as np
+
+from shiny import App, Inputs, Outputs, Session, render, ui
+
+app_ui = ui.page_sidebar(
+    ui.sidebar(
+        ui.input_slider("obs", "Number of observations:", min=0, max=1000, value=500),
+        open="closed",
+    ),
+    ui.markdown(
+        """
+#### `session.clientdata` values
+
+The following methods are available from the `session.clientdata` object and allow you
+to reactively read the client data values from the browser.
+"""
+    ),
+    ui.output_text_verbatim("clientdatatext"),
+    ui.output_plot("myplot"),
+)
+
+
+def server(input: Inputs, output: Outputs, session: Session):
+
+    @render.code
+    def clientdatatext():
+        return textwrap.dedent(
+            f"""
+        .url_hash()         -> {session.clientdata.url_hash()}
+        .url_hash_initial() -> {session.clientdata.url_hash_initial()}
+        .url_hostname()     -> {session.clientdata.url_hostname()}
+        .url_pathname()     -> {session.clientdata.url_pathname()}
+        .url_port()         -> {session.clientdata.url_port()}
+        .url_protocol()     -> {session.clientdata.url_protocol()}
+        .url_search()       -> {session.clientdata.url_search()}
+        .pixelratio()       -> {session.clientdata.pixelratio()}
+
+        .output_height("myplot")       -> {session.clientdata.output_height("myplot")}
+        .output_width("myplot")        -> {session.clientdata.output_width("myplot")}
+        .output_hidden("myplot")       -> {session.clientdata.output_hidden("myplot")}
+        .output_bg_color("myplot")     -> {session.clientdata.output_bg_color("myplot")}
+        .output_fg_color("myplot")     -> {session.clientdata.output_fg_color("myplot")}
+        .output_accent_color("myplot") -> {session.clientdata.output_accent_color("myplot")}
+        .output_font("myplot")         -> {session.clientdata.output_font("myplot")}
+
+        """
+        )
+
+    @render.plot
+    def myplot():
+        plt.figure()
+        plt.hist(np.random.normal(size=input.obs()))  # type: ignore
+        plt.title("This is myplot")
+
+
+app = App(app_ui, server)

shiny/api-examples/ClientData/app-express.py

@@ -0,0 +1,46 @@
+# pyright: reportUnknownMemberType=false, reportUnknownVariableType=false
+import matplotlib.pyplot as plt
+import numpy as np
+
+from shiny.express import input, render, session, ui
+
+with ui.sidebar(open="closed"):
+    ui.input_slider("obs", "Number of observations:", min=0, max=1000, value=500)
+
+ui.markdown(
+    """
+#### `session.clientdata` values
+
+The following methods are available from the `session.clientdata` object and allow you
+to reactively read the client data values from the browser.
+"""
+)
+
+
+@render.code
+def clientdatatext():
+    return f"""
+    .url_hash()         -> {session.clientdata.url_hash()}
+    .url_hash_initial() -> {session.clientdata.url_hash_initial()}
+    .url_hostname()     -> {session.clientdata.url_hostname()}
+    .url_pathname()     -> {session.clientdata.url_pathname()}
+    .url_port()         -> {session.clientdata.url_port()}
+    .url_protocol()     -> {session.clientdata.url_protocol()}
+    .url_search()       -> {session.clientdata.url_search()}
+    .pixelratio()       -> {session.clientdata.pixelratio()}
+
+    .output_height("myplot")       -> {session.clientdata.output_height("myplot")}
+    .output_width("myplot")        -> {session.clientdata.output_width("myplot")}
+    .output_hidden("myplot")       -> {session.clientdata.output_hidden("myplot")}
+    .output_bg_color("myplot")     -> {session.clientdata.output_bg_color("myplot")}
+    .output_fg_color("myplot")     -> {session.clientdata.output_fg_color("myplot")}
+    .output_accent_color("myplot") -> {session.clientdata.output_accent_color("myplot")}
+    .output_font("myplot")         -> {session.clientdata.output_font("myplot")}
+    """
+
+
+@render.plot
+def myplot():
+    plt.figure()
+    plt.hist(np.random.normal(size=input.obs()))  # type: ignore
+    plt.title("This is myplot")

shiny/session/__init__.py

@@ -2,7 +2,7 @@
 Tools for working within a (user) session context.
 """
 
-from ._session import Session, Inputs, Outputs
+from ._session import ClientData, Inputs, Outputs, Session
 from ._utils import (  # noqa: F401
     get_current_session,
     session_context as session_context,
@@ -13,6 +13,7 @@
     "Session",
     "Inputs",
     "Outputs",
+    "ClientData",
     "get_current_session",
     "require_active_session",
 )