diff --git a/src/tqdm_publisher/_demos/_multiple_bars/README.md b/src/tqdm_publisher/_demos/_multiple_bars/README.md new file mode 100644 index 0000000..678a0be --- /dev/null +++ b/src/tqdm_publisher/_demos/_multiple_bars/README.md @@ -0,0 +1,7 @@ +# TQDM Publisher Multiple Bars Demo +This demo shows how to use `tqdm_publisher` to forward progress updates from multiple `TQDMPublisher` instances to the browser. + +## The Approach +This demo is nearly identical to the [single bar demo](../_single_bar/README.md), except that progress bars are managed through a scoped class definition. + +This allows us to easily track a `request_id` passed when the client requests a new progress bar, associating each progress bar with a pre-populated element on the browser. diff --git a/src/tqdm_publisher/_demos/_parallel_bars/README.md b/src/tqdm_publisher/_demos/_parallel_bars/README.md new file mode 100644 index 0000000..8370b4f --- /dev/null +++ b/src/tqdm_publisher/_demos/_parallel_bars/README.md @@ -0,0 +1,18 @@ +# TQDM Publisher Multiple Bars Demo +This demo shows how to use a global `TQDMPublisher` instance to forward progress updates from parallel `TQDMPublisher` instances to the browser. + +## The Approach +In this demo, we track multiple interdependent levels of progress updates by using a global `TQDMPublisher` instance to reflect the execution state of parallel `TQDMPublisher` instances. + +Similar to the [multiple bar demo](../_multiple_bars/README.md), a `request_id` is used to associate both the global and parallel progress bars with a specific group of elements on the browser. In particular, the ID of the global progress bar matches the `request_id`, allowing it to be distinguished from the lower-level progress bars. + +However, this approach also differs in many ways from the other demos: +1. Instead of a `websockets` server, we use a `flask` server to receive requests from the client and send updates back using the Server-Sent Events (SSE) protocol. +2. A `TQDMProgressHandler` is used to queue progress updates from parallel `TQDMPublisher` instances, avoiding the possibility of overloading the connection and receiving misformatted messages on the client. + +## Handling Processes +Since our `TQDMProgressHandler` is managing progress bars across processes, we're using it in an unconventional way. + +Instead of using the handler to directly manage `TQDMSubscriber` instances, we declare `TQDMPublisher` instances within the process. + +Since we can't pass data directly out of the process, we send an HTTP request to the `flask` server that is directly forwarded to the handler's `announce` method. diff --git a/src/tqdm_publisher/_demos/_parallel_bars/_server.py b/src/tqdm_publisher/_demos/_parallel_bars/_server.py index 2f53763..5d09bc4 100644 --- a/src/tqdm_publisher/_demos/_parallel_bars/_server.py +++ b/src/tqdm_publisher/_demos/_parallel_bars/_server.py @@ -215,7 +215,7 @@ def update(): progress_bar_id = data["id"] format_dict = data["data"] - # Forward updates over Sever-Side Events + # Forward updates over Server-Sent Events progress_handler.announce(dict(request_id=request_id, progress_bar_id=progress_bar_id, format_dict=format_dict)) return jsonify({"status": "success"}) diff --git a/src/tqdm_publisher/_demos/_single_bar/README.md b/src/tqdm_publisher/_demos/_single_bar/README.md new file mode 100644 index 0000000..2d1e045 --- /dev/null +++ b/src/tqdm_publisher/_demos/_single_bar/README.md @@ -0,0 +1,9 @@ +# TQDM Publisher Single Bar Demo +This demo shows how to use `tqdm_publisher` to forward progress updates from a single `TQDMPublisher` instance to the browser. + +## The Approach +We use `websockets` to establish a connection between the server and the client. + +A progress bar is pre-rendered on page load. When the client presses the Create Progress Bar button, the server forwards progress updates to the client using a `TQDMPublisher` instance spawned in a separate thread. + +The Create button is disabled until the progress bar is finished to avoid associating updates from multiple progress bars with their respective elements.