MatplotLibAPI 4.0.2__tar.gz → 4.0.4__tar.gz

{matplotlibapi-4.0.2 → matplotlibapi-4.0.4}/.github/workflows/ci.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
 
     steps:
       - uses: actions/checkout@v4
@@ -44,3 +44,6 @@ jobs:
 
       - name: Type check with pyright
         run: pyright src
+
+      - name: Run tests with coverage
+        run: pytest -q --cov=src --cov-report=term-missing --cov-fail-under=70

{matplotlibapi-4.0.2 → matplotlibapi-4.0.4}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: MatplotLibAPI
-Version: 4.0.2
+Version: 4.0.4
 License-File: LICENSE
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Requires-Dist: kaleido
 Requires-Dist: matplotlib
 Requires-Dist: nbformat

matplotlibapi-4.0.4/examples/bubble.py

@@ -0,0 +1,42 @@
+"""
+Example module for network graph sample data generation and plotting.
+
+This module provides functions to generate and plot sample network data for testing.
+"""
+
+import sys
+from pathlib import Path
+from matplotlib.figure import Figure
+import pandas as pd
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+from MatplotLibAPI.bubble import Bubble
+
+
+def generate_sample_data() -> pd.DataFrame:
+    """Generate and save sample data for a bubble chart."""
+    data = {
+        "country": ["USA", "China", "India", "Brazil", "Nigeria"],
+        "population": [331, 1441, 1393, 213, 206],  # in millions
+        "gdp_per_capita": [63593, 10500, 2191, 7741, 2229],
+        "age": [62, 45, 35, 42, 30],
+    }
+    df = pd.DataFrame(data)
+    return df
+
+
+def plot_sample_data() -> Figure:
+    """Load a sample DataFrame for testing."""
+
+    pd_df = generate_sample_data()
+    o_plot = Bubble(
+        pd_df=pd_df, label="country", x="population", y="gdp_per_capita", z="age"
+    )
+    plot_fig = o_plot.fplot(title="Bubble Graph")
+
+    return plot_fig
+
+
+if __name__ == "__main__":
+    plot_fig = plot_sample_data()
+    plot_fig.show()

{matplotlibapi-4.0.2 → matplotlibapi-4.0.4}/examples/network.py

@@ -13,7 +13,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
 from MatplotLibAPI.network import NetworkGraph
 
 
-def generate_sample_network_data() -> pd.DataFrame:
+def generate_sample_data() -> pd.DataFrame:
     """Generate and save sample data for a network graph."""
     data = {
         "city_a": ["New York", "London", "Tokyo", "Sydney", "New York"],
@@ -24,21 +24,18 @@ def generate_sample_network_data() -> pd.DataFrame:
     return df
 
 
-def plot_sample_network_data() -> Figure:
+def plot_sample_data() -> Figure:
     """Load a sample DataFrame for testing."""
 
-    pd_df = generate_sample_network_data()
+    pd_df = generate_sample_data()
     graph = NetworkGraph.from_pandas_edgelist(
         pd_df, source="city_a", target="city_b", edge_weight_col="distance_km"
     )
-    plot_fig = graph.fplot_w(title="Network Graph")
+    plot_fig = graph.fplot(title="Network Graph")
 
     return plot_fig
 
 
 if __name__ == "__main__":
-    plot_df = generate_sample_network_data()
-    f = plot_df.mpl.fplot_network(
-        source="city_a", target="city_b", edge_weight_col="distance_km"
-    )
-    plot_fig = plot_sample_network_data()
+    plot_fig = plot_sample_data()
+    plot_fig.show()

{matplotlibapi-4.0.2 → matplotlibapi-4.0.4}/examples/sample_data.py

@@ -6,25 +6,16 @@ import pandas as pd
 
 def generate_bubble_data():
     """Generate and save sample data for a bubble chart."""
-    data = {
-        "country": ["USA", "China", "India", "Brazil", "Nigeria"],
-        "population": [331, 1441, 1393, 213, 206],  # in millions
-        "gdp_per_capita": [63593, 10500, 2191, 7741, 2229],
-        "continent": ["North America", "Asia", "Asia", "South America", "Africa"],
-    }
-    df = pd.DataFrame(data)
-    df.to_csv("data/bubble.csv", index=False)
+    from .bubble import generate_sample_data
+
+    generate_sample_data().to_csv("data/bubble.csv", index=False)
 
 
 def generate_network_data():
     """Generate and save sample data for a network graph."""
-    data = {
-        "city_a": ["New York", "London", "Tokyo", "Sydney", "New York"],
-        "city_b": ["London", "Tokyo", "Sydney", "New York", "Tokyo"],
-        "distance_km": [5585, 9562, 7824, 16027, 10850],
-    }
-    df = pd.DataFrame(data)
-    df.to_csv("data/network.csv", index=False)
+    from .network import generate_sample_data
+
+    generate_sample_data().to_csv("data/network.csv", index=False)
 
 
 def generate_pivot_data():

{matplotlibapi-4.0.2 → matplotlibapi-4.0.4}/pyproject.toml

@@ -3,9 +3,9 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 [project]
 name = "MatplotLibAPI"
-version = "4.0.2"
+version = "4.0.4"
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 dependencies = [
     "pandas",
     "matplotlib",

matplotlibapi-4.0.4/src/MatplotLibAPI/__init__.py

@@ -0,0 +1,6 @@
+"""Public API and pandas accessor for MatplotLibAPI."""
+
+from .accessor import DataFrameAccessor
+from .types import CorrelationMethod
+
+__all__ = ["DataFrameAccessor", "CorrelationMethod"]

{matplotlibapi-4.0.2 → matplotlibapi-4.0.4}/src/MatplotLibAPI/accessor.py

@@ -10,7 +10,6 @@ from matplotlib.axes import Axes
 from matplotlib.figure import Figure
 from pandas.api.extensions import register_dataframe_accessor
 
-from .base_plot import BasePlot
 from .style_template import (
     FIG_SIZE,
     AREA_STYLE_TEMPLATE,
@@ -21,148 +20,13 @@ from .style_template import (
     TREEMAP_STYLE_TEMPLATE,
     StyleTemplate,
 )
-from .typing import CorrelationMethod
+
+from .types import CorrelationMethod
 
 if TYPE_CHECKING:
     import plotly.graph_objects as go
 
 
-def _heatmap_imports() -> tuple[StyleTemplate, Any, Any, Any, Any]:
-    from .heatmap import (
-        HEATMAP_STYLE_TEMPLATE,
-        aplot_correlation_matrix,
-        aplot_heatmap,
-        fplot_correlation_matrix,
-        fplot_heatmap,
-    )
-
-    return (
-        HEATMAP_STYLE_TEMPLATE,
-        aplot_correlation_matrix,
-        aplot_heatmap,
-        fplot_correlation_matrix,
-        fplot_heatmap,
-    )
-
-
-def _network_imports() -> tuple[StyleTemplate, Any, Any, Any, Any, Any, Any]:
-    from .network import (
-        NETWORK_STYLE_TEMPLATE,
-        aplot_network,
-        aplot_network_node,
-        aplot_network_components,
-        fplot_network,
-        fplot_network_node,
-        fplot_network_components,
-    )
-
-    return (
-        NETWORK_STYLE_TEMPLATE,
-        aplot_network,
-        aplot_network_node,
-        aplot_network_components,
-        fplot_network,
-        fplot_network_node,
-        fplot_network_components,
-    )
-
-
-def _wordcloud_imports() -> tuple[StyleTemplate, Any, Any]:
-    from .word_cloud import WORDCLOUD_STYLE_TEMPLATE, aplot_wordcloud, fplot_wordcloud
-
-    return WORDCLOUD_STYLE_TEMPLATE, aplot_wordcloud, fplot_wordcloud
-
-
-def _sankey_imports() -> tuple[StyleTemplate, Any]:
-    from .sankey import SANKEY_STYLE_TEMPLATE, fplot_sankey
-
-    return SANKEY_STYLE_TEMPLATE, fplot_sankey
-
-
-def aplot_histogram(*args: Any, **kwargs: Any) -> Axes:
-    from .histogram import aplot_histogram as _aplot_histogram
-
-    return _aplot_histogram(*args, **kwargs)
-
-
-def fplot_histogram(*args: Any, **kwargs: Any) -> Figure:
-    from .histogram import fplot_histogram as _fplot_histogram
-
-    return _fplot_histogram(*args, **kwargs)
-
-
-def aplot_pie_donut(*args: Any, **kwargs: Any) -> Axes:
-    from .pie import aplot_pie as _aplot_pie_donut
-
-    return _aplot_pie_donut(*args, **kwargs)
-
-
-def fplot_pie_donut(*args: Any, **kwargs: Any) -> Figure:
-    from .pie import fplot_pie as _fplot_pie_donut
-
-    return _fplot_pie_donut(*args, **kwargs)
-
-
-def aplot_table(*args: Any, **kwargs: Any) -> Axes:
-    from .table import aplot_table as _aplot_table
-
-    return _aplot_table(*args, **kwargs)
-
-
-def fplot_table(*args: Any, **kwargs: Any) -> Figure:
-    from .table import fplot_table as _fplot_table
-
-    return _fplot_table(*args, **kwargs)
-
-
-def aplot_timeserie(*args: Any, **kwargs: Any) -> Axes:
-    from .timeserie import aplot_timeserie as _aplot_timeserie
-
-    return _aplot_timeserie(*args, **kwargs)
-
-
-def fplot_timeserie(*args: Any, **kwargs: Any) -> Figure:
-    from .timeserie import fplot_timeserie as _fplot_timeserie
-
-    return _fplot_timeserie(*args, **kwargs)
-
-
-def aplot_waffle(*args: Any, **kwargs: Any) -> Axes:
-    from .waffle import aplot_waffle as _aplot_waffle
-
-    return _aplot_waffle(*args, **kwargs)
-
-
-def fplot_waffle(*args: Any, **kwargs: Any) -> Figure:
-    from .waffle import fplot_waffle as _fplot_waffle
-
-    return _fplot_waffle(*args, **kwargs)
-
-
-def fplot_treemap(*args: Any, **kwargs: Any) -> go.Figure:
-    from .treemap import fplot_treemap as _fplot_treemap
-
-    return _fplot_treemap(*args, **kwargs)
-
-
-def fplot_sunburst(*args: Any, **kwargs: Any) -> go.Figure:
-    from .sunburst import fplot_sunburst as _fplot_sunburst
-
-    return _fplot_sunburst(*args, **kwargs)
-
-
-def plot_composite_bubble(*args: Any, **kwargs: Any) -> Figure:
-    from .composite import plot_composite_bubble as _plot_composite_bubble
-
-    return _plot_composite_bubble(*args, **kwargs)
-
-
-def plot_composite_treemap(*args: Any, **kwargs: Any) -> Optional[go.Figure]:
-    from .composite import plot_composite_treemap as _plot_composite_treemap
-
-    return _plot_composite_treemap(*args, **kwargs)
-
-
 @register_dataframe_accessor("mpl")
 class DataFrameAccessor:
     """Expose MatplotLibAPI plotting helpers as a pandas accessor.
@@ -490,7 +354,9 @@ class DataFrameAccessor:
         Axes
             The Matplotlib axes object with the histogram.
         """
-        return aplot_histogram(
+        from .histogram import aplot_histogram as _aplot_histogram
+
+        return _aplot_histogram(
             pd_df=self._obj,
             column=column,
             bins=bins,
@@ -531,7 +397,9 @@ class DataFrameAccessor:
         Figure
             The new Matplotlib figure with the histogram.
         """
-        return fplot_histogram(
+        from .histogram import fplot_histogram as _fplot_histogram
+
+        return _fplot_histogram(
             pd_df=self._obj,
             column=column,
             bins=bins,
@@ -844,7 +712,9 @@ class DataFrameAccessor:
         Axes
             The Matplotlib axes object with the pie or donut chart.
         """
-        return aplot_pie_donut(
+        from .pie import aplot_pie as _aplot_pie_donut
+
+        return _aplot_pie_donut(
             pd_df=self._obj,
             category=category,
             value=value,
@@ -885,7 +755,9 @@ class DataFrameAccessor:
         Figure
             The new Matplotlib figure with the pie or donut chart.
         """
-        return fplot_pie_donut(
+        from .pie import fplot_pie as _fplot_pie_donut
+
+        return _fplot_pie_donut(
             pd_df=self._obj,
             category=category,
             value=value,
@@ -926,7 +798,9 @@ class DataFrameAccessor:
         Axes
             The Matplotlib axes object with the waffle chart.
         """
-        return aplot_waffle(
+        from .waffle import aplot_waffle as _aplot_waffle
+
+        return _aplot_waffle(
             pd_df=self._obj,
             category=category,
             value=value,
@@ -967,7 +841,9 @@ class DataFrameAccessor:
         Figure
             The new Matplotlib figure with the waffle chart.
         """
-        return fplot_waffle(
+        from .waffle import fplot_waffle as _fplot_waffle
+
+        return _fplot_waffle(
             pd_df=self._obj,
             category=category,
             value=value,
@@ -1005,7 +881,7 @@ class DataFrameAccessor:
         go.Figure
             The Plotly Sankey figure.
         """
-        sankey_style_template, fplot_sankey = _sankey_imports()
+        from .sankey import SANKEY_STYLE_TEMPLATE, fplot_sankey
 
         return fplot_sankey(
             pd_df=self._obj,
@@ -1013,7 +889,7 @@ class DataFrameAccessor:
             target=target,
             value=value,
             title=title,
-            style=style or sankey_style_template,
+            style=style or SANKEY_STYLE_TEMPLATE,
         )
 
     def aplot_table(
@@ -1050,7 +926,9 @@ class DataFrameAccessor:
         Axes
             The Matplotlib axes object with the plot.
         """
-        return aplot_table(
+        from .table import aplot_table as _aplot_table
+
+        return _aplot_table(
             pd_df=self._obj,
             cols=cols,
             title=title,
@@ -1095,7 +973,9 @@ class DataFrameAccessor:
         Figure
             The new Matplotlib figure with the table.
         """
-        return fplot_table(
+        from .table import fplot_table as _fplot_table
+
+        return _fplot_table(
             pd_df=self._obj,
             cols=cols,
             title=title,
@@ -1149,7 +1029,9 @@ class DataFrameAccessor:
         Axes
             The Matplotlib axes object with the plot.
         """
-        return aplot_timeserie(
+        from .timeserie import aplot_timeserie as _aplot_timeserie
+
+        return _aplot_timeserie(
             pd_df=self._obj,
             label=label,
             x=x,
@@ -1206,7 +1088,9 @@ class DataFrameAccessor:
         Figure
             The new Matplotlib figure with the plot.
         """
-        return fplot_timeserie(
+        from .timeserie import fplot_timeserie as _fplot_timeserie
+
+        return _fplot_timeserie(
             pd_df=self._obj,
             label=label,
             x=x,
@@ -1257,14 +1141,14 @@ class DataFrameAccessor:
         Axes
             The Matplotlib axes object with the plot.
         """
-        wordcloud_style_template, aplot_wordcloud, _ = _wordcloud_imports()
+        from .word_cloud import WORDCLOUD_STYLE_TEMPLATE, aplot_wordcloud
 
         return aplot_wordcloud(
             pd_df=self._obj,
             text_column=text_column,
             weight_column=weight_column,
             title=title,
-            style=style or wordcloud_style_template,
+            style=style or WORDCLOUD_STYLE_TEMPLATE,
             max_words=max_words,
             stopwords=stopwords,
             random_state=random_state,
@@ -1308,14 +1192,14 @@ class DataFrameAccessor:
         Figure
             The new Matplotlib figure with the plot.
         """
-        wordcloud_style_template, _, fplot_wordcloud = _wordcloud_imports()
+        from .word_cloud import WORDCLOUD_STYLE_TEMPLATE, fplot_wordcloud
 
         return fplot_wordcloud(
             pd_df=self._obj,
             text_column=text_column,
             weight_column=weight_column,
             title=title,
-            style=style or wordcloud_style_template,
+            style=style or WORDCLOUD_STYLE_TEMPLATE,
             max_words=max_words,
             stopwords=stopwords,
             random_state=random_state,
@@ -1377,21 +1261,74 @@ class DataFrameAccessor:
         kwargs: Dict[str, Any] = {}
         if layout_seed is not None:
             kwargs["layout_seed"] = layout_seed
+        from .network import (
+            NETWORK_STYLE_TEMPLATE,
+            aplot_network_node as _aplot_network_node,
+        )
 
-        network_style_template, _, aplot_network_node, _, _, _, _ = _network_imports()
-
-        return aplot_network_node(
+        return _aplot_network_node(
             pd_df=self._obj,
             node=node,
             edge_source_col=edge_source_col,
             edge_target_col=edge_target_col,
             edge_weight_col=edge_weight_col,
             title=title,
-            style=style or network_style_template,
+            style=style or NETWORK_STYLE_TEMPLATE,
             ax=ax,
             **kwargs,
         )
 
+    def fplot_network(
+        self,
+        edge_source_col: str = "source",
+        edge_target_col: str = "target",
+        edge_weight_col: str = "weight",
+        title: Optional[str] = None,
+        style: Optional[StyleTemplate] = None,
+        layout_seed: Optional[int] = None,
+        figsize: Tuple[float, float] = FIG_SIZE,
+    ) -> Figure:
+        """Plot a network graph on a new figure.
+
+        Parameters
+        ----------
+        edge_source_col : str, optional
+            Column for source nodes. The default is "source".
+        edge_target_col : str, optional
+            Column for target nodes. The default is "target".
+        edge_weight_col : str, optional
+            Column for edge weights. The default is "weight".
+        title : str, optional
+            Chart title.
+        style : StyleTemplate, optional
+            Styling template. The default is `NETWORK_STYLE_TEMPLATE`.
+        layout_seed : int, optional
+            Seed forwarded to the spring layout. The default is ``_DEFAULT["SPRING_LAYOUT_SEED"]``.
+        figsize : tuple[float, float], optional
+            Figure size. The default is FIG_SIZE.
+
+        Returns
+        -------
+        Figure
+            The new Matplotlib figure with the plot.
+        """
+        kwargs: Dict[str, Any] = {}
+        if layout_seed is not None:
+            kwargs["layout_seed"] = layout_seed
+
+        from .network import NETWORK_STYLE_TEMPLATE, fplot_network
+
+        return fplot_network(
+            pd_df=self._obj,
+            edge_source_col=edge_source_col,
+            edge_target_col=edge_target_col,
+            edge_weight_col=edge_weight_col,
+            title=title,
+            style=style or NETWORK_STYLE_TEMPLATE,
+            figsize=figsize,
+            **kwargs,
+        )
+
     def aplot_network_components(
         self,
         edge_source_col: str = "source",
@@ -1437,9 +1374,7 @@ class DataFrameAccessor:
         if layout_seed is not None:
             kwargs["layout_seed"] = layout_seed
 
-        network_style_template, _, _, aplot_network_components, _, _, _ = (
-            _network_imports()
-        )
+        from .network import NETWORK_STYLE_TEMPLATE, aplot_network_components
 
         aplot_network_components(
             pd_df=self._obj,
@@ -1449,7 +1384,7 @@ class DataFrameAccessor:
             sort_by=sort_by,
             ascending=ascending,
             title=title,
-            style=style or network_style_template,
+            style=style or NETWORK_STYLE_TEMPLATE,
             axes=axes,
             **kwargs,
         )
@@ -1510,7 +1445,7 @@ class DataFrameAccessor:
         if layout_seed is not None:
             kwargs["layout_seed"] = layout_seed
 
-        network_style_template, _, _, _, _, fplot_network_node, _ = _network_imports()
+        from .network import NETWORK_STYLE_TEMPLATE, fplot_network_node
 
         return fplot_network_node(
             pd_df=self._obj,
@@ -1519,7 +1454,7 @@ class DataFrameAccessor:
             edge_target_col=edge_target_col,
             edge_weight_col=edge_weight_col,
             title=title,
-            style=style or network_style_template,
+            style=style or NETWORK_STYLE_TEMPLATE,
             figsize=figsize,
             **kwargs,
         )
@@ -1575,9 +1510,7 @@ class DataFrameAccessor:
         if layout_seed is not None:
             kwargs["layout_seed"] = layout_seed
 
-        network_style_template, _, _, _, _, _, fplot_network_components = (
-            _network_imports()
-        )
+        from .network import NETWORK_STYLE_TEMPLATE, fplot_network_components
 
         return fplot_network_components(
             pd_df=self._obj,
@@ -1585,7 +1518,7 @@ class DataFrameAccessor:
             edge_target_col=edge_target_col,
             edge_weight_col=edge_weight_col,
             title=title,
-            style=style or network_style_template,
+            style=style or NETWORK_STYLE_TEMPLATE,
             figsize=figsize,
             n_cols=n_cols,
             **kwargs,
@@ -1631,6 +1564,8 @@ class DataFrameAccessor:
         go.Figure
             The Plotly figure with the treemap.
         """
+        from .treemap import fplot_treemap
+
         return fplot_treemap(
             pd_df=self._obj,
             path=path,
@@ -1680,6 +1615,8 @@ class DataFrameAccessor:
         go.Figure
             The Plotly figure with the sunburst chart.
         """
+        from .sunburst import fplot_sunburst
+
         return fplot_sunburst(
             pd_df=self._obj,
             labels=labels,
@@ -1729,6 +1666,8 @@ class DataFrameAccessor:
         go.Figure, optional
             The Plotly figure with the composite treemap, or None if the input data is empty.
         """
+        from .composite import plot_composite_treemap
+
         pd_dfs: Dict[str, pd.DataFrame] = {}
         for path in paths:
             pd_dfs[path] = self._obj

{matplotlibapi-4.0.2 → matplotlibapi-4.0.4}/src/MatplotLibAPI/area.py

@@ -14,7 +14,6 @@ from .style_template import (
     string_formatter,
     validate_dataframe,
 )
-from .utils import _get_axis, _merge_kwargs, create_fig
 
 __all__ = ["AREA_STYLE_TEMPLATE", "aplot_area", "fplot_area"]
 
@@ -83,7 +82,7 @@ class AreaChart(BasePlot):
             "alpha": 0.7,
             "ax": plot_ax,
         }
-        pivot_df.plot(**_merge_kwargs(plot_kwargs, kwargs))
+        pivot_df.plot(**BasePlot.merge_kwargs(plot_kwargs, kwargs))
 
         legend = plot_ax.get_legend()
         if legend is not None:
@@ -101,7 +100,7 @@ class AreaChart(BasePlot):
             "color": style.font_color,
             "alpha": 0.4,
         }
-        merged_fill_between_kwargs = _merge_kwargs(fill_between_kwargs, kwargs)
+        merged_fill_between_kwargs = BasePlot.merge_kwargs(fill_between_kwargs, kwargs)
 
         plot_ax.fill_between(
             sorted_df[self.x],
@@ -137,7 +136,7 @@ class AreaChart(BasePlot):
         """
         if not style:
             style = AREA_STYLE_TEMPLATE
-        plot_ax = _get_axis(ax)
+        plot_ax = BasePlot.get_axis(ax)
         plot_ax.set_facecolor(style.background_color)
 
         if self.label: