gsplot 0.0.1__py3-none-any.whl

gsplot/figure/figure_tools.py

@@ -0,0 +1,66 @@
+from typing import Any
+
+from matplotlib import pyplot as plt
+from numpy.typing import NDArray
+
+__all__: list[str] = ["get_figure_size"]
+
+
+class FigureLayout:
+    """
+    A utility class for retrieving the size of the current Matplotlib figure.
+
+    This class provides a method to get the size of the current figure in inches.
+
+    Methods
+    --------------------
+    get_figure_size()
+        Retrieves the size of the current figure in inches.
+
+    Examples
+    --------------------
+    >>> layout = FigureLayout()
+    >>> size = layout.get_figure_size()
+    >>> print(size)
+    array([10.,  6.])  # Example output (width, height in inches)
+    """
+
+    def get_figure_size(self) -> NDArray[Any]:
+        """
+        Retrieves the size of the current Matplotlib figure in inches.
+
+        Returns
+        --------------------
+        numpy.ndarray
+            The width and height of the current figure in inches as a NumPy array.
+
+        Examples
+        --------------------
+        >>> layout = FigureLayout()
+        >>> size = layout.get_figure_size()
+        >>> print(size)
+        array([10.,  6.])  # Example output (width, height in inches)
+        """
+        figure_size = plt.gcf().get_size_inches()
+        return figure_size
+
+
+def get_figure_size() -> NDArray[Any]:
+    """
+    A convenient function to retrieve the size of the current Matplotlib figure.
+
+    This function is a shorthand for calling `FigureLayout().get_figure_size()`.
+
+    Returns
+    --------------------
+    numpy.ndarray
+        The width and height of the current figure in inches as a NumPy array.
+
+    Examples
+    --------------------
+    >>> import gsplot as gs
+    >>> size = gs.get_figure_size()
+    >>> print(size)
+    array([10.,  6.])  # Example output (width, height in inches)
+    """
+    return FigureLayout().get_figure_size()

gsplot/figure/show.py

@@ -0,0 +1,205 @@
+from typing import Any
+
+import matplotlib.pyplot as plt
+
+from ..base.base import CreateClassParams, ParamsGetter, bind_passed_params
+from .store import StoreSingleton
+
+__all__: list[str] = ["show"]
+
+
+class Show:
+    """
+    A utility class for managing figure saving and displaying in Matplotlib.
+
+    This class provides functionality to save the current figure in multiple formats
+    and optionally display it.
+
+    Parameters
+    --------------------
+    name : str, optional
+        The base name for saved figure files (default is "gsplot").
+    ft_list : list of str, optional
+        A list of file formats for saving the figure (default is ["png", "pdf"]).
+    dpi : float, optional
+        The resolution (dots per inch) for saving the figure (default is 600).
+    show : bool, optional
+        Whether to display the figure (default is True).
+    *args : Any
+        Additional positional arguments passed to `plt.savefig`.
+    **kwargs : Any
+        Additional keyword arguments passed to `plt.savefig`.
+
+    Attributes
+    --------------------
+    name : str
+        The base name for saved figure files.
+    ft_list : list of str
+        A list of file formats for saving the figure.
+    dpi : float
+        The resolution for saving the figure.
+    show : bool
+        Whether to display the figure.
+    args : Any
+        Additional positional arguments passed to `plt.savefig`.
+    kwargs : Any
+        Additional keyword arguments passed to `plt.savefig`.
+    _store_singleton : StoreSingleton
+        A singleton instance for managing the storage state.
+
+    Methods
+    --------------------
+    store_fig()
+        Saves the current figure in the specified formats.
+    get_store()
+        Retrieves the storage state from the singleton instance.
+    show_fig()
+        Displays the current figure if `show` is True.
+
+    Examples
+    --------------------
+    >>> show_instance = Show(name="example", ft_list=["png", "jpg"], dpi=300, show=False)
+    >>> show_instance.store_fig()
+    >>> show_instance.show_fig()  # Will not display the figure since `show=False`
+    """
+
+    def __init__(
+        self,
+        name: str = "gsplot",
+        ft_list: list[str] = ["png", "pdf"],
+        dpi: float = 600,
+        show: bool = True,
+        *args: Any,
+        **kwargs: Any,
+    ):
+
+        self.name: str = name
+        self.ft_list: list[str] = ft_list
+        self.dpi: float = dpi
+        self.show: bool = show
+        self.args: Any = args
+        self.kwargs: Any = kwargs
+
+        self._store_singleton: StoreSingleton = StoreSingleton()
+
+    def store_fig(self) -> None:
+        """
+        Saves the current figure in the specified formats.
+
+        This method uses the provided file formats and resolution to save the figure.
+
+        Raises
+        --------------------
+        Exception
+            If an error occurs during saving, a warning is printed.
+
+        Examples
+        --------------------
+        >>> show_instance = Show(name="example", ft_list=["png", "jpg"], dpi=300)
+        >>> show_instance.store_fig()
+        """
+        if self.get_store():
+            # save figure
+            fname_list: list[str] = [f"{self.name}.{ft}" for ft in self.ft_list]
+
+            # !TODO: figure out **kwargs for savefig. None, or *args, **kwargs
+            for fname in fname_list:
+                try:
+                    plt.savefig(
+                        fname,
+                        bbox_inches="tight",
+                        dpi=self.dpi,
+                        *self.args,
+                        **self.kwargs,
+                    )
+                except Exception as e:
+                    print(f"Error saving figure: {e}")
+                    plt.savefig(fname, bbox_inches="tight", dpi=self.dpi)
+
+    def get_store(self) -> bool | int:
+        """
+        Retrieves the storage state from the singleton instance.
+
+        Returns
+        --------------------
+        bool or int
+            The storage state indicating whether saving is enabled.
+
+        Examples
+        --------------------
+        >>> show_instance = Show()
+        >>> print(show_instance.get_store())
+        True
+        """
+
+        store: bool | int = self._store_singleton.store
+        return store
+
+    def show_fig(self) -> None:
+        """
+        Displays the current figure if `show` is True.
+
+        Examples
+        --------------------
+        >>> show_instance = Show(show=True)
+        >>> show_instance.show_fig()
+        """
+        if self.show:
+            plt.show()
+
+
+@bind_passed_params()
+def show(
+    fname: str = "gsplot",
+    ft_list: list[str] = ["png", "pdf"],
+    dpi: float = 600,
+    show: bool = True,
+    *args: Any,
+    **kwargs: Any,
+) -> None:
+    """
+    A convenience function to save and optionally display a Matplotlib figure.
+
+    This function wraps the `Show` class for easier access and management of figure
+    saving and displaying.
+
+    Parameters
+    --------------------
+    fname : str, optional
+        The base name for saved figure files (default is "gsplot").
+    ft_list : list of str, optional
+        A list of file formats for saving the figure (default is ["png", "pdf"]).
+    dpi : float, optional
+        The resolution (dots per inch) for saving the figure (default is 600).
+    show : bool, optional
+        Whether to display the figure (default is True).
+    *args : Any
+        Additional positional arguments passed to `plt.savefig`.
+    **kwargs : Any
+        Additional keyword arguments passed to `plt.savefig`.
+
+    Notes
+    --------------------
+    This function utilizes the `ParamsGetter` to retrieve bound parameters and
+    the `CreateClassParams` class to handle the merging of default, configuration,
+    and passed parameters.
+
+    Examples
+    --------------------
+    >>> import gsplot as gs
+    >>> gs.show(fname="example", ft_list=["png", "jpg"], dpi=300, show=True)
+    """
+    passed_params: dict[str, Any] = ParamsGetter("passed_params").get_bound_params()
+    class_params = CreateClassParams(passed_params).get_class_params()
+
+    _show: Show = Show(
+        class_params["fname"],
+        class_params["ft_list"],
+        class_params["dpi"],
+        class_params["show"],
+        *class_params["args"],
+        **class_params["kwargs"],
+    )
+
+    _show.store_fig()
+    _show.show_fig()

gsplot/figure/store.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import threading
+
+__all__: list[str] = []
+
+
+class StoreSingleton:
+    """
+    A thread-safe singleton class for managing a shared storage state.
+
+    This class ensures that a single instance is used to manage the storage state
+    across an application. The storage state can be a boolean or an integer (0 or 1),
+    providing flexibility for different use cases.
+
+    Attributes
+    --------------------
+    store : bool or int
+        The current storage state, which can be either a boolean or an integer (0 or 1).
+
+    Methods
+    --------------------
+    store
+        Retrieves the current storage state.
+    store(value)
+        Sets the storage state to a boolean or an integer (0 or 1).
+
+    Examples
+    --------------------
+    >>> singleton = StoreSingleton()
+    >>> print(singleton.store)
+    False  # Default value
+
+    >>> singleton.store = True
+    >>> print(singleton.store)
+    True
+
+    >>> singleton.store = 1
+    >>> print(singleton.store)
+    1
+
+    >>> singleton.store = "invalid"  # Raises ValueError
+    Traceback (most recent call last):
+        ...
+    ValueError: Store must be a boolean or integer.
+    """
+
+    _instance: StoreSingleton | None = None
+    _lock: threading.Lock = threading.Lock()  # Lock to ensure thread safety
+
+    def __new__(cls) -> "StoreSingleton":
+        with cls._lock:
+            if cls._instance is None:
+                cls._instance = super(StoreSingleton, cls).__new__(cls)
+                cls._instance._initialize_store()
+        return cls._instance
+
+    def _initialize_store(self) -> None:
+        """
+        Initializes the storage state to its default value (False).
+        """
+        # Explicitly initialize the instance variable with a type hint
+        self._store: bool | int = False
+
+    @property
+    def store(self) -> bool | int:
+        """
+        Retrieves the current storage state.
+
+        Returns
+        --------------------
+        bool or int
+            The current storage state.
+
+        Examples
+        --------------------
+        >>> singleton = StoreSingleton()
+        >>> print(singleton.store)
+        False
+        """
+        return self._store
+
+    @store.setter
+    def store(self, value: bool | int) -> None:
+        """
+        Sets the storage state.
+
+        Parameters
+        --------------------
+        value : bool or int
+            The new storage state. Must be a boolean or an integer (0 or 1).
+
+        Raises
+        --------------------
+        ValueError
+            If the value is not a boolean or integer, or if an integer is not 0 or 1.
+
+        Examples
+        --------------------
+        >>> singleton = StoreSingleton()
+        >>> singleton.store = True
+        >>> print(singleton.store)
+        True
+
+        >>> singleton.store = 1
+        >>> print(singleton.store)
+        1
+
+        >>> singleton.store = "invalid"  # Raises ValueError
+        Traceback (most recent call last):
+            ...
+        ValueError: Store must be a boolean or integer.
+        """
+        if not isinstance(value, (bool, int)):
+            raise ValueError("Store must be a boolean or integer.")
+        if isinstance(value, int) and value not in [0, 1]:
+            raise ValueError("Store must be 0 or 1 if integer.")
+
+        self._store = value

gsplot/hello_world/hello_world.py

@@ -0,0 +1,23 @@
+from rich import print
+
+from ..version import __commit__, __version__
+
+__all__ = ["hello_world"]
+
+
+def hello_world() -> None:
+    """
+    Print the version, commit hash, and an ASCII art of the logo.
+    """
+    ascii_art = r"""
+ ██████╗ ███████╗██████╗ ██╗      ██████╗ ████████╗
+██╔════╝ ██╔════╝██╔══██╗██║     ██╔═══██╗╚══██╔══╝
+██║  ███╗███████╗██████╔╝██║     ██║   ██║   ██║   
+██║   ██║╚════██║██╔═══╝ ██║     ██║   ██║   ██║   
+╚██████╔╝███████║██║     ███████╗╚██████╔╝   ██║   
+ ╚═════╝ ╚══════╝╚═╝     ╚══════╝ ╚═════╝    ╚═╝   
+        """
+
+    print(f"Version: {__version__}")
+    print(f"Commit : {__commit__}")
+    print(ascii_art)

gsplot/logger.py

@@ -0,0 +1,155 @@
+import os
+from datetime import datetime
+from typing import Any, cast
+
+import yaml
+from rich import print
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+from .version import __commit__, __version__
+
+
+class Logger:
+    HOME = os.path.expanduser("~")
+    LOG_PATH = os.path.join(HOME, ".config", "gsplot")
+    LOG_FILE_NAME = "gsplot_log.yml"
+    LOG_FILE_PATH = os.path.join(LOG_PATH, LOG_FILE_NAME)
+
+    def __init__(self):
+        self.console = Console()
+        self.log: dict[str, Any] = {}
+        self.version_idx: int | None = None
+        self.commit_idx: int | None = None
+
+        self.is_error: bool = False
+
+        self.create_file()
+        self.log = self.read_file()
+
+    def _create_empty_file(self):
+        with open(self.LOG_FILE_PATH, "w") as file:
+            file.write("{}")
+
+    def create_file(self):
+        if not os.path.exists(self.LOG_PATH):
+            os.makedirs(self.LOG_PATH)
+
+        # if YAML file does not exist, create it
+        if not os.path.exists(self.LOG_FILE_PATH):
+            self._create_empty_file()
+
+    def _init_log(self):
+        return {"versions": []}
+
+    def read_file(self) -> dict[str, Any]:
+        with open(self.LOG_FILE_PATH, "r") as file:
+            log = yaml.safe_load(file)
+
+        if not log or not log.get("versions"):
+            log = self._init_log()
+
+        return cast(dict[str, Any], log)
+
+    def get_date(self):
+        return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+    def _error_message(self, e: Exception) -> None:
+        warning_message = f"[bold yellow]gsplot log file is corrupted. [bold green]See gsplot_log.yml file: {self.LOG_FILE_PATH}\n[bold red]Error: {e}"
+
+        self.console.print(
+            Panel(
+                Text.from_markup(warning_message),
+                title="[bold yellow]Warning",
+                style="bold yellow",
+            )
+        )
+
+    def _get_versions_from_log(self) -> list[dict[str, str]]:
+        try:
+            return cast(list[dict[str, str]], self.log.get("versions", []))
+        except Exception as e:
+            self.is_error = True
+            self._error_message(e)
+            return []
+
+    def _get_commits_from_version(self, version: str) -> list[dict[str, str]]:
+        try:
+            return next(
+                (
+                    v.get("commits", [])
+                    for v in self.log["versions"]
+                    if v.get("version") == version
+                ),
+                [],
+            )
+        except Exception as e:
+            self.is_error = True
+            self._error_message(e)
+            return []
+
+    def _has_same_version(self, version: str) -> bool:
+        # Retrieve the list of versions from the log
+        versions: list[dict[str, str]] | None = self._get_versions_from_log()
+
+        if not versions:
+            return False
+
+        # Find the index of the version that matches the input
+        self.version_idx = next(
+            (i for i, v in enumerate(versions) if v.get("version") == version), None
+        )
+
+        # Return True if a match is found, otherwise False
+        return self.version_idx is not None
+
+    def _has_same_commit(self, commit: str) -> bool:
+        # Get commits from the version
+        commits: list[dict[str, str]] = self._get_commits_from_version(__version__)
+
+        if not commits:
+            return False
+
+        # Find the commit in the list of commits
+        self.commit_idx = next(
+            (i for i, c in enumerate(commits) if c.get("commit") == commit), None
+        )
+
+        # Return True if a match is found
+        return self.commit_idx is not None
+
+    def create_log(self):
+        if not self._has_same_version(__version__):
+            current = {
+                "version": __version__,
+                "commits": [{"commit": __commit__, "date": self.get_date()}],
+            }
+
+            self.log["versions"].append(current)
+        else:
+            if not self._has_same_commit(__commit__):
+                self.log["versions"][self.version_idx]["commits"].append(
+                    {"commit": __commit__, "date": self.get_date()}
+                )
+
+    def write_log(self, log: dict[str, Any]) -> None:
+        with open(self.LOG_FILE_PATH, "w") as file:
+            yaml.dump(log, file, default_flow_style=False, sort_keys=False, indent=2)
+
+    def make_log(self) -> None:
+        if self.is_error:
+            return None
+
+        try:
+            self.create_log()
+        except Exception as e:
+            self.is_error = True
+            self._error_message(e)
+
+        self.write_log(self.log)
+
+
+def logger():
+    _logger = Logger()
+    _logger.make_log()