absfuyu 5.6.1__py3-none-any.whl → 6.1.2__py3-none-any.whl

absfuyu/typings.py

@@ -3,8 +3,8 @@ Absfuyu: Core
 -------------
 Pre-defined typing
 
-Version: 5.6.1
-Date updated: 12/09/2025 (dd/mm/yyyy)
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
 """
 
 # Module Package
@@ -33,21 +33,18 @@ __all__ = [
 from collections.abc import Callable
 from typing import Any, ParamSpec, Protocol, TypeVar, overload
 
-try:
-    from typing import override  # type: ignore
-except ImportError:
-    from absfuyu.core.decorator import dummy_decorator as override
-
-
 # Type
 # ---------------------------------------------------------------------------
 # Types where neither is possible are invariant
+# Type safety must be strict
 T = TypeVar("T")  # Type invariant
 # Type variables that are covariant can be substituted
 # with a more specific type without causing errors
+# Safe to treat a Box[int] as a Box[object]
 T_co = TypeVar("T_co", covariant=True)  # Type covariant
 # Type variables that are contravariant can be substituted
 # with a more general type without causing errors
+# Safe to use a Box[object] where a Box[int] is needed
 T_contra = TypeVar("T_contra", contravariant=True)  # Type contravariant
 
 KT = TypeVar("KT")

absfuyu/util/__init__.py

@@ -3,8 +3,8 @@ Absufyu: Utilities
 ------------------
 Some random utilities
 
-Version: 5.6.1
-Date updated: 12/09/2025 (dd/mm/yyyy)
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
 """
 
 # Module Package
@@ -25,6 +25,7 @@ __all__ = [
 # Library
 # ---------------------------------------------------------------------------
 import pkgutil
+import subprocess
 from datetime import datetime
 from string import printable
 
@@ -257,3 +258,31 @@ def convert_to_raw_unicode(text: str, partial: bool = True) -> str:
         character if character in character_set and partial else _convert(character)
         for character in text
     )
+
+
+@versionadded("5.9.0")
+def is_command_available(cmd: list[str] | str, err_msg: str = "") -> None:
+    """
+    Checks if the desired command available
+
+    Parameters
+    ----------
+    cmd : list[str] | str
+        Command to check
+
+    err_msg : str, optional
+        Custom error message, by default ""
+
+    Raises
+    ------
+    ValueError
+        When command is unvailable
+    """
+    try:
+        subprocess.run(
+            cmd,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+    except Exception:
+        raise ValueError(err_msg)

absfuyu/util/api.py

@@ -3,8 +3,8 @@ Absufyu: API
 ------------
 Fetch data stuff
 
-Version: 5.6.1
-Date updated: 12/09/2025 (dd/mm/yyyy)
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
 """
 
 # Module level
@@ -23,12 +23,15 @@ import subprocess
 from pathlib import Path
 from typing import NamedTuple
 
-import requests
-
 from absfuyu.core.baseclass import BaseClass
 from absfuyu.core.docstring import versionadded, versionchanged
 from absfuyu.logger import logger
 
+try:
+    import requests
+except ImportError:
+    raise ImportError("Please install requests package")
+
 
 # Function
 # ---------------------------------------------------------------------------

absfuyu/util/cli.py

@@ -0,0 +1,119 @@
+"""
+Absfuyu: CLI
+------------
+Custom Argument Parser
+
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
+"""
+
+# Module level
+# ---------------------------------------------------------------------------
+__all__ = ["FuyuArgumentParser"]
+
+
+# Library
+# ---------------------------------------------------------------------------
+import logging
+import sys
+from argparse import ArgumentDefaultsHelpFormatter, ArgumentParser
+from collections.abc import Callable
+from typing import Any
+
+
+# Class
+# ---------------------------------------------------------------------------
+class FuyuArgumentParser(ArgumentParser):
+    """
+    Usage:
+    ------
+    >>> import sys
+    >>> args = FuyuArgumentParser()
+    >>> args.start()
+    """
+
+    def __init__(
+        self,
+        prog: str | None = None,
+        description: str | None = None,
+        epilog: str | None = None,
+        version: str = "0.0.1",
+        formatter_class: Any = ArgumentDefaultsHelpFormatter,
+        prefix_chars: str = "-",
+        argument_default: Any = None,
+        conflict_handler: str = "error",
+        add_help: bool = True,
+        allow_abbrev: bool = True,
+        exit_on_error: bool = True,
+    ) -> None:
+        # Desc
+        if description is None:
+            description = f"Absfuyu CLI {version}"
+
+        # Default
+        self._default_args = ["--help"]
+
+        # Super
+        super().__init__(
+            prog=prog,
+            description=description,
+            epilog=epilog,
+            formatter_class=formatter_class,
+            prefix_chars=prefix_chars,
+            argument_default=argument_default,
+            conflict_handler=conflict_handler,
+            add_help=add_help,
+            allow_abbrev=allow_abbrev,
+            exit_on_error=exit_on_error,
+        )
+
+        # Add version
+        self.add_argument("-v", "--version", action="version", version=f"%(prog)s {version}")
+
+        # Add log level
+        _ll_val = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+        self.add_argument(
+            "-ll",
+            "--log-level",
+            metavar="LOG_LEVEL",
+            dest="log_level",
+            choices=_ll_val,
+            default="ERROR",
+            help=f"Log level: {', '.join(_ll_val)}",
+        )
+
+    def _fuyu_set_log_level(self, log_level: str = "ERROR") -> None:
+        log_levels = {
+            "DEBUG": logging.DEBUG,
+            "INFO": logging.INFO,
+            "WARNING": logging.WARNING,
+            "ERROR": logging.ERROR,
+            "CRITICAL": logging.CRITICAL,
+        }
+        logging.basicConfig(
+            level=log_levels[log_level],
+            format="[%(asctime)s] [%(module)s] [%(name)s] [%(funcName)s] [%(levelname)-s] %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+
+    def start(self, default: Callable[[], Any] | None = None):
+        """
+        Quick start for argument parser
+
+        Parameters
+        ----------
+        default : Callable[[], Any] | None, optional
+            | Default callable to run, by default ``None``
+            | Shows help on default behavior (default=None)
+
+        Returns
+        -------
+        Namespace
+            Namespace
+        """
+        if default is None:
+            args = self.parse_args(args=None if sys.argv[1:] else self._default_args)
+        else:
+            args = self.parse_args(args=None if sys.argv[1:] else default())
+        self._fuyu_set_log_level(getattr(args, "log_level", "ERROR"))
+        return args

absfuyu/util/gui.py

@@ -0,0 +1,91 @@
+"""
+Absfuyu: GUI
+------------
+Custom tkinter GUI
+
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
+"""
+
+# Module level
+# ---------------------------------------------------------------------------
+__all__ = ["CustomTkinterApp"]
+
+
+# Library
+# ---------------------------------------------------------------------------
+import tkinter as tk
+
+from absfuyu.pkg_data.logo import AbsfuyuLogo
+
+
+# Class
+# ---------------------------------------------------------------------------
+class CustomTkinterApp(tk.Tk):
+
+    def __init__(self, title: str | None = None, size: tuple[int, int] | None = None) -> None:
+        """
+        Custom Tkinter GUI
+
+        Parameters
+        ----------
+        title : str | None, optional
+            Title of the app, by default None
+
+        size : tuple[int, int] | None, optional
+            Size of the app (width, height), by default None
+        """
+        super().__init__()
+
+        # Set custom icon
+        self.iconphoto(True, tk.PhotoImage(data=AbsfuyuLogo.SHORT))
+
+        # Title
+        self.title(title)
+
+        # Set size
+        self._absfuyu_set_width_height(size)
+
+    # @versionadded("5.10.0")
+    def _absfuyu_set_width_height(self, size: tuple[int, int] | None = None) -> None:
+        """
+        Set width and height for the app.
+
+        Parameters
+        ----------
+        size : tuple[int, int] | None, optional
+            Size of the app (width, height), by default ``None``
+            (420 x 250)
+        """
+        # Set GUI appears in center
+        if size is None:
+            _width = 420
+            _height = 250
+        else:
+            _width, _height = size
+
+        _width_screen = self.winfo_screenwidth()
+        _width_screen_offset = 0.0052  # x offset mutiplier
+        _x_offset = int(_width_screen * _width_screen_offset)
+
+        _height_screen = self.winfo_screenheight()
+        _height_screen_offset = 0.0926  # y offset mutiplier
+        _y_offset = int(_height_screen * _height_screen_offset)
+
+        if _width > _width_screen:
+            _width = int(_width_screen * (1 - 0.001))
+            # _x_offset = 0
+
+        if _height > (_height_screen - _y_offset):
+            _height = int(_height_screen * (1 - 0.001))
+            _y_offset = 0
+
+        _x = (_width_screen / 2) - (_width / 2) - _x_offset
+        _y = (_height_screen / 2) - (_height / 2) - _y_offset
+
+        self.geometry(f"{_width}x{_height}+{int(_x)}+{int(_y)}")
+
+
+if __name__ == "__main__":
+    app = CustomTkinterApp("absfuyu")
+    app.mainloop()

absfuyu/util/json_method.py

@@ -3,8 +3,8 @@ Absfuyu: Json Method
 --------------------
 ``.json`` file handling
 
-Version: 5.6.1
-Date updated: 12/09/2025 (dd/mm/yyyy)
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
 """
 
 # Module level

absfuyu/util/lunar.py

@@ -4,8 +4,8 @@ Absfuyu: Lunar calendar
 -----------------------
 Convert to lunar calendar
 
-Version: 5.6.1
-Date updated: 12/09/2025 (dd/mm/yyyy)
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
 
 Source:
 -------

absfuyu/util/package.py

@@ -0,0 +1,124 @@
+"""
+Absfuyu: Package
+----------------
+Package related
+
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
+"""
+
+# Module level
+# ---------------------------------------------------------------------------
+__all__ = ["PackageManager"]
+
+
+# Library
+# ---------------------------------------------------------------------------
+import ensurepip
+import importlib
+import importlib.metadata
+import importlib.util
+import subprocess
+import sys
+
+from absfuyu.core.baseclass import BaseClass
+
+
+# Class
+# ---------------------------------------------------------------------------
+class PackageManager(BaseClass):
+    """
+    Utility class for checking, installing, and importing Python packages safely.
+    """
+
+    def __init__(
+        self,
+        package: str,
+        import_name: str | None = None,
+        auto_upgrade: bool = False,
+        auto_bootstrap: bool = True,
+    ) -> None:
+        """
+        A configurable package manager utility that can check, install, and import Python packages safely.
+
+        Parameters
+        ----------
+        package : str
+            The pip package name (e.g. "absfuyu", "random").
+
+        import_name : str | None
+            The importable module name if different from the package name (e.g. "PIL" for "pillow").
+
+        auto_upgrade : bool, by default ``False``
+            Whether to automatically upgrade packages during installation.
+
+        auto_bootstrap : bool, by default ``True``
+            Whether to automatically bootstrap pip using ensurepip if it's missing.
+        """
+        self.package = package
+        self.import_name = import_name
+        self.auto_upgrade = auto_upgrade
+        self.auto_bootstrap = auto_bootstrap
+
+    @property
+    def version(self) -> str | None:
+        """
+        Version of package if available
+
+        Returns
+        -------
+        str
+            Version of package
+
+        None
+            When package is not available
+        """
+        try:
+            return importlib.metadata.version(self.package or self.import_name)
+        except importlib.metadata.PackageNotFoundError:
+            return None
+
+    def _run_pip_install(self, package: str) -> None:
+        """
+        Internal helper to safely run pip install, bootstrapping pip if needed.
+        """
+        try:
+            import pip  # noqa: F401
+        except ImportError:
+            if self.auto_bootstrap:
+                ensurepip.bootstrap()
+            else:
+                raise RuntimeError("pip not found and auto_bootstrap is disabled.")
+
+        cmd = [sys.executable, "-m", "pip", "install", package]
+        if self.auto_upgrade:
+            cmd.append("--upgrade")
+
+        try:
+            subprocess.check_call(cmd)
+        except subprocess.CalledProcessError as e:
+            raise RuntimeError(f"Failed to install {package}: {e}")
+
+    def ensure_installed(self) -> None:
+        """
+        Ensure a Python package is installed. Installs (and optionally upgrades) it if missing.
+        """
+        module_name = self.import_name or self.package
+
+        if importlib.util.find_spec(module_name) is None:
+            self._run_pip_install(self.package)
+
+    def ensure_import(self):
+        """
+        Ensure a Python package is importable, installing it if necessary.
+        Returns the imported module.
+        """
+        module_name = self.import_name or self.package
+
+        if importlib.util.find_spec(module_name) is not None:
+            return importlib.import_module(module_name)
+
+        self.logger.info(f"Installing missing package: {self.package} ...")
+
+        self._run_pip_install(self.package)
+        return importlib.import_module(module_name)