docs: WIP DOC-659-publish and fetch

docs/python/how-to-guides/create-plugins.md

@@ -25,7 +25,7 @@ ExampleServicePlugin/
     └── pyproject.toml
     └── example_plugin_server/
         └── __init__.py
-└── server/
+└── client/
     └── pyproject.toml
     └── example_plugin_client/
         └── __init__.py
@@ -86,7 +86,7 @@ class ExampleService:
 
     def hello_string(self, data: str) -> str:
         """Returns a string containing the input data."""
-        return f"Hello client.  You said: {data}"
+        return f"Hello client. You said: {data}"
 
     def hello_table(self, table: Table, data: str) -> Table:
         """Returns a table generated from the input table and the input data."""
@@ -201,7 +201,7 @@ class ExampleService:
 
     def hello_string(self, data: str) -> str:
         """Returns a string containing the input data."""
-        return f"Hello client.  You said: {data}"
+        return f"Hello client. You said: {data}"
 
     def hello_table(self, table: Table, data: str) -> Table:
         """Returns a table generated from the input table and the input data."""
@@ -427,7 +427,7 @@ dependencies = ["pydeephaven>=0.36.1", "pandas"]
 
 ## Use the plugin
 
-Once you have completed all of the client—and server-side wiring, you can test the plugin. The following subsections cover testing the server using different launch methods.
+Once you have completed all of the client- and server-side wiring, you can test the plugin. The following subsections cover testing the server using different launch methods.
 
 ### Installation
 
@@ -463,7 +463,7 @@ RUN pip install /server
 The following Docker Compose file runs Deephaven using the image built by the above Dockerfile:
 
 > [!IMPORTANT]
-> The Dockerfile below sets the pre-shared key to `YOUR_PASSWORD_HERE` for demonstration purposes. The client needs this key when connecting to the server. It is recommended that this key be changed to something more secure.
+> The Docker Compose file below sets the pre-shared key to `YOUR_PASSWORD_HERE` for demonstration purposes. The client needs this key when connecting to the server. It is recommended that this key be changed to something more secure.
 
 ```yaml
 services:
@@ -487,8 +487,12 @@ If running Deephaven from Python, the following Python script will start a Deeph
 
 ```python skip-test
 import sys
+from deephaven_server import Server
 from example_plugin_server import ExampleService
 
+# Start the Deephaven server
+server = Server(port=10000)
+server.start()
 
 example_service = ExampleService()
 
@@ -573,6 +577,82 @@ print(table_result.to_arrow().to_pandas())
 session.close()
 ```
 
+## Share plugin objects between sessions
+
+Plugin objects created in one session can be shared with other sessions using the [`publish`](../reference/client-api/session/publish.md) and [`fetch`](../reference/client-api/session/fetch.md) methods. This is useful when you want multiple client sessions to interact with the same server-side plugin object.
+
+### Publishing a plugin object
+
+To share a plugin object, first fetch it to get an export ticket, then publish it to a shared ticket:
+
+```python skip-test
+from pydeephaven import Session
+from pydeephaven.ticket import SharedTicket
+
+# Connect to the server
+session = Session(
+    auth_type="io.deephaven.authentication.psk.PskAuthenticationHandler",
+    auth_token="YOUR_PASSWORD_HERE",
+)
+
+# Get the plugin object ticket
+example_service_ticket = session.exportable_objects["example_service"]
+
+# Create a plugin client
+plugin_client = session.plugin_client(example_service_ticket)
+
+# Fetch the plugin object to get an export ticket
+export_ticket = session.fetch(plugin_client)
+
+# Publish to a shared ticket
+shared_ticket = SharedTicket.random_ticket()
+session.publish(export_ticket, shared_ticket)
+
+# Now other sessions can use this shared_ticket to access the same plugin object
+```
+
+### Fetching a shared plugin object
+
+Another session can fetch the shared plugin object using the shared ticket:
+
+```python skip-test
+from pydeephaven import Session
+from pydeephaven.ticket import ServerObject, SharedTicket
+
+# Connect to the server
+sub_session = Session(
+    auth_type="io.deephaven.authentication.psk.PskAuthenticationHandler",
+    auth_token="YOUR_PASSWORD_HERE",
+)
+
+# Use the shared ticket from the publishing session
+# (In practice, you would pass this ticket between sessions)
+shared_ticket = SharedTicket.random_ticket()  # Use the actual shared ticket
+
+# Create a ServerObject reference with the appropriate type
+server_obj = ServerObject(
+    type="example_plugin_server.ExampleService", ticket=shared_ticket
+)
+
+# Create a plugin client to interact with the shared object
+sub_plugin_client = sub_session.plugin_client(server_obj)
+
+# Now you can use the plugin client as usual
+from example_plugin_client import ExampleServiceProxy
+
+example_service = ExampleServiceProxy(sub_plugin_client)
+
+result = example_service.hello_string("Hello from another session!")
+print(result)
+
+sub_session.close()
+```
+
+> [!IMPORTANT]
+> Shared tickets remain valid only as long as the publishing session keeps the object alive. When the publishing session closes or releases the object, the shared ticket becomes invalid.
+
 ## Related documentation
 
 - [Install and use plugins](./install-use-plugins.md)
+- [`publish`](../reference/client-api/session/publish.md) - Publish server objects to shared tickets
+- [`fetch`](../reference/client-api/session/fetch.md) - Fetch server objects by ticket

docs/python/reference/client-api/session/fetch-table.md

@@ -0,0 +1,59 @@
+---
+title: fetch_table
+---
+
+The `fetch_table` method fetches a table by [`SharedTicket`](/core/client-api/python/code/pydeephaven.ticket.html#pydeephaven.ticket.SharedTicket).
+
+This is a convenience method specifically for tables. For fetching other types of server objects (such as plots, pandas DataFrames, or plugin objects), use the generic [`fetch`](./fetch.md) method.
+
+> [!NOTE]
+> If the remote table is closed or its owner session is closed, the ticket becomes invalid.
+
+## Syntax
+
+```python syntax
+fetch_table(ticket: SharedTicket) -> Table
+```
+
+## Parameters
+
+<ParamTable>
+<Param name="ticket" type="SharedTicket">
+
+A [`SharedTicket`](/core/client-api/python/code/pydeephaven.ticket.html#pydeephaven.ticket.SharedTicket) object.
+
+</Param>
+</ParamTable>
+
+## Returns
+
+A Table object.
+
+## Examples
+
+The following example fetches a table that was published to a shared ticket by another session.
+
+```python skip-test
+from pydeephaven import Session
+from pydeephaven.ticket import SharedTicket
+
+# Assume another session published a table to this shared ticket
+# (In practice, you would get this ticket from the publishing session)
+shared_ticket = SharedTicket.random_ticket()  # Use the actual shared ticket
+
+# Connect and fetch the table
+session = Session(host="localhost", port=10000)
+table = session.fetch_table(shared_ticket)
+
+session.close()
+```
+
+For a complete example showing how to use `fetch_table` with tables published from another session, see the Barrage [`subscribe`](../../data-import-export/barrage/subscribe.md) documentation.
+
+## Related documentation
+
+- [`publish_table`](./publish-table.md)
+- [`fetch`](./fetch.md)
+- [`publish`](./publish.md)
+- [`subscribe`](../../data-import-export/barrage/subscribe.md)
+- [Session API](/core/client-api/python/code/pydeephaven.session.html#pydeephaven.session.Session.fetch_table)

docs/python/reference/client-api/session/fetch.md

@@ -0,0 +1,131 @@
+---
+title: fetch
+---
+
+The `fetch` method fetches a server object by ticket and returns an [`ExportTicket`](/core/client-api/python/code/pydeephaven.ticket.html#pydeephaven.ticket.ExportTicket). This is a low-level method that can be used to fetch any server object (not just tables).
+
+The ticket represents a fetchable server object, such as a [`PluginClient`](/core/client-api/python/code/pydeephaven.experimental.plugin_client.html#pydeephaven.experimental.plugin_client.PluginClient) or [`Fetchable`](/core/client-api/python/code/pydeephaven.experimental.plugin_client.html#pydeephaven.experimental.plugin_client.Fetchable). This method is used together with the [`publish`](./publish.md) method to share server objects between sessions.
+
+> [!NOTE]
+> For tables specifically, use the higher-level [`fetch_table`](./fetch-table.md) method instead.
+
+## Syntax
+
+```python syntax
+fetch(ticket: Ticket) -> ExportTicket
+```
+
+## Parameters
+
+<ParamTable>
+<Param name="ticket" type="Ticket">
+
+The ticket representing a fetchable server object.
+
+</Param>
+</ParamTable>
+
+## Returns
+
+An [`ExportTicket`](/core/client-api/python/code/pydeephaven.ticket.html#pydeephaven.ticket.ExportTicket) object that can be used to reference the fetched server object.
+
+## Examples
+
+### Fetching and publishing a Figure object
+
+The following example fetches a Figure (plot) object and publishes it to a shared ticket.
+
+```python skip-test
+from pydeephaven import Session
+from pydeephaven.ticket import SharedTicket, ServerObject
+
+# Create a session and generate a plot
+session = Session(host="localhost", port=10000)
+session.run_script("""
+from deephaven.plot.figure import Figure
+from deephaven import empty_table
+
+source = empty_table(20).update([
+    "X = 0.1 * i",
+    "Y = randomDouble(0.0, 5.0)"
+])
+
+plot = Figure().plot_xy(
+    series_name="Random numbers",
+    t=source,
+    x="X",
+    y="Y"
+).show()
+""")
+
+# Get the plot object from the session
+plot_obj = session.exportable_objects["plot"]
+
+# Create a plugin client to interact with the plot
+plugin_client = session.plugin_client(plot_obj)
+
+# Fetch the plugin object to get an export ticket
+export_ticket = session.fetch(plugin_client)
+
+# Now you can publish this export ticket to share it with other sessions
+shared_ticket = SharedTicket.random_ticket()
+session.publish(export_ticket, shared_ticket)
+
+plugin_client.close()
+session.close()
+```
+
+### Fetching a table using generic fetch
+
+While [`fetch_table`](./fetch-table.md) is recommended for tables, you can also use the generic `fetch` method:
+
+```python skip-test
+from pydeephaven import Session
+from pydeephaven.ticket import ScopeTicket
+
+# Create a session and table
+session = Session(host="localhost", port=10000)
+session.run_script("source = empty_table(20).update('X = i')")
+
+# Fetch the table as an export ticket using the generic fetch method
+export_ticket = session.fetch(ScopeTicket.scope_ticket("source"))
+
+# The export_ticket can now be used to reference the table
+# or published to a shared ticket for other sessions to access
+
+session.close()
+```
+
+### Fetching a shared plugin object
+
+The following example shows how to fetch a plugin object that was published to a shared ticket by another session.
+
+```python skip-test
+from pydeephaven import Session
+from pydeephaven.ticket import SharedTicket, ServerObject
+
+# Assume another session published a Figure to this shared ticket
+shared_ticket = SharedTicket.random_ticket()  # Use the actual shared ticket
+
+# Connect to the session and fetch the shared object
+session = Session(host="localhost", port=10000)
+
+# Create a ServerObject reference with the appropriate type
+server_obj = ServerObject(type="Figure", ticket=shared_ticket)
+
+# Create a plugin client to interact with the shared Figure
+plugin_client = session.plugin_client(server_obj)
+
+# You can now interact with the Figure through the plugin client
+payload, refs = next(plugin_client.resp_stream)
+
+plugin_client.close()
+session.close()
+```
+
+## Related documentation
+
+- [`publish`](./publish.md)
+- [`fetch_table`](./fetch-table.md)
+- [`publish_table`](./publish-table.md)
+- [Session API](/core/client-api/python/code/pydeephaven.session.html#pydeephaven.session.Session.fetch)