Use pyplot functions into their own submodule (as matplotlib)

Author: Chris00

README.md

@@ -35,7 +35,7 @@ A basic example
 ---------------
 
 ```rust
-use matplotlib as plt;
+use matplotlib::pyplot as plt;
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {
     let (fig, [[mut ax]]) = plt::subplots()?;

examples/a_simple_example.rs

@@ -1,7 +1,7 @@
 /// https://matplotlib.org/stable/tutorials/introductory/quick_start.html#a-simple-example
 
 use std::error::Error;
-use matplotlib as plt;
+use matplotlib::pyplot as plt;
 
 fn main() -> Result<(), Box<dyn Error>> {
     let (fig, [[mut ax]]) = plt::subplots()?;

examples/basic_example.rs

@@ -1,6 +1,6 @@
 // Example for the README
 
-use matplotlib as plt;
+use matplotlib::pyplot as plt;
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {
     let (fig, [[mut ax]]) = plt::subplots()?;

examples/flower.rs

@@ -1,5 +1,5 @@
 use polars_core::prelude::*;
-use matplotlib as plt;
+use matplotlib::pyplot as plt;
 
 // Yellow Flag Iris, attributed to Iris pseudacorus flowers were
 // measured in Norfolk marshes in 2018 by LCrossman.

src/axes.rs

@@ -37,7 +37,7 @@ impl Axes {
     /// # Example
     ///
     /// ```
-    /// use matplotlib::{self as plt, colors};
+    /// use matplotlib::{pyplot as plt, colors};
     /// let (fig, [[mut ax]]) = plt::subplots()?;
     /// let x = [1., 2., 3., 4.];
     /// let y = [1., 4., 2., 3.];
@@ -68,7 +68,7 @@ impl Axes {
     /// # Example
     ///
     /// ```
-    /// use matplotlib as plt;
+    /// use matplotlib::pyplot as plt;
     /// let (fig, [[mut ax]]) = plt::subplots()?;
     /// ax.y(&[1., 4., 2., 3.]).plot();
     /// fig.save().to_file("target/Y_plot.pdf")?;
@@ -90,13 +90,15 @@ impl Axes {
     /// # Example
     ///
     /// ```
-    /// use matplotlib as plt;
+    /// use matplotlib::pyplot as plt;
     /// let (fig, [[mut ax]]) = plt::subplots()?;
     /// ax.xy_from(&[(1., 2.), (4., 2.), (2., 3.), (3., 4.)]).plot();
     /// ax.xy_from([(1., 0.), (2., 3.), (3., 1.), (4., 3.)]).plot();
     /// fig.save().to_file("target/XY_from_plot.pdf")?;
     /// # Ok::<(), matplotlib::Error>(())
     /// ```
+    // FIXME: show an example combining iterators using `zip`.  The
+    // `covid` research project may serve as a source of inspiration.
     pub fn xy_from<'a, I>(&'a mut self, xy: I) -> XYFrom<'a, I>
     where
         I: IntoIterator,
@@ -114,7 +116,7 @@ impl Axes {
     ///
     /// # Example
     /// ```
-    /// use matplotlib as plt;
+    /// use matplotlib::pyplot as plt;
     /// let (fig, [[mut ax]]) = plt::subplots()?;
     /// ax.fun(|x| x * x, 0., 1.).plot();
     /// fig.save().to_file("target/Fun_plot.pdf")?;
@@ -142,7 +144,7 @@ impl Axes {
     /// # Example
     ///
     /// ```
-    /// use matplotlib::{self as plt, colors::Tab};
+    /// use matplotlib::{pyplot as plt, colors::Tab};
     /// use ndarray::{Array1, Array2};
     /// let x: Array1<f64> = Array1::linspace(-1., 1., 30);
     /// let y: Array1<f64> = Array1::linspace(-1., 1., 30);
@@ -180,7 +182,7 @@ impl Axes {
     /// # Example
     ///
     /// ```
-    /// use matplotlib as plt;
+    /// use matplotlib::pyplot as plt;
     /// let (fig, [[mut ax]]) = plt::subplots()?;
     /// ax.contour_fun([-1., 1.], [-1., 1.], |x, y| {
     ///     (0.5 * x).powi(2) + y.powi(2)

src/lib.rs

@@ -19,10 +19,9 @@ use pyo3::{
 
 pub mod colors;
 pub mod figure;
-use figure::Figure;
 pub mod axes;
-use axes::Axes;
 pub mod lines;
+pub mod pyplot;
 pub mod text;
 include!("macros.rs");
 
@@ -93,76 +92,45 @@ impl From<&ImportError> for Error {
     }
 }
 
-// RuntimeWarning: More than 20 figures have been opened. Figures
-// created through the pyplot interface (`matplotlib.pyplot.figure`)
-// are retained until explicitly closed and may consume too much
-// memory. […]  Consider using `matplotlib.pyplot.close()`.
-//
-// => Do not use pyplot interface (since we need handles anyway).
-
-fn pyplot<'a, 'py>(
-    py: Python<'py>,
-    f: &'a PyOnceLock<Py<PyAny>>,
-    attr_name: &str
-) -> Result<&'a Bound<'py, PyAny>, Error> {
-    f.get_or_try_init(py, || {
-        Ok(py.import("matplotlib.pyplot").into_error(py)?
-            .getattr(attr_name).into_error(py)?
-            .unbind())
-    })
-        .map(|f| f.bind(py))
-}
-
-/// Return a new figure.
-/// This figure is tracked by Matplotlib so [`show()`] displays it.
-/// This implies it must be explicitly deallocated using [`close()`].
-pub fn figure() -> Result<Figure, Error> {
-    static FIG: PyOnceLock<Py<PyAny>> = PyOnceLock::new();
-    Python::attach(|py| {
-        let fig = pyplot(py, &FIG, "figure")?;
-        Ok(Figure { fig: fig.call0().into_error(py)?.unbind() })
-    })
+/// A dict-like key-value store for config parameters, including
+/// validation.
+///
+/// Validating functions are defined and associated with rc parameters
+/// in [`rcsetup`].
+#[derive(Debug)]
+pub struct RcParams {
+    dict: Py<PyAny>,
 }
 
-/// Return a figure and a grid of subplots with `R` rows and `C` columns.
-pub fn subplots<const R: usize, const C: usize>(
-) -> Result<(Figure, [[Axes; C]; R]), Error> {
-    let fig = figure()?;
-    let ax = fig.subplots()?;
-    Ok((fig, ax))
+impl RcParams {
+    /// Return the subset of the `self` dictionary whose keys match
+    /// ([`using
+    /// re.search()`](https://docs.python.org/3/library/re.html#re.search)) the
+    /// given pattern.
+    pub fn find_all(&self, pat: &str) -> Vec<String> {
+        Python::attach(|py| {
+            self.dict.bind(py)
+                .call_method1(intern!(py, "find_all"), (pat,)).unwrap()
+                .cast().unwrap()
+                .extract().unwrap()
+        })
+    }
 }
 
-/// Display all open figures created with [`figure()`] or [`subplots()`].
-pub fn show() {
-    static SHOW: PyOnceLock<Py<PyAny>> = PyOnceLock::new();
-    Python::attach(|py| {
-        pyplot(py, &SHOW, "show")
-            .expect("Cannot get matplotlib.pyplot.show")
-            .call0()
-            .expect("matplotlib.pyplot.show did not succeed");
-    })
+pub fn rcsetup() {
+    todo!()
 }
 
-/// Close the figure `fig` (created with [`figure()`] or [`subplots()`]).
-pub fn close(fig: Figure) {
-    static CLOSE: PyOnceLock<Py<PyAny>> = PyOnceLock::new();
-    Python::attach(|py| {
-        pyplot(py, &CLOSE, "close")
-            .expect("Cannot find matplotlib.pyplot.close")
-            .call1((fig.fig,))
-            .expect("matplotlib.pyplot.close did not succeed");
-    })
+#[derive(Debug)]
+pub struct RcParamsRef<'a> {
+    dict: &'a Bound<'a, PyAny>,
 }
 
-/// Close all figures created with [`figure()`] or [`subplots()`].
-pub fn close_all() {
-    static CLOSE: PyOnceLock<Py<PyAny>> = PyOnceLock::new();
-    Python::attach(|py| {
-        pyplot(py, &CLOSE, "close")
-            .expect("Cannot get matplotlib.pyplot.close")
-            .call1(("all",))
-            .expect("matplotlib.pyplot.close('all') did not succeed");
-    })
+fn rc_params(py: Python<'_>) -> RcParamsRef<'_> {
+    static RCPARAMS: PyOnceLock<Py<PyAny>> = PyOnceLock::new();
+    let dict = RCPARAMS.import(py, "matplotlib", "rcParams")
+        .expect("Cannot find matplotlib.rcParams");
+    RcParamsRef { dict }
 }
 
 

src/pyplot.rs

@@ -0,0 +1,88 @@
+//! State-based interface to matplotlib.  It provides an implicit,
+//! MATLAB-like, way of plotting.  It also opens figures on your
+//! screen, and acts as the figure GUI manager.
+//!
+//! pyplot is mainly intended for interactive plots and simple cases
+//! of programmatic plot generation:
+//!
+//! ```
+//! use matplotlib::pyplot as plt;
+//! 
+//! ```
+
+use pyo3::{
+    prelude::*, sync::PyOnceLock,
+};
+use crate::{axes::Axes, Error, figure::Figure, IntoError};
+
+// RuntimeWarning: More than 20 figures have been opened. Figures
+// created through the pyplot interface (`matplotlib.pyplot.figure`)
+// are retained until explicitly closed and may consume too much
+// memory. […]  Consider using `matplotlib.pyplot.close()`.
+//
+// => Do not use pyplot interface (since we need handles anyway).
+
+fn pyplot<'a, 'py>(
+    py: Python<'py>,
+    f: &'a PyOnceLock<Py<PyAny>>,
+    attr_name: &str
+) -> Result<&'a Bound<'py, PyAny>, Error> {
+    f.get_or_try_init(py, || {
+        Ok(py.import("matplotlib.pyplot").into_error(py)?
+            .getattr(attr_name).into_error(py)?
+            .unbind())
+    })
+        .map(|f| f.bind(py))
+}
+
+/// Return a new figure.
+/// This figure is tracked by Matplotlib so [`show()`] displays it.
+/// This implies it must be explicitly deallocated using [`close()`].
+pub fn figure() -> Result<Figure, Error> {
+    static FIG: PyOnceLock<Py<PyAny>> = PyOnceLock::new();
+    Python::attach(|py| {
+        let fig = pyplot(py, &FIG, "figure")?;
+        Ok(Figure { fig: fig.call0().into_error(py)?.unbind() })
+    })
+}
+
+/// Return a figure and a grid of subplots with `R` rows and `C` columns.
+pub fn subplots<const R: usize, const C: usize>(
+) -> Result<(Figure, [[Axes; C]; R]), Error> {
+    let fig = figure()?;
+    let ax = fig.subplots()?;
+    Ok((fig, ax))
+}
+
+/// Display all open figures created with [`figure()`] or [`subplots()`].
+pub fn show() {
+    static SHOW: PyOnceLock<Py<PyAny>> = PyOnceLock::new();
+    Python::attach(|py| {
+        pyplot(py, &SHOW, "show")
+            .expect("Cannot get matplotlib.pyplot.show")
+            .call0()
+            .expect("matplotlib.pyplot.show did not succeed");
+    })
+}
+
+/// Close the figure `fig` (created with [`figure()`] or [`subplots()`]).
+pub fn close(fig: Figure) {
+    static CLOSE: PyOnceLock<Py<PyAny>> = PyOnceLock::new();
+    Python::attach(|py| {
+        pyplot(py, &CLOSE, "close")
+            .expect("Cannot find matplotlib.pyplot.close")
+            .call1((fig.fig,))
+            .expect("matplotlib.pyplot.close did not succeed");
+    })
+}
+
+/// Close all figures created with [`figure()`] or [`subplots()`].
+pub fn close_all() {
+    static CLOSE: PyOnceLock<Py<PyAny>> = PyOnceLock::new();
+    Python::attach(|py| {
+        pyplot(py, &CLOSE, "close")
+            .expect("Cannot get matplotlib.pyplot.close")
+            .call1(("all",))
+            .expect("matplotlib.pyplot.close('all') did not succeed");
+    })
+}