expose an async API for plotly_static

Signed-off-by: Andrei Gherghescu <[email protected]>

Author: andrei-ng

docs/book/src/fundamentals/static_image_export.md

@@ -37,8 +37,8 @@ plotly = { version = "0.13", features = ["static_export_default"] }
 ## Prerequisites
 
 1. **WebDriver Installation**: You need either chromedriver or geckodriver installed
-   - Chrome: Download from https://chromedriver.chromium.org/
-   - Firefox: Download from https://github.com/mozilla/geckodriver/releases
+   - Chrome: Download from [https://chromedriver.chromium.org/](https://chromedriver.chromium.org/)
+   - Firefox: Download from [https://github.com/mozilla/geckodriver/releases](https://github.com/mozilla/geckodriver/releases)
    - Or use the `static_export_wd_download` feature for automatic download
 
 2. **Browser Installation**: You need Chrome/Chromium or Firefox installed
@@ -91,6 +91,9 @@ plot1.write_image_with_exporter(&mut exporter, "plot1", ImageFormat::PNG, 800, 6
     .expect("Failed to export plot1");
 plot2.write_image_with_exporter(&mut exporter, "plot2", ImageFormat::JPEG, 800, 600, 1.0)
     .expect("Failed to export plot2");
+
+// Always close the exporter to ensure proper release of WebDriver resources
+exporter.close();
 ```
 
 ## Supported Formats
@@ -129,8 +132,13 @@ let base64_data = plot.to_base64_with_exporter(&mut exporter, ImageFormat::PNG,
 // Get SVG data (vector format, scalable)
 let svg_data = plot.to_svg_with_exporter(&mut exporter, 400, 300, 1.0)
     .expect("Failed to export plot");
+
+// Always close the exporter to ensure proper release of WebDriver resources
+exporter.close();
 ```
 
+Always call `close()` on the exporter to ensure proper release of WebDriver resources. Due to the nature of WebDriver implementation, close has to be called as resources cannot be automatically dropped or released.
+
 ## Advanced Configuration
 
 ### Custom WebDriver Configuration
@@ -150,6 +158,10 @@ let mut exporter = StaticExporterBuilder::default()
     ])
     .build()
     .expect("Failed to create StaticExporter");
+
+// Always close the exporter to ensure proper release of WebDriver resources
+exporter.close();
+
 ```
 
 ### Parallel Usage
@@ -172,8 +184,17 @@ let mut exporter = StaticExporterBuilder::default()
     .webdriver_port(get_unique_port())
     .build()
     .expect("Failed to build StaticExporter");
+
+// Always close the exporter to ensure proper release of WebDriver resources
+exporter.close();
 ```
 
+### Async support
+
+`plotly_static` package offers an `async` API which can is exposed in `plotly` as well but only if the user passes an `AsyncStaticExporter` to the `write_image_async`, `to_base64_async` and `to_svg_async` functions. The `AsyncStaticExporter` can be built using the `StaticExportBuilder`'s `build_async` method. 
+
+For more details check the [`plotly_static` API Documentation](https://docs.rs/plotly_static/)
+
 ## Logging Support
 
 Enable logging for debugging and monitoring:
@@ -190,6 +211,9 @@ env_logger::init();
 let mut exporter = StaticExporterBuilder::default()
     .build()
     .expect("Failed to create StaticExporter");
+
+// Always close the exporter to ensure proper release of WebDriver resources
+exporter.close();
 ```
 
 ## Performance Considerations
@@ -200,7 +224,7 @@ let mut exporter = StaticExporterBuilder::default()
 
 ## Complete Example
 
-See the [static export example](../../../examples/static_export/) for a complete working example that demonstrates:
+See the [static export example](https://github.com/plotly/plotly.rs/tree/main/examples/static_export) for a complete working example that demonstrates:
 
 - Multiple export formats
 - Exporter reuse

examples/customization/consistent_static_format_export/src/main.rs

@@ -162,6 +162,9 @@ fn line_and_scatter_plot(
     info!("  - {file_name}.pdf");
     info!("  - {file_name}.svg");
     info!("  - {file_name}.png");
+
+    // Always close the exporter to ensure proper release of WebDriver resources
+    exporter.close();
 }
 
 fn read_from_file(file_path: &str) -> Vec<Vec<f64>> {

examples/static_export/Cargo.toml

@@ -5,8 +5,10 @@ authors = ["Andrei Gherghescu [email protected]"]
 edition = "2021"
 description = "Example demonstrating static image export using plotly_static with WebDriver"
 readme = "README.md"
+default-run = "sync"
 
 [dependencies]
 plotly = { path = "../../plotly", features = ["static_export_default"] }
-env_logger = "0.10"
-log = "0.4" 
+env_logger = "0.11"
+log = "0.4"
+tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

examples/static_export/README.md

@@ -6,13 +6,15 @@ The `plotly_static` provides a interface for converting Plotly plots into variou
 
 In this example it is shown how to use the `StaticExporter` with the old style Kaleido API and also with the new style API. Using the former API is fine for one time static exports, but that API will crate an instance of the `StaticExporter` for each `write_image` call. The new style API is recommended for performance as the same instance of the `StaticExporter` can be reused across multiple exports.  
 
-See also the `Static Image Export` section in the book for a more detailed description.
+There are both a sync and an async StaticExporter version which can be build with `build` and `build_async` methods.
 
-## Overview
+Refer to the [`plotly_static` API Documentation](https://docs.rs/plotly_static/) a more detailed description.
 
+## Overview
 
 ## Features 
 
+- **Async/Sync API**
 - **Multiple Export Formats**: PNG, JPEG, SVG, PDF
 - **Exporter Reuse (new API)**: Efficient reuse of a single `StaticExporter` instance
 - **String Export**: Base64 and SVG string output for web applications
@@ -45,17 +47,32 @@ plotly = { version = "0.13", features = ["static_export_geckodriver"] }
 plotly = { version = "0.13", features = ["static_export_chromedriver"] }
 ```
 
-## Running the Example
+## Running the Example(s)
+
+To run the `sync` API example 
+
+```bash
+# Basic run
+cargo run --bin sync
+
+# With debug logging
+RUST_LOG=debug cargo run --bin sync
+
+# With custom WebDriver path
+WEBDRIVER_PATH=/path/to/chromedriver cargo run --bin sync
+```
+
+To run the `async` API example  
 
 ```bash
 # Basic run
-cargo run
+cargo run --bin async
 
 # With debug logging
-RUST_LOG=debug cargo run
+RUST_LOG=debug cargo run --bin async
 
 # With custom WebDriver path
-WEBDRIVER_PATH=/path/to/chromedriver cargo run
+WEBDRIVER_PATH=/path/to/chromedriver cargo run --bin async
 ```
 
 ## Output

examples/static_export/src/bin/async.rs

@@ -0,0 +1,77 @@
+use log::info;
+use plotly::plotly_static::{ImageFormat, StaticExporterBuilder};
+use plotly::{Plot, Scatter};
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();
+
+    // Create some plots
+    let mut plot1 = Plot::new();
+    plot1.add_trace(Scatter::new(vec![1, 2, 3, 4], vec![10, 15, 13, 17]).name("trace1"));
+
+    let mut plot2 = Plot::new();
+    plot2.add_trace(Scatter::new(vec![2, 3, 4, 5], vec![16, 5, 11, 9]).name("trace2"));
+
+    std::fs::create_dir_all("./output").unwrap();
+
+    info!("Creating AsyncStaticExporter with default configuration...");
+    let mut exporter = StaticExporterBuilder::default()
+        .webdriver_port(5111)
+        .build_async()
+        .expect("Failed to create AsyncStaticExporter");
+
+    info!("Exporting multiple plots using a single AsyncStaticExporter...");
+    plot1
+        .write_image_async(
+            &mut exporter,
+            "./output/plot1_async_api",
+            ImageFormat::PNG,
+            800,
+            600,
+            1.0,
+        )
+        .await?;
+    plot1
+        .write_image_async(
+            &mut exporter,
+            "./output/plot1_async_api",
+            ImageFormat::JPEG,
+            800,
+            600,
+            1.0,
+        )
+        .await?;
+    plot2
+        .write_image_async(
+            &mut exporter,
+            "./output/plot2_async_api",
+            ImageFormat::SVG,
+            800,
+            600,
+            1.0,
+        )
+        .await?;
+    plot2
+        .write_image_async(
+            &mut exporter,
+            "./output/plot2_async_api",
+            ImageFormat::PDF,
+            800,
+            600,
+            1.0,
+        )
+        .await?;
+
+    info!("Exporting to base64 and SVG strings with async API...");
+    let _base64_data = plot1
+        .to_base64_async(&mut exporter, ImageFormat::PNG, 400, 300, 1.0)
+        .await?;
+    let _svg_data = plot1.to_svg_async(&mut exporter, 400, 300, 1.0).await?;
+
+    // Always close the exporter to ensure proper release of WebDriver resources
+    exporter.close().await;
+
+    info!("Async exports completed successfully!");
+    Ok(())
+}

examples/static_export/src/main.rs examples/static_export/src/bin/sync.rsexamples/static_export/src/main.rs renamed to examples/static_export/src/bin/sync.rs

@@ -28,13 +28,15 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
         1.0,
     )?;
     plot3.write_image("./output/plot3_legacy_api", ImageFormat::SVG, 800, 600, 1.0)?;
-    plot1.write_image("./output/plot3_legacy_api", ImageFormat::PDF, 800, 600, 1.0)?;
+
+    plot1.write_image("./output/plot1_legacy_api", ImageFormat::PDF, 800, 600, 1.0)?;
 
     // Create a single StaticExporter to reuse across all plots
     // This is more efficient than creating a new exporter for each plot which
     // happens implicitly in the calls above using the old API
     info!("Creating StaticExporter with default configuration...");
     let mut exporter = StaticExporterBuilder::default()
+        .webdriver_port(5112)
         .build()
         .expect("Failed to create StaticExporter");
 
@@ -108,5 +110,8 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
         .expect("Failed to create custom StaticExporter");
     */
 
+    // Always close the exporter to ensure proper release of WebDriver resources
+    exporter.close();
+
     Ok(())
 }

plotly/Cargo.toml

@@ -52,7 +52,7 @@ dyn-clone = "1"
 erased-serde = "0.4"
 image = { version = "0.25", optional = true }
 plotly_derive = { version = "0.13", path = "../plotly_derive" }
-plotly_static = { version = "0.0", path = "../plotly_static", optional = true }
+plotly_static = { version = "0.1", path = "../plotly_static", optional = true }
 plotly_kaleido = { version = "0.13", path = "../plotly_kaleido", optional = true }
 ndarray = { version = "0.16", optional = true }
 once_cell = "1"

plotly/src/layout/rangebreaks.rs

@@ -4,7 +4,7 @@ use serde::Serialize;
 use crate::private::NumOrString;
 
 /// Struct representing a rangebreak for Plotly axes.
-/// See: https://plotly.com/python/reference/layout/xaxis/#layout-xaxis-rangebreaks
+/// See: <https://plotly.com/python/reference/layout/xaxis/#layout-xaxis-rangebreaks>
 #[derive(Debug, Clone, Serialize, PartialEq, FieldSetter)]
 pub struct RangeBreak {
     /// Sets the lower and upper bounds for this range break, e.g. ["sat",

plotly/src/layout/scene.rs

@@ -357,7 +357,7 @@ impl Rotation {
 pub struct Projection {
     #[serde(rename = "type")]
     projection_type: Option<ProjectionType>,
-    /// Sets the rotation of the map projection. See https://plotly.com/python/reference/layout/geo/#layout-geo-projection-rotation
+    // Sets the rotation of the map projection. See https://plotly.com/python/reference/layout/geo/#layout-geo-projection-rotation
     #[serde(rename = "rotation")]
     rotation: Option<Rotation>,
 }

plotly/src/lib.rs

@@ -6,7 +6,7 @@
 //!
 //! The `kaleido` and `kaleido_download` features are deprecated since version
 //! 0.13.0 and will be removed in version 0.14.0. Please migrate to the
-//! `plotly_static` and `plotly_static_download` features instead.
+//! `plotly_static` and `static_export_*` features instead.
 #![recursion_limit = "256"] // lets us use a large serde_json::json! macro for testing crate::layout::Axis
 extern crate askama;
 extern crate rand;