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

absfuyu/util/json_method.py

@@ -3,8 +3,8 @@ Absfuyu: Json Method
 --------------------
 ``.json`` file handling
 
-Version: 5.0.0
-Date updated: 25/02/2025 (dd/mm/yyyy)
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
 """
 
 # Module level
@@ -16,7 +16,6 @@ __all__ = ["JsonFile"]
 # ---------------------------------------------------------------------------
 import json
 from pathlib import Path
-from typing import Any
 
 from absfuyu.core import BaseClass
 
@@ -26,6 +25,20 @@ from absfuyu.core import BaseClass
 class JsonFile(BaseClass):
     """
     ``.json`` file handling
+
+    Parameters
+    ----------
+    json_file_location : str | Path
+        .json file location
+
+    encoding : str | None, optional
+        Data encoding, by default ``"utf-8"``
+
+    indent : int | str | None, optional
+        Indentation when export to json file, by default ``4``
+
+    sort_keys : bool, optional
+        Sort the keys before export to json file, by default ``True``
     """
 
     def __init__(
@@ -37,26 +50,40 @@ class JsonFile(BaseClass):
         sort_keys: bool = True,
     ) -> None:
         """
-        json_file_location: json file location
-        encoding: data encoding (Default: utf-8)
-        indent: indentation when export to json file
-        sort_keys: sort the keys before export to json file
+        ``.json`` file handling
+
+        Parameters
+        ----------
+        json_file_location : str | Path
+            .json file location
+
+        encoding : str | None, optional
+            Data encoding, by default ``"utf-8"``
+
+        indent : int | str | None, optional
+            Indentation when export to json file, by default ``4``
+
+        sort_keys : bool, optional
+            Sort the keys before export to json file, by default ``True``
         """
+
         self.json_file_location = Path(json_file_location)
         self.encoding = encoding
         self.indent = indent
         self.sort_keys = sort_keys
-        self.data: dict[Any, Any] = {}
+        self.data: dict = {}
 
     def __str__(self) -> str:
         return f"{self.__class__.__name__}({self.json_file_location.name})"
 
-    def load_json(self) -> dict[Any, Any]:
+    def load_json(self) -> dict:
         """
         Load ``.json`` file
 
-        :returns: ``.json`` data
-        :rtype: dict
+        Returns
+        -------
+        dict
+            ``.json`` data
         """
         with open(self.json_file_location, "r", encoding=self.encoding) as file:
             self.data = json.load(file)
@@ -68,11 +95,13 @@ class JsonFile(BaseClass):
         with open(self.json_file_location, "w", encoding=self.encoding) as file:
             file.writelines(json_data)
 
-    def update_data(self, data: dict[Any, Any]) -> None:
+    def update_data(self, data: dict) -> None:
         """
         Update ``.json`` data without save
 
-        :param data: ``.json`` data
-        :type data: dict
+        Parameters
+        ----------
+        data : dict
+            ``.json`` data
         """
         self.data = data

absfuyu/util/lunar.py

@@ -4,8 +4,8 @@ Absfuyu: Lunar calendar
 -----------------------
 Convert to lunar calendar
 
-Version: 1.0.3
-Date updated: 15/11/2024 (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)