Plotly.io.stream and Python Asyncio: Managing Long-Running Stream Cancellations

Answer

No, there is no documented method for plotly.io.stream to propagate a cancellation signal directly back to a generator function. The stream object is designed for unidirectional data flow (write/close) and does not provide a native asyncio cancellation token or a reverse-channel callback to signal the data source to stop.

To terminate a stream without destroying the associated figure object, you must stop the data producer and call stream.close(). This ends the transmission connection while leaving the go.Figure instance intact in Python memory.

Implementation Logic and Assumptions

Because plotly.io.stream does not signal the producer, you must implement cooperative cancellation. This assumes your data producer is wrapped in an asyncio.Task. Note that asyncio cancellation only triggers at await points; if your generator is performing a heavy synchronous calculation, it will block the cancellation signal until the next yield or await.

Steps for Graceful Termination

1. Wrap the Producer: Run your data generator inside an asyncio.Task.
2. Use a Signal: Share an asyncio.Event between the cancellation logic (e.g., a client disconnect handler) and the producer.
3. Poll for Cancellation: Inside the generator loop, check the event status or catch asyncio.CancelledError before calling stream.write().
4. Close the Stream: Once the loop terminates, call stream.close() to release the network resource.

import asyncio

async def data_producer(fig, stream, stop_event):
    try:
        while not stop_event.is_set():
            # Perform compute-heavy work in chunks or via run_in_executor
            data = await get_heavy_data()
            stream.write(data)
            await asyncio.sleep(0) # Yield control to allow cancellation
    except asyncio.CancelledError:
        # Handle immediate task cancellation
        pass
    finally:
        stream.close()

# To stop the stream:
# stop_event.set()
# producer_task.cancel()

Verification and Constraints

• Version Check: Verify your environment supports this API: import plotly; print(hasattr(plotly.io, 'stream')).
• Figure Persistence: Calling stream.close() stops the flow of data but does not purge the figure. Existing traces remain on the client side unless explicitly removed via a separate Plotly.js command.
• Synchronous Blocks: If the generator is strictly synchronous and compute-heavy, asyncio cannot interrupt it. You must move the calculation to a ThreadPoolExecutor and check the stop signal periodically.

Required Diagnostic: Which target is the stream writing to (e.g., Plotly Cloud, a Dash app, or a Jupyter renderer)? The specific renderer determines whether stream.close() fully cleans up the client-side connection or requires additional JavaScript-side cleanup.