gsplot 0.1.0__tar.gz → 0.1.2__tar.gz

{gsplot-0.1.0 → gsplot-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: gsplot
-Version: 0.1.0
+Version: 0.1.2
 Summary: General-scientific plot based on matplotlib
 Author: Giordano Mattoni
 Author-email: mattoni@scphys.kyoto-u.ac.jp
@@ -26,6 +26,7 @@ Description-Content-Type: text/markdown
 ![Using Poetry](https://img.shields.io/badge/Using-Poetry-blue)
 ![PyPI](https://img.shields.io/pypi/v/gsplot)
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/gsplot)
+[![PyPI Downloads](https://static.pepy.tech/badge/gsplot)](https://pepy.tech/projects/gsplot)
 ![Python](https://img.shields.io/badge/python-3.10%2B-blue)
 ![License: MIT](https://img.shields.io/badge/License-MIT-green)
 
@@ -37,21 +38,21 @@ Description-Content-Type: text/markdown
   <a href="#license" style="text-decoration: none;">License</a>
 </p>
 
-Welcome to **gsplot** (general-scientific plot), a toolkit designed to enhance the capabilities of data visualization based on [matplotlib](https://matplotlib.org). This package is specifically tailored for creating high-quality figures aimed at the scientific field.
+Welcome to **gsplot** (General-Scientific Plot), a toolkit designed to elevate capabilities of data visualization based on [matplotlib](https://matplotlib.org). This package is specifically tailored for creating high-quality figures aimed at the scientific field.
 
 > [!WARNING]
 > This package is _beta_ quality. Expect breaking changes and many bugs 🐛. Please report any issue you encounter 🤝.
 
 ## ✨ Features
 
-- **Better Plot, Less Code**: Simplify the process of creating high-quality figures ⚛️
-- **Compatibility**: Compatible with [matplotlib](https://matplotlib.org) 📊
-- **Customization**: Customize your configuration to fit your needs 🎨
-- **Reproducibility**: Save your package status to make plots reproducible 📦
+- **Better Plot, Less Effort**: Effortlessly create high-quality figures ⚛️
+- **Compatibility**: Fully compatible with [matplotlib](https://matplotlib.org) 📊
+- **Customization**: Tailor configurations to suit your needs 🎨
+- **Reproducibility**: Save package states for reproducible plots 📦
 
 ### 📈 Example using gsplot
 
-[See more details](https://soichiroyamane.github.io/gsplot/guides/stable/demo/4_paper_plot.html)
+[See more details](https://soichiroyamane.github.io/gsplot/stable/guides/demo/4_paper_plot.html)
 
 ![example](docs/_static/tutorial/SC_cal.png)
 
@@ -59,7 +60,7 @@ Welcome to **gsplot** (general-scientific plot), a toolkit designed to enhance t
 
 [See more details](https://soichiroyamane.github.io/gsplot/stable/guides/demo/13_REPL.html)
 
-![repl_tutorial](./docs/_static/tutorial/repl_tutorial_sp.gif)
+![repl_tutorial](./docs/_static/tutorial/repl_tutorial_45fps.gif)
 
 ## 🚀 Getting Started
 

{gsplot-0.1.0 → gsplot-0.1.2}/README.md

@@ -6,6 +6,7 @@
 ![Using Poetry](https://img.shields.io/badge/Using-Poetry-blue)
 ![PyPI](https://img.shields.io/pypi/v/gsplot)
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/gsplot)
+[![PyPI Downloads](https://static.pepy.tech/badge/gsplot)](https://pepy.tech/projects/gsplot)
 ![Python](https://img.shields.io/badge/python-3.10%2B-blue)
 ![License: MIT](https://img.shields.io/badge/License-MIT-green)
 
@@ -17,21 +18,21 @@
   <a href="#license" style="text-decoration: none;">License</a>
 </p>
 
-Welcome to **gsplot** (general-scientific plot), a toolkit designed to enhance the capabilities of data visualization based on [matplotlib](https://matplotlib.org). This package is specifically tailored for creating high-quality figures aimed at the scientific field.
+Welcome to **gsplot** (General-Scientific Plot), a toolkit designed to elevate capabilities of data visualization based on [matplotlib](https://matplotlib.org). This package is specifically tailored for creating high-quality figures aimed at the scientific field.
 
 > [!WARNING]
 > This package is _beta_ quality. Expect breaking changes and many bugs 🐛. Please report any issue you encounter 🤝.
 
 ## ✨ Features
 
-- **Better Plot, Less Code**: Simplify the process of creating high-quality figures ⚛️
-- **Compatibility**: Compatible with [matplotlib](https://matplotlib.org) 📊
-- **Customization**: Customize your configuration to fit your needs 🎨
-- **Reproducibility**: Save your package status to make plots reproducible 📦
+- **Better Plot, Less Effort**: Effortlessly create high-quality figures ⚛️
+- **Compatibility**: Fully compatible with [matplotlib](https://matplotlib.org) 📊
+- **Customization**: Tailor configurations to suit your needs 🎨
+- **Reproducibility**: Save package states for reproducible plots 📦
 
 ### 📈 Example using gsplot
 
-[See more details](https://soichiroyamane.github.io/gsplot/guides/stable/demo/4_paper_plot.html)
+[See more details](https://soichiroyamane.github.io/gsplot/stable/guides/demo/4_paper_plot.html)
 
 ![example](docs/_static/tutorial/SC_cal.png)
 
@@ -39,7 +40,7 @@ Welcome to **gsplot** (general-scientific plot), a toolkit designed to enhance t
 
 [See more details](https://soichiroyamane.github.io/gsplot/stable/guides/demo/13_REPL.html)
 
-![repl_tutorial](./docs/_static/tutorial/repl_tutorial_sp.gif)
+![repl_tutorial](./docs/_static/tutorial/repl_tutorial_45fps.gif)
 
 ## 🚀 Getting Started
 

{gsplot-0.1.0 → gsplot-0.1.2}/gsplot/__init__.py

@@ -3,6 +3,7 @@ from .config.config import (Config, config_dict, config_entry_option,
                             config_load, save_metadata)
 from .data.load_file import load_file
 from .figure.axes import axes
+from .figure.axes_inset import axes_inset, axes_inset_padding
 from .figure.figure_tools import get_figure_size
 from .figure.show import show
 from .hello_world.hello_world import hello_world
@@ -49,6 +50,9 @@ __all__ = [
     "load_file",
     # figure/axes.py
     "axes",
+    # figure/axes_inset.py
+    "axes_inset",
+    "axes_inset_padding",
     # figure/figure_tools.py
     "get_figure_size",
     # figure/show.py

gsplot-0.1.2/gsplot/figure/axes_inset.py

@@ -0,0 +1,708 @@
+from typing import Any, cast
+
+from matplotlib.axes import Axes
+from matplotlib.transforms import BboxBase, Transform, TransformedBbox
+from matplotlib.typing import ColorType
+from mpl_toolkits.axes_grid1.inset_locator import (BboxConnector, BboxPatch,
+                                                   inset_axes)
+
+from ..base.base import CreateClassParams, ParamsGetter, bind_passed_params
+from ..style.label import Label
+from ..style.ticks import MinorTicks
+
+__all__ = ["axes_inset", "axes_inset_padding"]
+
+
+class InsetAxesBase:
+    """
+    A utility class for managing inset axes in a Matplotlib figure.
+
+    This class provides functionality for configuring and customizing inset axes,
+    including zooming, labeling, and enabling minor ticks. It also allows for manual
+    control of zoom connectors and axis limits.
+
+    Parameters
+    --------------------
+    ax : Axes
+        The main axis in the figure.
+    axins : Axes
+        The inset axis in the figure.
+    lab_lims : list[Any] | None, optional
+        List specifying axis labels and limits for the inset axis.
+        Expected format: [x_label, y_label, x_lim_min, x_lim_max, y_lim_min, y_lim_max].
+    minor_ticks : bool, default=True
+        Whether to enable minor ticks on the inset axis.
+    zoom : bool or tuple[tuple[int, int], tuple[int, int]], default=True
+        Zoom settings for the inset axis.
+        - If True, uses the built-in zoom indication.
+        - If a tuple, manually connects the axes with zoom connectors.
+    zoom_color : ColorType, default='black'
+        Color for the zoom connectors and patches.
+    zoom_alpha : int | float, default=0.3
+        Transparency for the zoom connectors and patches.
+    **kwargs : Any
+        Additional keyword arguments for axis label configuration.
+
+    Notes
+    --------------------
+    This class is designed for cases where inset axes are needed for enhanced
+    visualization. It uses helper classes like `Label` and `MinorTicks` to
+    streamline customization.
+
+    Methods
+    --------------------
+    manual_inset_zoom():
+        Manually connect the main axis to the inset axis with zoom connectors.
+
+    indicate_inset_zoom():
+        Use the built-in Matplotlib method to indicate zoom on the inset axis.
+
+    inset_zoom():
+        Automatically apply zoom connectors based on the `zoom` attribute.
+
+    set_minor_ticks():
+        Enable minor ticks on the inset axis.
+
+    label():
+        Configure and set labels and axis limits for the inset axis.
+
+    Warnings
+    --------------------
+    - Ensure that `lab_lims` is provided and correctly formatted when calling `label()`.
+    - `zoom` should be a tuple of tuples when using `manual_inset_zoom()`.
+
+    Examples
+    --------------------
+    >>> import matplotlib.pyplot as plt
+    >>> fig, ax = plt.subplots()
+    >>> axins = ax.inset_axes([0.5, 0.5, 0.4, 0.4])
+    >>> inset = InsetAxesBase(
+    ...     ax,
+    ...     axins,
+    ...     lab_lims=["X Label", "Y Label", 0, 1, 0, 1],
+    ...     zoom=((1, 2), (3, 4)),
+    ... )
+    >>> inset.set_minor_ticks()
+    >>> inset.label()
+    >>> inset.inset_zoom()
+    >>> plt.show()
+    """
+
+    def __init__(
+        self,
+        ax,
+        axins,
+        lab_lims: list[Any] | None = None,
+        minor_ticks: bool = True,
+        zoom: bool | tuple[tuple[int, int], tuple[int, int]] = True,
+        zoom_color: ColorType = "black",
+        zoom_alpha: int | float = 0.3,
+        **kwargs,
+    ) -> None:
+        self.ax: Axes = ax
+        self.axins: Axes = axins
+        self.lab_lims: list[Any] | None = lab_lims
+        self.minor_ticks: bool = minor_ticks
+        self.zoom: bool | tuple[tuple[int, int], tuple[int, int]] = zoom
+        self.zoom_color: ColorType = zoom_color
+        self.zoom_alpha: int | float = zoom_alpha
+        self.kwargs: Any = kwargs
+
+    def manual_inset_zoom(self):
+        """
+        Manually connect the main axis to the inset axis with zoom connectors.
+
+        This method adds connectors and a patch between the main and inset axes
+        to visually represent the zoomed-in region.
+
+        Raises:
+            ValueError: If `zoom` is not a tuple of tuples.
+
+        Notes
+        --------------------
+        This method is used when manual control over zoom connectors is required.
+        """
+        if isinstance(self.zoom, bool):
+            raise ValueError("locs_zoom must be a tuple of tuples")
+
+        loc1a, loc1b = self.zoom[0]
+        loc2a, loc2b = self.zoom[1]
+        rect = TransformedBbox(self.axins.viewLim, self.ax.transData)
+        pp = BboxPatch(
+            rect, fill=False, edgecolor=self.zoom_color, alpha=self.zoom_alpha
+        )
+        self.ax.add_patch(pp)
+        p1 = BboxConnector(
+            self.axins.bbox,
+            rect,
+            loc1=loc1b,
+            loc2=loc1a,
+            color=self.zoom_color,
+            alpha=self.zoom_alpha,
+        )
+        self.axins.add_patch(p1)
+        p1.set_clip_on(False)
+        p2 = BboxConnector(
+            self.axins.bbox,
+            rect,
+            loc1=loc2b,
+            loc2=loc2a,
+            color=self.zoom_color,
+            alpha=self.zoom_alpha,
+        )
+        self.axins.add_patch(p2)
+        p2.set_clip_on(False)
+
+    def indicate_inset_zoom(self):
+        """
+        Use Matplotlib's built-in method to indicate zoom on the inset axis.
+
+        This method creates a zoom indication using a rectangular outline between
+        the main and inset axes.
+
+        Notes
+        --------------------
+        This method is simpler and faster than `manual_inset_zoom` but offers
+        less customization.
+        """
+        self.ax.indicate_inset_zoom(
+            self.axins, edgecolor=self.zoom_color, alpha=self.zoom_alpha
+        )
+
+    def inset_zoom(self):
+        """
+        Apply zoom connectors to the inset axis based on the `zoom` attribute.
+
+        If `zoom` is True, the built-in zoom indication method is used.
+        If `zoom` is a tuple, manual zoom connectors are created using `manual_inset_zoom`.
+
+        Notes
+        --------------------
+        This method provides a unified interface for adding zoom connectors.
+        """
+        if self.zoom is True:
+            self.indicate_inset_zoom()
+        elif isinstance(self.zoom, tuple):
+            self.manual_inset_zoom()
+
+    def set_minor_ticks(self):
+        """
+        Enable minor ticks on the inset axis.
+
+        This method configures and displays minor ticks on both x and y axes
+        of the inset axis.
+
+        Notes
+        --------------------
+        Minor ticks enhance the readability of the inset axis.
+        """
+        _minor_ticks = MinorTicks(self.axins)
+        _minor_ticks.set_minor_ticks_on(mode="xy")
+
+    def label(
+        self,
+    ):
+        """
+        Configure labels and axis limits for the inset axis.
+
+        This method sets the x and y axis labels and applies the specified
+        axis limits to the inset axis.
+
+        Raises:
+            ValueError: If `lab_lims` is not provided or has an invalid shape.
+
+        Notes
+        --------------------
+        This method utilizes the `Label` class to simplify axis labeling and limit configuration.
+
+        Examples
+        --------------------
+        >>> inset = InsetAxesBase(ax, axins, lab_lims=["X", "Y", 0, 1, 0, 1])
+        >>> inset.label()
+        """
+        if not self.lab_lims:
+            raise ValueError("lab_lims must be provided")
+
+        _label = Label(
+            self.lab_lims,
+            minor_ticks_axes=False,
+            tight_layout=False,
+            **self.kwargs,
+        )
+
+        try:
+            x_lab, y_lab, *lims = self.lab_lims
+        except ValueError:
+            raise ValueError("lab_lims has invalid shape")
+
+        # Label the inset axes
+        _label.configure_axis_labels(self.axins, x_lab, y_lab, **self.kwargs)
+        # Set the axis limits
+        _label.configure_axis_limits(self.axins, lims)
+
+
+class AxesInset:
+    """
+    A class to create and manage inset axes in a Matplotlib figure.
+
+    This class simplifies the creation of inset axes, providing options for zooming,
+    labeling, minor ticks, and custom axis transformations.
+
+    Parameters
+    --------------------
+    ax : Axes
+        The main axis in the figure.
+    bounds : tuple[float, float, float, float]
+        Bounds for the inset axis in the format (x0, y0, width, height).
+    transform : Transform | None, optional
+        The transform to apply to the inset axis. Default is None.
+    projection : str | None, optional
+        The projection type for the inset axis. Default is None.
+    polar : bool, default=False
+        If True, the inset axis will use a polar projection.
+    lab_lims : list[Any] | None, optional
+        List specifying axis labels and limits for the inset axis.
+        Expected format: [x_label, y_label, x_lim_min, x_lim_max, y_lim_min, y_lim_max].
+    minor_ticks : bool, default=True
+        Whether to enable minor ticks on the inset axis.
+    zoom : bool or tuple[tuple[int, int], tuple[int, int]], default=True
+        Zoom settings for the inset axis.
+        - If True, uses the built-in zoom indication.
+        - If a tuple, manually connects the axes with zoom connectors.
+    zoom_color : ColorType, default='black'
+        Color for the zoom connectors and patches.
+    zoom_alpha : int | float, default=0.3
+        Transparency for the zoom connectors and patches.
+    zorder : int | float, default=5
+        The z-order of the inset axis.
+    **kwargs : Any
+        Additional keyword arguments for label configuration or other customizations.
+
+    Methods
+    --------------------
+    axes_inset() -> Axes:
+        Creates and configures the inset axis, applying zoom, labels, and minor ticks.
+
+    Examples
+    --------------------
+    >>> import matplotlib.pyplot as plt
+    >>> fig, ax = plt.subplots()
+    >>> bounds = [0.5, 0.5, 0.4, 0.4]
+    >>> axins = AxesInset(ax, bounds, lab_lims=["X", "Y", 0, 1, 0, 1]).axes_inset()
+    >>> plt.show()
+    """
+
+    def __init__(
+        self,
+        ax: Axes,
+        bounds: tuple[float, float, float, float],
+        transform: Transform | None = None,
+        projection: str | None = None,
+        polar: bool = False,
+        lab_lims: list[Any] | None = None,
+        minor_ticks: bool = True,
+        zoom: bool | tuple[tuple[int, int], tuple[int, int]] = True,
+        zoom_color: ColorType = "black",
+        zoom_alpha: int | float = 0.3,
+        zorder: int | float = 5,
+        **kwargs: Any,
+    ) -> None:
+        self.ax: Axes = ax
+        self.bounds: tuple[float, float, float, float] = bounds
+        self.transform: Transform | None = transform
+        self.projection: str | None = projection
+        self.polar: bool = polar
+
+        self.lab_lims: list[Any] | None = lab_lims
+        self.minor_ticks: bool = minor_ticks
+        self.zoom: bool | tuple[tuple[int, int], tuple[int, int]] = zoom
+        self.zoom_color: ColorType = zoom_color
+        self.zoom_alpha: int | float = zoom_alpha
+        self.zorder: int | float = zorder
+        self.kwargs: Any = kwargs
+
+    def axes_inset(self) -> Axes:
+        """
+        Create and configure the inset axis.
+
+        This method creates an inset axis using the specified bounds and properties,
+        applies zoom connectors if specified, adds axis labels and limits, and enables
+        minor ticks.
+
+        Returns
+        --------------------
+        axins : Axes
+            The created inset axis.
+
+        Notes
+        --------------------
+        - If `lab_lims` is provided, the inset axis will be labeled and have custom limits.
+        - If `zoom` is specified, zoom connectors will be added between the main and inset axes.
+
+        Examples
+        --------------------
+        >>> axins = AxesInset(ax, bounds).axes_inset()
+        >>> axins.plot([0, 1], [0, 1])
+        """
+        axins = self.ax.inset_axes(
+            bounds=self.bounds,
+            transform=self.transform,
+            projection=self.projection,
+            polar=self.polar,
+            zorder=self.zorder,
+        )
+        self._axes_inset_base = InsetAxesBase(
+            ax=self.ax,
+            axins=axins,
+            minor_ticks=self.minor_ticks,
+            zoom=self.zoom,
+            zoom_color=self.zoom_color,
+            zoom_alpha=self.zoom_alpha,
+            lab_lims=self.lab_lims,
+            **self.kwargs,
+        )
+
+        if self.lab_lims:
+            self._axes_inset_base.label()
+        if self.zoom:
+            self._axes_inset_base.inset_zoom()
+        self._axes_inset_base.set_minor_ticks()
+        return axins
+
+
+@bind_passed_params()
+def axes_inset(
+    ax: Axes,
+    bounds: tuple[float, float, float, float],
+    transform: Transform | None = None,
+    projection: str | None = None,
+    polar: bool = False,
+    lab_lims: list[Any] | None = None,
+    minor_ticks: bool = True,
+    zoom: bool | tuple[tuple[int, int], tuple[int, int]] = True,
+    zoom_color: ColorType = "black",
+    zoom_alpha: int | float = 0.3,
+    zorder: int | float = 5,
+    **kwargs: Any,
+) -> Axes:
+    """
+    A functional interface to create an inset axis in a Matplotlib figure.
+
+    This function wraps the `AxesInset` class, allowing inset axes to be created
+    with a simpler function-based interface.
+
+    Parameters
+    --------------------
+    ax : Axes
+        The main axis in the figure.
+    bounds : tuple[float, float, float, float]
+        Bounds for the inset axis in the format (x0, y0, width, height).
+    transform : Transform | None, optional
+        The transform to apply to the inset axis. Default is None.
+    projection : str | None, optional
+        The projection type for the inset axis. Default is None.
+    polar : bool, default=False
+        If True, the inset axis will use a polar projection.
+    lab_lims : list[Any] | None, optional
+        Axis labels and limits for the inset axis.
+    minor_ticks : bool, default=True
+        Whether to enable minor ticks on the inset axis.
+    zoom : bool or tuple[tuple[int, int], tuple[int, int]], default=True
+        Zoom settings for the inset axis.
+    zoom_color : ColorType, default='black'
+        Color for the zoom connectors and patches.
+    zoom_alpha : int | float, default=0.3
+        Transparency for the zoom connectors and patches.
+    zorder : int | float, default=5
+        The z-order of the inset axis.
+    **kwargs : Any
+        Additional keyword arguments for label configuration or other customizations.
+
+    Returns
+    --------------------
+    axins : Axes
+        The created inset axis.
+
+    Notes
+    --------------------
+    zoom provides manual inset zooming when a tuple is provided.
+    zoom = ((1, 2), (3, 4)) will connect the main axis to the inset axis as follows:
+
+    - 1 (main) - 2 (inset)
+    - 3 (main) - 3 (inset)
+
+    The indices represent the corners of the axes, with 1 being the bottom left corner
+
+    Examples
+    --------------------
+    >>> import matplotlib.pyplot as plt
+    >>> fig, ax = plt.subplots()
+    >>> axins = axes_inset(ax, [0.5, 0.5, 0.4, 0.4], lab_lims=["X", "Y", 0, 1, 0, 1])
+    >>> axins.plot([0, 1], [0, 1])
+    """
+
+    passed_params: dict[str, Any] = ParamsGetter("passed_params").get_bound_params()
+    class_params = CreateClassParams(passed_params).get_class_params()
+
+    _axes_inset = AxesInset(
+        class_params["ax"],
+        class_params["bounds"],
+        class_params["transform"],
+        class_params["projection"],
+        class_params["polar"],
+        class_params["lab_lims"],
+        class_params["minor_ticks"],
+        class_params["zoom"],
+        class_params["zoom_color"],
+        class_params["zoom_alpha"],
+        class_params["zorder"],
+        **class_params["kwargs"],
+    )
+    axins = _axes_inset.axes_inset()
+    return axins
+
+
+class AxesInsetPadding:
+    """
+    A class to create and manage inset axes with padding in a Matplotlib figure.
+
+    This class facilitates the creation of inset axes with precise control over
+    size, location, and additional padding. It also supports zooming, labeling,
+    and minor tick customization.
+
+    Parameters
+    --------------------
+    ax : Axes
+        The parent axis where the inset axis will be placed.
+    width : str or float
+        The width of the inset axis. Can be a float (absolute size) or a string
+        (e.g., "30%" relative to the parent axis).
+    height : str or float
+        The height of the inset axis. Can be a float (absolute size) or a string
+        (e.g., "30%" relative to the parent axis).
+    loc : str, default="upper right"
+        The location of the inset axis relative to the parent axis. Accepted values are:
+        "upper right", "upper left", "lower left", "lower right", etc.
+    borderpad : float, default=0.5
+        Padding between the parent axis and the inset axis.
+    bbox_to_anchor : tuple[float, float] | BboxBase | None, optional
+        The bounding box to anchor the inset axis.
+    bbox_transform : Transform | None, optional
+        Transformation for the bounding box anchor.
+    axes_kwargs : dict[str, Any] | None, optional
+        Additional keyword arguments to pass to the inset axis creation.
+    lab_lims : list[Any] | None, optional
+        Axis labels and limits for the inset axis.
+        Expected format: [x_label, y_label, x_lim_min, x_lim_max, y_lim_min, y_lim_max].
+    minor_ticks : bool, default=True
+        Whether to enable minor ticks on the inset axis.
+    zoom : bool or tuple[tuple[int, int], tuple[int, int]], default=True
+        Zoom settings for the inset axis.
+        - If True, uses the built-in zoom indication.
+        - If a tuple, manually connects the axes with zoom connectors.
+    zoom_color : ColorType, default="black"
+        Color for the zoom connectors and patches.
+    zoom_alpha : int | float, default=0.3
+        Transparency for the zoom connectors and patches.
+    **kwargs : Any
+        Additional keyword arguments for label configuration or other customizations.
+
+    Methods
+    --------------------
+    axes_inset() -> Axes:
+        Creates and configures the inset axis with the specified parameters.
+
+    Examples
+    --------------------
+    >>> import matplotlib.pyplot as plt
+    >>> from mpl_toolkits.axes_grid1.inset_locator import inset_axes
+    >>> fig, ax = plt.subplots()
+    >>> axins = AxesInsetPadding(ax, width="30%", height="30%", loc="upper right").axes_inset()
+    >>> axins.plot([0, 1], [0, 1])
+    >>> plt.show()
+    """
+
+    def __init__(
+        self,
+        ax: Axes,
+        width: str | float,
+        height: str | float,
+        loc: str = "upper right",
+        borderpad: float = 0.5,
+        bbox_to_anchor: tuple[float, float] | BboxBase | None = None,
+        bbox_transform: Transform | None = None,
+        axes_kwargs: dict[str, Any] | None = None,
+        lab_lims: list[Any] | None = None,
+        minor_ticks: bool = True,
+        zoom: bool | tuple[tuple[int, int], tuple[int, int]] = True,
+        zoom_color: ColorType = "black",
+        zoom_alpha: int | float = 0.3,
+        **kwargs: Any,
+    ) -> None:
+        self.ax: Axes = ax
+        self.width: str | float = width
+        self.height: str | float = height
+        self.loc: str = loc
+        self.borderpad: float = borderpad
+        self.bbox_to_anchor: tuple[float, float] | BboxBase | None = bbox_to_anchor
+        self.bbox_transform: Transform | None = bbox_transform
+        self.axes_kwargs: dict[str, Any] | None = axes_kwargs
+
+        self.lab_lims: list[Any] | None = lab_lims
+        self.minor_ticks: bool = minor_ticks
+        self.zoom: bool | tuple[tuple[int, int], tuple[int, int]] = zoom
+        self.zoom_color: ColorType = zoom_color
+        self.zoom_alpha: int | float = zoom_alpha
+        self.kwargs: Any = kwargs
+
+    def axes_inset(self) -> Axes:
+        """
+        Create and configure an inset axis with padding.
+
+        This method uses `inset_axes` to create an inset axis with the specified
+        width, height, and padding. It applies zoom connectors, labels, and minor
+        ticks if specified.
+
+        Returns
+        --------------------
+        axins : Axes
+            The created inset axis.
+
+        Notes
+        --------------------
+        - If `lab_lims` is provided, the inset axis will be labeled and have custom limits.
+        - If `zoom` is specified, zoom connectors will be added between the main and inset axes.
+
+        Examples
+        --------------------
+        >>> axins = AxesInsetPadding(ax, "30%", "30%", loc="upper right").axes_inset()
+        >>> axins.plot([0, 1], [0, 1])
+        """
+        axins = inset_axes(
+            parent_axes=self.ax,
+            width=self.width,
+            height=self.height,
+            loc=self.loc,
+            borderpad=self.borderpad,
+            bbox_to_anchor=self.bbox_to_anchor,
+            bbox_transform=self.bbox_transform,
+            axes_kwargs=self.axes_kwargs,
+        )
+        self._axes_inset_base = InsetAxesBase(
+            ax=self.ax,
+            axins=axins,
+            minor_ticks=self.minor_ticks,
+            zoom=self.zoom,
+            zoom_color=self.zoom_color,
+            zoom_alpha=self.zoom_alpha,
+            lab_lims=self.lab_lims,
+            **self.kwargs,
+        )
+
+        if self.lab_lims:
+            self._axes_inset_base.label()
+        if self.zoom:
+            self._axes_inset_base.inset_zoom()
+        self._axes_inset_base.set_minor_ticks()
+        return cast(Axes, axins)
+
+
+@bind_passed_params()
+def axes_inset_padding(
+    ax: Axes,
+    width: str | float,
+    height: str | float,
+    loc: str = "upper right",
+    borderpad: float = 0.5,
+    bbox_to_anchor: tuple[float, float] | BboxBase | None = None,
+    bbox_transform: Transform | None = None,
+    axes_kwargs: dict[str, Any] | None = None,
+    lab_lims: list[Any] | None = None,
+    minor_ticks: bool = True,
+    zoom: bool | tuple[tuple[int, int], tuple[int, int]] = True,
+    zoom_color: ColorType = "black",
+    zoom_alpha: int | float = 0.3,
+    **kwargs: Any,
+) -> Axes:
+    """
+    A functional interface to create an inset axis with padding in a Matplotlib figure.
+
+    This function wraps the `AxesInsetPadding` class, allowing inset axes to be created
+    with a simpler function-based interface.
+
+    Parameters
+    --------------------
+    ax : Axes
+        The parent axis where the inset axis will be placed.
+    width : str or float
+        The width of the inset axis.
+    height : str or float
+        The height of the inset axis.
+    loc : str, default="upper right"
+        The location of the inset axis relative to the parent axis.
+    borderpad : float, default=0.5
+        Padding between the parent axis and the inset axis.
+    bbox_to_anchor : tuple[float, float] | BboxBase | None, optional
+        Bounding box to anchor the inset axis.
+    bbox_transform : Transform | None, optional
+        Transformation for the bounding box anchor.
+    axes_kwargs : dict[str, Any] | None, optional
+        Additional keyword arguments for the inset axis creation.
+    lab_lims : list[Any] | None, optional
+        Axis labels and limits for the inset axis.
+    minor_ticks : bool, default=True
+        Whether to enable minor ticks on the inset axis.
+    zoom : bool or tuple[tuple[int, int], tuple[int, int]], default=True
+        Zoom settings for the inset axis.
+    zoom_color : ColorType, default="black"
+        Color for the zoom connectors and patches.
+    zoom_alpha : int | float, default=0.3
+        Transparency for the zoom connectors and patches.
+    **kwargs : Any
+        Additional keyword arguments for label configuration or other customizations.
+
+    Returns
+    --------------------
+    axins : Axes
+        The created inset axis.
+
+
+    Notes
+    --------------------
+    zoom provides manual inset zooming when a tuple is provided.
+    zoom = ((1, 2), (3, 4)) will connect the main axis to the inset axis as follows:
+
+    - 1 (main) - 2 (inset)
+    - 3 (main) - 3 (inset)
+
+    The indices represent the corners of the axes, with 1 being the bottom left corner
+
+    Examples
+    --------------------
+    >>> import matplotlib.pyplot as plt
+    >>> fig, ax = plt.subplots()
+    >>> axins = axes_inset_padding(ax, "30%", "30%", loc="upper right", zoom=False)
+    >>> axins.plot([0, 1], [0, 1])
+    """
+
+    passed_params: dict[str, Any] = ParamsGetter("passed_params").get_bound_params()
+    class_params = CreateClassParams(passed_params).get_class_params()
+
+    _axes_inset_padding = AxesInsetPadding(
+        class_params["ax"],
+        class_params["width"],
+        class_params["height"],
+        class_params["loc"],
+        class_params["borderpad"],
+        class_params["bbox_to_anchor"],
+        class_params["bbox_transform"],
+        class_params["axes_kwargs"],
+        class_params["lab_lims"],
+        class_params["minor_ticks"],
+        class_params["zoom"],
+        class_params["zoom_color"],
+        class_params["zoom_alpha"],
+        **class_params["kwargs"],
+    )
+    axins = _axes_inset_padding.axes_inset()
+    return axins

{gsplot-0.1.0 → gsplot-0.1.2}/gsplot/style/label.py

@@ -452,31 +452,39 @@ class Label:
     lab_lims : list[Any]
         A list specifying labels and limits for each axis in the figure. Each entry
         should be a tuple of the form `(x_label, y_label, x_limits, y_limits)`.
-    x_pad : int, default=2
-        Horizontal padding for tight layout.
-    y_pad : int, default=2
-        Vertical padding for tight layout.
+    xpad_label : int or float, default=5
+        Padding for the x-axis label.
+    ypad_label : int or float, default=5
+        Padding for the y-axis label.
     minor_ticks_axes : bool, default=True
         Whether to add minor ticks to all axes.
     tight_layout : bool, default=True
         Whether to apply `tight_layout` to the figure.
+    xpad_layout : int, default=2
+        Horizontal padding for tight layout.
+    ypad_layout : int, default=2
+        Vertical padding for tight layout.
     *args : Any
-        Additional arguments for `plt.tight_layout`.
+        Additional arguments for `ax.set_xlabel` and `ax.set_ylabel.
     **kwargs : Any
-        Additional keyword arguments for `plt.tight_layout`.
+        Additional keyword arguments for `ax.set_xlabel` and `ax.set_ylabel`.
 
     Attributes
     --------------------
     lab_lims : list[Any]
         The labels and limits configuration for the axes.
-    x_pad : int
-        Horizontal padding for tight layout.
-    y_pad : int
-        Vertical padding for tight layout.
+    xpad_label : int or float
+        Padding for the x-axis label.
+    ypad_label : int or float
+        Padding for the y-axis label.
     minor_ticks_axes : bool
         Whether minor ticks are enabled for axes.
     tight_layout : bool
         Whether `tight_layout` is applied.
+    xpad_layout : int
+        Horizontal padding for tight layout.
+    ypad_layout : int
+        Vertical padding for tight layout.
     _axes : list[Axes]
         List of axes in the current figure.
 
@@ -507,20 +515,22 @@ class Label:
     def __init__(
         self,
         lab_lims: list[Any],
-        x_pad: int = 2,
-        y_pad: int = 2,
+        xpad_label: int | float = 2,
+        ypad_label: int | float = 2,
         minor_ticks_axes: bool = True,
         tight_layout: bool = True,
-        *args: Any,
+        xpad_layout: int | float = 2,
+        ypad_layout: int | float = 2,
         **kwargs: Any,
     ) -> None:
 
         self.lab_lims: list[Any] = lab_lims
-        self.x_pad: int = x_pad
-        self.y_pad: int = y_pad
+        self.xpad_label: int | float = xpad_label
+        self.ypad_label: int | float = ypad_label
         self.minor_ticks_axes: bool = minor_ticks_axes
         self.tight_layout: bool = tight_layout
-        self.args: Any = args
+        self.xpad_layout: int | float = xpad_layout
+        self.ypad_layout: int | float = ypad_layout
         self.kwargs: Any = kwargs
 
         self._axes: list[Axes] = plt.gcf().axes
@@ -621,7 +631,15 @@ class Label:
         if self.minor_ticks_axes:
             MinorTicksAxes().set_minor_ticks_axes()
 
-    def configure_axis_labels(self, ax: Axes, x_lab: str | None, y_lab: str | None):
+    def configure_axis_labels(
+        self,
+        ax: Axes,
+        x_lab: str | None,
+        y_lab: str | None,
+        xpad_label: int | float = 10,
+        ypad_label: int | float = 10,
+        **kwargs: Any,
+    ) -> None:
         """
         Configures the labels for a given axis.
 
@@ -633,20 +651,31 @@ class Label:
             The label for the x-axis. If `None`, the x-axis label is removed.
         y_lab : str, optional
             The label for the y-axis. If `None`, the y-axis label is removed.
+        xpad_label : int or float, default=5
+            Padding for the x-axis label.
+        ypad_label : int or float, default=5
+            Padding for the y-axis label.
+        **kwargs : Any
+            Additional keyword arguments for the labels.
 
         Returns
         --------------------
         None
         """
-        if x_lab:
-            ax.set_xlabel(x_lab)
-        else:
-            self.remove_xlabels(ax)
 
-        if y_lab:
-            ax.set_ylabel(y_lab)
+        if isinstance(x_lab, str):
+            ax.set_xlabel(xlabel=x_lab, labelpad=xpad_label, **kwargs)
+        elif x_lab is None:
+            self.remove_xlabels(ax)
         else:
+            raise ValueError("Invalid x-axis label. Must be a string or None.")
+
+        if isinstance(y_lab, str):
+            ax.set_ylabel(ylabel=y_lab, labelpad=ypad_label, **kwargs)
+        elif y_lab is None:
             self.remove_ylabels(ax)
+        else:
+            raise ValueError("Invalid y-axis label. Must be a string or None.")
 
     def configure_axis_limits(
         self,
@@ -672,6 +701,7 @@ class Label:
         --------------------
         None
         """
+
         if lims:
             x_lims, y_lims = lims
 
@@ -710,18 +740,40 @@ class Label:
             )
 
     def set_labels(self):
+        """
+        Applies labels, limits, and scales to all axes based on the configuration.
+
+        Returns
+        --------------------
+        None
+
+        """
         final_axes_ranges = self._get_final_axes_ranges()
 
         for i, (x_lab, y_lab, *lims) in enumerate(self.lab_lims):
             ax = self._axes[i]
 
             # Configure axis labels
-            self.configure_axis_labels(ax, x_lab, y_lab)
+            self.configure_axis_labels(
+                ax, x_lab, y_lab, self.xpad_label, self.ypad_label, **self.kwargs
+            )
 
             # Configure axis limits and scales
             self.configure_axis_limits(ax, lims, final_axes_ranges)
 
     def _calculate_padding_range(self, range: NDArray[Any]) -> NDArray[Any]:
+        """
+        Calculates the padding range for a given axis.
+
+        Parameters
+        --------------------
+        range : numpy.ndarray
+            The range of values for the axis.
+
+        Returns
+        --------------------
+        numpy.ndarray
+        """
 
         PADDING_FACTOR: float = 0.05
         span: float = range[1] - range[0]
@@ -732,11 +784,32 @@ class Label:
     def _get_wider_range(
         self, range1: NDArray[Any], range2: NDArray[Any]
     ) -> NDArray[Any]:
+        """
+        Calculates the wider range between two ranges.
+
+        Parameters
+        --------------------
+        range1 : numpy.ndarray
+            The first range of values.
+        range2 : numpy.ndarray
+            The second range of values.
+
+        Returns
+        --------------------
+        numpy.ndarray
+        """
 
         new_range = np.array([min(range1[0], range2[0]), max(range1[1], range2[1])])
         return new_range
 
     def _get_axes_ranges_current(self) -> list[list[NDArray[Any]]]:
+        """
+        Retrieves the current ranges for all axes.
+
+        Returns
+        --------------------
+        list[list[numpy.ndarray]]
+        """
 
         axes_ranges_current = []
         for ax in self._axes:
@@ -746,6 +819,13 @@ class Label:
         return axes_ranges_current
 
     def _get_final_axes_ranges(self) -> dict[Axes, list[NDArray[Any]]]:
+        """
+        Retrieves the final axes ranges for all axes.
+
+        Returns
+        --------------------
+        dict[matplotlib.axes.Axes, list[numpy.ndarray]]
+        """
         _axes_range_singleton = AxesRangeSingleton()
 
         axes_ranges_current = self._get_axes_ranges_current()
@@ -780,21 +860,28 @@ class Label:
 
     #! Xpad and Ypad will change the size of the axis
     def apply_tight_layout(self) -> None:
+        """
+        Applies `tight_layout` to the figure.
 
+        Returns
+        --------------------
+        None
+        """
         if self.tight_layout:
             # Ignore this warning when using inset_axes:
             # UserWarning: This figure includes Axes that are not compatible with tight_layout, so results might be incorrect
             with warnings.catch_warnings():
                 warnings.simplefilter("ignore")
-                try:
-                    plt.tight_layout(
-                        w_pad=self.x_pad, h_pad=self.y_pad, *self.args, **self.kwargs
-                    )
-                except Exception:
-                    plt.tight_layout(w_pad=self.x_pad, h_pad=self.y_pad)
+                plt.tight_layout(w_pad=self.xpad_layout, h_pad=self.ypad_layout)
 
     def label(self) -> None:
+        """
+        Adds labels, limits, and layouts to the figure's axes.
 
+        Returns
+        --------------------
+        None
+        """
         self.add_minor_ticks_axes()
         self.set_labels()
         self.apply_tight_layout()
@@ -804,10 +891,12 @@ class Label:
 @track_order
 def label(
     lab_lims: list[Any],
-    x_pad: int = 2,
-    y_pad: int = 2,
+    xpad_label: int | float = 5,
+    ypad_label: int | float = 5,
     minor_ticks_axes: bool = True,
     tight_layout: bool = True,
+    xpad_layout: int = 2,
+    ypad_layout: int = 2,
     *args: Any,
     **kwargs: Any,
 ) -> None:
@@ -821,18 +910,22 @@ def label(
     lab_lims : list[Any]
         A list specifying labels and limits for each axis in the figure. Each entry
         should be a tuple of the form `(x_label, y_label, x_limits, y_limits)`.
-    x_pad : int, default=2
-        Horizontal padding for tight layout.
-    y_pad : int, default=2
-        Vertical padding for tight layout.
+    xpad_label : int or float, default=5
+        Padding for the x-axis label.
+    ypad_label : int or float, default=5
+        Padding for the y-axis label.
     minor_ticks_axes : bool, default=True
         Whether to add minor ticks to all axes.
     tight_layout : bool, default=True
         Whether to apply `tight_layout` to the figure.
+    xpad_layout : int, default=2
+        Horizontal padding for tight layout.
+    ypad_layout : int, default=2
+        Vertical padding for tight layout.
     *args : Any
-        Additional arguments for `plt.tight_layout`.
+        Additional arguments for `ax.set_xlabel` and `ax.set_ylabel.
     **kwargs : Any
-        Additional keyword arguments for `plt.tight_layout`.
+        Additional keyword arguments for `ax.set_xlabel` and `ax.set_ylabel`.
 
     Notes
     --------------------
@@ -853,8 +946,8 @@ def label(
     >>> import gsplot as gs
     >>> gs.label(
     >>>     lab_lims=[("X Label", "Y Label", [1, 10, "log"], [1, 20, 2])],
-    >>>     x_pad=5,
-    >>>     y_pad=5,
+    >>>     xpad_layout=5,
+    >>>     ypad_layout=5,
     >>> )
     """
 
@@ -863,11 +956,12 @@ def label(
 
     _label = Label(
         class_params["lab_lims"],
-        class_params["x_pad"],
-        class_params["y_pad"],
+        class_params["xpad_label"],
+        class_params["ypad_label"],
         class_params["minor_ticks_axes"],
         class_params["tight_layout"],
-        *class_params["args"],
+        class_params["xpad_layout"],
+        class_params["ypad_layout"],
         **class_params["kwargs"],
     )
 

{gsplot-0.1.0 → gsplot-0.1.2}/gsplot/style/legend.py

@@ -1,3 +1,4 @@
+import warnings
 from typing import Any
 
 import matplotlib.pyplot as plt
@@ -197,8 +198,10 @@ class LegendAxes:
         """
         _lg_list = []
         for ax in plt.gcf().axes:
-            _lg = ax.legend(*self.args, **self.kwargs)
-            _lg_list.append(_lg)
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore")
+                _lg = ax.legend(*self.args, **self.kwargs)
+                _lg_list.append(_lg)
         return _lg_list
 
 

gsplot-0.1.2/gsplot/version.py

@@ -0,0 +1,2 @@
+__version__ = '0.1.2'
+__commit__ = '828d28fda62f1f1935e76112444e53617990c7cc'

{gsplot-0.1.0 → gsplot-0.1.2}/pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "gsplot"
 
-version = "0.1.0"
+version = "0.1.2"
 
 description = "General-scientific plot based on matplotlib"
 authors = [

gsplot-0.1.0/gsplot/version.py

@@ -1,2 +0,0 @@
-__version__ = "0.1.0"
-__commit__ = "68872757a43a0b342475f0a47af06a1014d9d223"