refactor

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

Author: andrei-ng

README.md

@@ -121,6 +121,8 @@ let svg_string = plot.to_svg(800, 600, 1.0)?;
 
 **Note:** This feature requires a WebDriver-compatible browser (Chrome or Firefox) as well as a Webdriver (chromedriver/geckodriver) to be available on the system. For advanced usage, see the [`plotly_static` crate documentation](https://docs.rs/plotly_static/).
 
+> Enabling any of the `plotly` features `static_export_chromedriver`, `static_export_geckodriver`, or `static_export_default` gives access to both the synchronous `StaticExporter` and the asynchronous `AsyncStaticExporter` (available via `plotly::plotly_static`). Use the async API in async contexts; avoid calling the sync API from async code.
+
 ## Exporting Static Images with Kaleido (legacy)
 
 Enable the `kaleido` feature and opt in for automatic downloading of the `kaleido` binaries by doing the following

docs/book/src/fundamentals/static_image_export.md

@@ -34,6 +34,8 @@ plotly = { version = "0.13", features = ["static_export_chromedriver", "static_e
 plotly = { version = "0.13", features = ["static_export_default"] }
 ```
 
+> Enabling any of the static export features in `plotly` (`static_export_chromedriver`, `static_export_geckodriver`, or `static_export_default`) enables both APIs from `plotly_static`: the sync `StaticExporter` and the async `AsyncStaticExporter` (reachable as `plotly::plotly_static::AsyncStaticExporter`). Prefer the async API inside async code.
+
 ## Prerequisites
 
 1. **WebDriver Installation**: You need either chromedriver or geckodriver installed
@@ -74,6 +76,7 @@ For better performance when exporting multiple plots, reuse a single `StaticExpo
 ```rust
 use plotly::{Plot, Scatter};
 use plotly::plotly_static::{StaticExporterBuilder, ImageFormat};
+use plotly::prelude::*;
 
 let mut plot1 = Plot::new();
 plot1.add_trace(Scatter::new(vec![1, 2, 3], vec![4, 5, 6]));
@@ -87,9 +90,9 @@ let mut exporter = StaticExporterBuilder::default()
     .expect("Failed to create StaticExporter");
 
 // Export multiple plots using the same exporter
-plot1.write_image_with_exporter(&mut exporter, "plot1", ImageFormat::PNG, 800, 600, 1.0)
+exporter.write_image(&plot1, "plot1", ImageFormat::PNG, 800, 600, 1.0)
     .expect("Failed to export plot1");
-plot2.write_image_with_exporter(&mut exporter, "plot2", ImageFormat::JPEG, 800, 600, 1.0)
+exporter.write_image(&plot2, "plot2", ImageFormat::JPEG, 800, 600, 1.0)
     .expect("Failed to export plot2");
 
 // Always close the exporter to ensure proper release of WebDriver resources
@@ -117,6 +120,7 @@ For web applications or APIs, you can export to strings:
 ```rust
 use plotly::{Plot, Scatter};
 use plotly::plotly_static::{StaticExporterBuilder, ImageFormat};
+use plotly::prelude::*;
 
 let mut plot = Plot::new();
 plot.add_trace(Scatter::new(vec![1, 2, 3], vec![4, 5, 6]));
@@ -126,11 +130,11 @@ let mut exporter = StaticExporterBuilder::default()
     .expect("Failed to create StaticExporter");
 
 // Get base64 data (useful for embedding in HTML)
-let base64_data = plot.to_base64_with_exporter(&mut exporter, ImageFormat::PNG, 400, 300, 1.0)
+let base64_data = exporter.to_base64(&plot, ImageFormat::PNG, 400, 300, 1.0)
     .expect("Failed to export plot");
 
 // Get SVG data (vector format, scalable)
-let svg_data = plot.to_svg_with_exporter(&mut exporter, 400, 300, 1.0)
+let svg_data = exporter.to_svg(&plot, 400, 300, 1.0)
     .expect("Failed to export plot");
 
 // Always close the exporter to ensure proper release of WebDriver resources
@@ -191,7 +195,9 @@ 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. 
+`plotly_static` package offers an `async` API which is exposed in `plotly` via the `write_image_async`, `to_base64_async` and `to_svg_async` functions. However, the user must pass an `AsyncStaticExporter` asynchronous exporter insted of a synchronous one by building it via `StaticExportBuilder`'s `build_async` method. 
+
+> Note: Both sync and async exporters are available whenever a `static_export_*` feature is enabled in `plotly`.
 
 For more details check the [`plotly_static` API Documentation](https://docs.rs/plotly_static/)
 

examples/customization/consistent_static_format_export/src/main.rs

@@ -3,6 +3,7 @@ use plotly::color::{NamedColor, Rgb};
 use plotly::common::{Anchor, Font, Line, Marker, MarkerSymbol, Mode, Title};
 use plotly::layout::{Axis, ItemSizing, Legend, Margin, Shape, ShapeLine, ShapeType};
 use plotly::plotly_static::{ImageFormat, StaticExporterBuilder};
+use plotly::prelude::*;
 use plotly::{Layout, Plot, Scatter};
 
 fn line_and_scatter_plot(
@@ -149,13 +150,16 @@ fn line_and_scatter_plot(
         .unwrap();
 
     info!("Exporting to PNG format...");
-    plot.write_image_with_exporter(&mut exporter, file_name, ImageFormat::PNG, 1280, 960, 1.0)
+    exporter
+        .write_image(&plot, file_name, ImageFormat::PNG, 1280, 960, 1.0)
         .unwrap();
     info!("Exporting to SVG format...");
-    plot.write_image_with_exporter(&mut exporter, file_name, ImageFormat::SVG, 1280, 960, 1.0)
+    exporter
+        .write_image(&plot, file_name, ImageFormat::SVG, 1280, 960, 1.0)
         .unwrap();
     info!("Exporting to PDF format...");
-    plot.write_image_with_exporter(&mut exporter, file_name, ImageFormat::PDF, 1280, 960, 1.0)
+    exporter
+        .write_image(&plot, file_name, ImageFormat::PDF, 1280, 960, 1.0)
         .unwrap();
 
     info!("Export complete. Check the output files:");

examples/static_export/README.md

@@ -6,9 +6,7 @@ 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.  
 
-There are both a sync and an async StaticExporter version which can be build with `build` and `build_async` methods.
-
-Refer to the [`plotly_static` API Documentation](https://docs.rs/plotly_static/) a more detailed description.
+When any of the `plotly` static export features are enabled (`static_export_chromedriver`, `static_export_geckodriver`, or `static_export_default`), both `StaticExporter` (sync) and `AsyncStaticExporter` (async) are available via `plotly::plotly_static`. This example includes separate `sync` and `async` bins demonstrating both.  Refer to the [`plotly_static` API Documentation](https://docs.rs/plotly_static/) a more detailed description.
 
 ## Overview
 

examples/static_export/src/bin/async.rs

@@ -1,5 +1,6 @@
 use log::info;
 use plotly::plotly_static::{ImageFormat, StaticExporterBuilder};
+use plotly::prelude::*;
 use plotly::{Plot, Scatter};
 
 #[tokio::main]
@@ -22,52 +23,24 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         .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,
-        )
+    exporter
+        .write_image(&plot1, "./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,
-        )
+    exporter
+        .write_image(&plot1, "./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,
-        )
+    exporter
+        .write_image(&plot2, "./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,
-        )
+    exporter
+        .write_image(&plot2, "./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)
+    let _base64_data = exporter
+        .to_base64(&plot1, ImageFormat::PNG, 400, 300, 1.0)
         .await?;
-    let _svg_data = plot1.to_svg_async(&mut exporter, 400, 300, 1.0).await?;
+    let _svg_data = exporter.to_svg(&plot1, 400, 300, 1.0).await?;
 
     // Always close the exporter to ensure proper release of WebDriver resources
     exporter.close().await;

examples/static_export/src/bin/sync.rs

@@ -1,5 +1,6 @@
 use log::info;
 use plotly::plotly_static::{ImageFormat, StaticExporterBuilder};
+use plotly::prelude::*;
 use plotly::{Plot, Scatter};
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {
@@ -41,34 +42,34 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
         .expect("Failed to create StaticExporter");
 
     info!("Exporting multiple plots using a single StaticExporter...");
-    // Export all plots using the same exporter
-    plot1.write_image_with_exporter(
-        &mut exporter,
+    // Export all plots using the same exporter (new unified naming via extension trait)
+    exporter.write_image(
+        &plot1,
         "./output/plot1_new_api",
         ImageFormat::PNG,
         800,
         600,
         1.0,
     )?;
-    plot2.write_image_with_exporter(
-        &mut exporter,
+    exporter.write_image(
+        &plot2,
         "./output/plot2_new_api",
         ImageFormat::JPEG,
         800,
         600,
         1.0,
     )?;
-    plot3.write_image_with_exporter(
-        &mut exporter,
+    exporter.write_image(
+        &plot3,
         "./output/plot3_new_api",
         ImageFormat::SVG,
         800,
         600,
         1.0,
     )?;
 
-    plot1.write_image_with_exporter(
-        &mut exporter,
+    exporter.write_image(
+        &plot1,
         "./output/plot1_new_api",
         ImageFormat::PDF,
         800,
@@ -79,11 +80,10 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     // Demonstrate string-based export
     info!("Exporting to base64 and SVG strings...");
     // Get base64 data (useful for embedding in HTML or APIs)
-    let base64_data =
-        plot1.to_base64_with_exporter(&mut exporter, ImageFormat::PNG, 400, 300, 1.0)?;
+    let base64_data = exporter.to_base64(&plot1, ImageFormat::PNG, 400, 300, 1.0)?;
     info!("Base64 data length: {}", base64_data.len());
 
-    let svg_data = plot1.to_svg_with_exporter(&mut exporter, 400, 300, 1.0)?;
+    let svg_data = exporter.to_svg(&plot1, 400, 300, 1.0)?;
     info!("SVG data starts with: {}", &svg_data[..50]);
 
     info!("All exports completed successfully!");

plotly/Cargo.toml

@@ -17,13 +17,22 @@ keywords = ["plot", "chart", "plotly"]
 exclude = ["target/*"]
 
 [features]
-static_export_chromedriver = ["plotly_static", "plotly_static/chromedriver"]
-static_export_geckodriver = ["plotly_static", "plotly_static/geckodriver"]
+static_export_chromedriver = [
+    "plotly_static",
+    "plotly_static/chromedriver",
+    "async-trait",
+]
+static_export_geckodriver = [
+    "plotly_static",
+    "plotly_static/geckodriver",
+    "async-trait",
+]
 static_export_wd_download = ["plotly_static/webdriver_download"]
 static_export_default = [
     "plotly_static",
     "plotly_static/chromedriver",
     "plotly_static/webdriver_download",
+    "async-trait",
 ]
 
 plotly_ndarray = ["ndarray"]
@@ -64,6 +73,7 @@ rand = { version = "0.9", default-features = false, features = [
     "small_rng",
     "alloc",
 ] }
+async-trait = { version = "0.1", optional = true }
 
 [target.'cfg(target_arch = "wasm32")'.dependencies]
 wasm-bindgen-futures = { version = "0.4" }