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

absfuyu/util/path.py

@@ -3,8 +3,8 @@ Absfuyu: Path
 -------------
 Path related
 
-Version: 5.6.1
-Date updated: 12/09/2025 (dd/mm/yyyy)
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
 
 Feature:
 --------
@@ -18,6 +18,7 @@ __all__ = [
     # Main
     "DirectoryBase",
     "Directory",
+    "ProjectDirInit",
     "SaveFileAs",
     # Mixin
     "DirectoryInfoMixin",
@@ -34,13 +35,16 @@ __all__ = [
 
 # Library
 # ---------------------------------------------------------------------------
+import json
 import os
 import re
 import shutil
+from collections.abc import Mapping
+from dataclasses import dataclass
 from datetime import datetime
 from functools import partial
 from pathlib import Path
-from typing import Any, ClassVar, Literal, NamedTuple
+from typing import Any, ClassVar, Final, Literal, NamedTuple, Self, TypedDict
 
 from absfuyu.core.baseclass import BaseClass
 from absfuyu.core.decorator import add_subclass_methods_decorator
@@ -784,7 +788,7 @@ class DirectorySelectMixin(DirectoryBase):
         paths = [
             x
             for x in self.source_path.glob(pattern)
-            if x.is_file() and x.suffix in file_type
+            if x.is_file() and x.suffix.lower() in map(lambda x: x.lower(), file_type)
         ]
         return paths
 
@@ -819,6 +823,311 @@ class Directory(
     pass
 
 
+# Class - ProjectDirInit
+# ---------------------------------------------------------------------------
+class ProjectDirInitTemplate(TypedDict):
+    folders: list[str]
+    files: dict[str, Any]
+
+
+@dataclass(slots=True)
+class FileContent:
+    path: Path
+    content: str
+    overwrite: bool = False
+
+
+@versionadded("6.0.0")
+class ProjectDirInit(DirectoryBase):
+    """
+    Initialize and manage a project directory structure.
+
+    This class allows you to declaratively register folders and files,
+    then generate or clean them in a controlled way.
+
+    Attributes
+    ----------
+    source_path : Path
+        Root directory of the project.
+
+    auto_generate : bool
+        If True, folders/files are created immediately when added.
+
+    _folders : dict[str, Path]
+        Registered subfolders.
+
+    _files : dict[str, FileContent]
+        Registered files with content.
+    """
+
+    ENCODING: Final[str] = "utf-8"
+
+    def __init__(
+        self,
+        source_path: str | Path,
+        create_if_not_exist: bool = False,
+        *,
+        auto_generate: bool = False,
+    ) -> None:
+        """
+        Project directory
+
+        Parameters
+        ----------
+        source_path : str | Path
+            Root directory of the project.
+
+        create_if_not_exist : bool
+            Create the root directory if it does not exist, by default ``False``
+
+        auto_generate : bool, optional
+            Automatically create folders/files when calling add methods, by default ``False``
+        """
+
+        super().__init__(source_path, create_if_not_exist)
+
+        # This variable store sub folder/file paths
+        self.auto_generate = auto_generate
+        self._folders: dict[str, Path] = {}
+        self._files: dict[str, FileContent] = {}
+
+    # Register
+    # -----------------------------------------
+    def add_folder(self, name: str) -> Path:
+        """
+        Register a subfolder relative to the project root.
+
+        Parameters
+        ----------
+        name : str
+            Folder name
+
+        Returns
+        -------
+        Path
+            Absolute path to the registered folder.
+        """
+        # path = self.source_path.joinpath(name)
+        path = self.source_path / name
+
+        self._folders[name] = path
+        if self.auto_generate:
+            self._make_folder()
+
+        return path
+
+    def add_file(
+        self,
+        name: str,
+        content: str | None = None,
+        *,
+        overwrite: bool = False,
+    ) -> Path:
+        """
+        Register a file relative to the project root.
+
+        Parameters
+        ----------
+        name : str
+            File name
+
+        content : str | None, optional
+            File content, by default ``None``
+
+        overwrite : bool, optional
+            Overwrite file if it already exists, bt default ``False``
+
+        Returns
+        -------
+        Path
+            Absolute path to the registered file.
+        """
+        # path = self.source_path.joinpath(name)
+        path = self.source_path / name
+
+        # c = "" if content is None else content
+        # self._files[name] = FileContent(path, c)
+        self._files[name] = FileContent(
+            path=path,
+            content=content or "",
+            overwrite=overwrite,
+        )
+
+        if self.auto_generate:
+            self._make_file()
+
+        return path
+
+    # Generate
+    # -----------------------------------------
+    def _make_folder(self) -> None:
+        """
+        Generate folders in ``self._folders``
+        """
+        if len(self._folders) < 1:
+            return None
+
+        for x in self._folders.values():
+            if not x.exists():
+                x.mkdir(parents=True, exist_ok=True)
+
+    def _make_file(self) -> None:
+        """
+        Generate files in ``self._files``
+        """
+        if len(self._files) < 1:
+            return None
+
+        for x in self._files.values():
+            if x.path.exists() and not x.overwrite:
+                continue
+
+            # with x.path.open("w", encoding=self.ENCODING) as f:
+            #     f.write(x.content)
+            x.path.write_text(x.content, encoding=self.ENCODING)
+
+    def generate_project(self) -> None:
+        """
+        Generate all registered folders and files.
+        """
+        self._make_folder()
+        self._make_file()
+
+    # Clean
+    # -----------------------------------------
+    def clean_up(self, *, remove_root: bool = False) -> None:
+        """
+        Remove generated folders and files.
+
+        Parameters
+        ----------
+        remove_root : bool, optional
+            If ``True``, remove the entire project directory, by default ``False``
+        """
+        if remove_root:
+            shutil.rmtree(self.source_path, ignore_errors=False)
+            return None
+
+        # Del files
+        for file in self._files.values():
+            if file.path.exists():
+                file.path.unlink()
+
+        # Del folders
+        for x in self._folders.values():
+            shutil.rmtree(x.absolute(), ignore_errors=False)
+
+    # Template loader
+    # -----------------------------------------
+    @classmethod
+    def from_template_dict(
+        cls,
+        source_path: str | Path,
+        template: ProjectDirInitTemplate,
+        *,
+        variables: Mapping[str, str] | None = None,
+        create_if_not_exist: bool = True,
+        auto_generate: bool = True,
+    ) -> Self:
+        """
+        Create a project from a dictionary template.
+
+        Parameters
+        ----------
+        source_path : str | Path
+            Root project directory.
+
+        template : Mapping[str, Any]
+            Template definition.
+
+        variables : Mapping[str, str], optional
+            Variables used for string formatting.
+
+        create_if_not_exist : bool, optional
+            Create project root if missing, by default ``True``
+
+        auto_generate : bool, optional
+            Generate files/folders immediately, by default ``True``
+
+        Returns
+        -------
+        Self
+            Project with loaded template
+        """
+        project = cls(
+            source_path,
+            create_if_not_exist=create_if_not_exist,
+            auto_generate=auto_generate,
+        )
+
+        vars_ = variables or {}
+
+        # Folders
+        for folder in template.get("folders", []):
+            project.add_folder(folder.format(**vars_))
+
+        # Files
+        for path, content in template.get("files", {}).items():
+            project.add_file(
+                path.format(**vars_),
+                content=(content or "").format(**vars_),
+            )
+
+        return project
+
+    @classmethod
+    def from_template_json(
+        cls,
+        source_path: str | Path,
+        json_path: str | Path,
+        *,
+        variables: Mapping[str, str] | None = None,
+        create_if_not_exist: bool = True,
+        auto_generate: bool = True,
+        encoding: str = "utf-8",
+    ) -> Self:
+        """
+        Create a project from a JSON template file.
+
+        Parameters
+        ----------
+        source_path : str | Path
+            Root project directory.
+
+        json_path : str | Path
+            Path to .json template.
+
+        variables : Mapping[str, str], optional
+            Variables used for string formatting.
+
+        create_if_not_exist : bool, optional
+            Create project root if missing, by default ``True``
+
+        auto_generate : bool, optional
+            Generate files/folders immediately, by default ``True``
+
+        encoding : str
+            .json encoding
+
+        Returns
+        -------
+        Self
+            Project with loaded template
+        """
+        json_path = Path(json_path)
+
+        with json_path.open(encoding=encoding) as f:
+            template = json.load(f)
+
+        return cls.from_template_dict(
+            source_path,
+            template,
+            variables=variables,
+            create_if_not_exist=create_if_not_exist,
+            auto_generate=auto_generate,
+        )
+
+
 # Class - SaveFileAs
 # ---------------------------------------------------------------------------
 class SaveFileAs:

absfuyu/util/performance.py

@@ -3,8 +3,8 @@ Absfuyu: Performance
 --------------------
 Performance Check
 
-Version: 5.6.1
-Date updated: 12/09/2025 (dd/mm/yyyy)
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
 
 Feature:
 --------

absfuyu/util/shorten_number.py

@@ -1,12 +1,16 @@
 """
 Absfuyu: Shorten number
 -----------------------
-Short number base on suffixes
+Short number base on suffixes (deprecated, use absfuyu.numbers instead)
 
-Version: 5.6.1
-Date updated: 12/09/2025 (dd/mm/yyyy)
+WILL BE REMOVED IN VERSION 7.0.0
+
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
 """
 
+from __future__ import annotations
+
 # Module level
 # ---------------------------------------------------------------------------
 __all__ = [
@@ -14,6 +18,8 @@ __all__ = [
     "CommonUnitSuffixesFactory",
     "Decimal",
     "shorten_number",
+    "Duration",
+    "SupportDurationFormatPreset",
 ]
 
 
@@ -22,7 +28,7 @@ __all__ = [
 from collections.abc import Callable
 from dataclasses import dataclass, field
 from functools import wraps
-from typing import Annotated, NamedTuple, ParamSpec, Self, TypeVar
+from typing import Annotated, NamedTuple, ParamSpec, Protocol, Self, TypeVar
 
 from absfuyu.core import versionadded
 
@@ -32,7 +38,7 @@ P = ParamSpec("P")  # Parameter type
 N = TypeVar("N", int, float)  # Number type
 
 
-# Class
+# Class - Decimal
 # ---------------------------------------------------------------------------
 @versionadded("4.1.0")
 class UnitSuffixFactory(NamedTuple):
@@ -223,11 +229,7 @@ class Decimal:
     def _get_factory(self) -> None:
         if self.factory is not None:
             self.base = self.factory.base
-            self.suffixes = (
-                self.factory.full_name
-                if self.suffix_full_name
-                else self.factory.short_name
-            )
+            self.suffixes = self.factory.full_name if self.suffix_full_name else self.factory.short_name
 
     def _convert_decimal(self) -> tuple[float, str]:
         """Convert to smaller number"""
@@ -240,9 +242,7 @@ class Decimal:
         output = self.original_value / unit
         return output, suffix
 
-    def to_text(
-        self, decimal: int = 2, *, separator: str = " ", float_only: bool = True
-    ) -> str:
+    def to_text(self, decimal: int = 2, *, separator: str = " ", float_only: bool = True) -> str:
         """
         Convert to string
 
@@ -307,3 +307,196 @@ def shorten_number(f: Callable[P, N]) -> Callable[P, Decimal]:
         return value
 
     return wrapper
+
+
+# Class - Duration
+# ---------------------------------------------------------------------------
+# Format preset
+class SupportDurationFormatPreset(Protocol):
+    def __call__(self, duration: Duration, /) -> str: ...
+
+
+@dataclass
+@versionadded("5.16.0")
+class Duration:
+    """
+    Convert duration in seconds to a more readable form. Eg: 3 mins 2 secs
+
+    Parameters
+    ----------
+    total_seconds : int | float
+        Seconds to convert to
+    """
+
+    total_seconds: int | float
+
+    years: int = field(init=False)
+    months: int = field(init=False)
+    days: int = field(init=False)
+    hours: int = field(init=False)
+    minutes: int = field(init=False)
+    seconds: int = field(init=False)
+
+    _formats: dict[str, SupportDurationFormatPreset] = field(init=False)
+
+    # Calculate duration
+    def _calculate_duration(self) -> None:
+        SEC_PER_MIN = 60
+        SEC_PER_HOUR = 3600
+        SEC_PER_DAY = 86400
+        SEC_PER_MONTH = 30 * SEC_PER_DAY
+        SEC_PER_YEAR = 365 * SEC_PER_DAY
+
+        secs = self.total_seconds
+
+        self.years, secs = divmod(secs, SEC_PER_YEAR)
+        self.months, secs = divmod(secs, SEC_PER_MONTH)
+        self.days, secs = divmod(secs, SEC_PER_DAY)
+        self.hours, secs = divmod(secs, SEC_PER_HOUR)
+        self.minutes, self.seconds = divmod(secs, SEC_PER_MIN)
+
+    # Format handling
+    def _init_format(self) -> None:
+
+        def duration_compact_preset(duration: Self, /) -> str:
+            """
+            Example: "1y 2m 3d 4h 5m 6s"
+            (fields = hidden when = 0).
+            """
+            parts = []
+            if duration.years:
+                parts.append(f"{duration.years}y")
+            if duration.months:
+                parts.append(f"{duration.months}m")
+            if duration.days:
+                parts.append(f"{duration.days}d")
+            if duration.hours:
+                parts.append(f"{duration.hours}h")
+            if duration.minutes:
+                parts.append(f"{duration.minutes}m")
+            if duration.seconds:
+                parts.append(f"{duration.seconds}s")
+            return " ".join(parts) if parts else "0s"
+
+        def duration_HMS_only_preset(duration: Self, /) -> str:
+            """
+            Example: "02:15:09" (HH:MM:SS only).
+            """
+            total = duration.total_seconds
+            h, m = divmod(total, 3600)
+            m, s = divmod(m, 60)
+            return f"{h:02d}:{m:02d}:{s:02d}"
+
+        def duration_digital_preset(duration: Self, /) -> str:
+            """
+            Examples:
+            - If >= 1 day: "1d 02:03:04"
+            - else: "02:03:04"
+            """
+            total = duration.total_seconds
+            days, sec = divmod(total, 86400)
+            h, sec = divmod(sec, 3600)
+            m, s = divmod(sec, 60)
+
+            if days:
+                return f"{days}d {h:02d}:{m:02d}:{s:02d}"
+            return f"{h:02d}:{m:02d}:{s:02d}"
+
+        self._formats = {
+            "compact": duration_compact_preset,
+            "hms": duration_HMS_only_preset,
+            "digital": duration_digital_preset,
+        }
+
+    @versionadded("5.17.0")
+    def add_format(self, name: str, format_func: SupportDurationFormatPreset) -> None:
+        """
+        Add format style to Duration
+
+        Parameters
+        ----------
+        name : str
+            Name of the style (name will be lowercased)
+
+        format_func : SupportDurationFormatPreset
+            Format function
+        """
+        self._formats[name.lower().strip()] = format_func
+
+    @property
+    def available_formats(self) -> list[str]:
+        """
+        Available style format
+
+        Returns
+        -------
+        list[str]
+            All available style formats
+        """
+        return list(self._formats)
+
+    def __format__(self, format_spec: str) -> str:
+        """
+        Change format of an object.
+
+        Usage
+        -----
+        >>> print(f"{<object>:<format_spec>}")
+        >>> print(<object>.__format__(<format_spec>))
+        >>> print(format(<object>, <format_spec>))
+        """
+
+        func = self._formats.get(format_spec.lower().strip(), None)
+
+        if func is None:
+            return self.__str__()
+        else:
+            return func(self)
+
+    # POST INIT
+    def __post_init__(self) -> None:
+        if not isinstance(self.total_seconds, (int, float)) or self.total_seconds < 0:
+            raise ValueError("seconds must be a non-negative number")
+        self._calculate_duration()
+        self._init_format()
+
+    def __str__(self) -> str:
+
+        def _plural(n: int | float, word: str):
+            return f"{n} {word}{'s' if n != 1 else ''}"
+
+        parts = []
+        if self.years:
+            parts.append(_plural(self.years, "year"))
+        if self.months:
+            parts.append(_plural(self.months, "month"))
+        if self.days:
+            parts.append(_plural(self.days, "day"))
+        if self.hours:
+            parts.append(_plural(self.hours, "hour"))
+        if self.minutes:
+            parts.append(_plural(self.minutes, "minute"))
+        if self.seconds:
+            parts.append(_plural(self.seconds, "second"))
+        return " ".join(parts) if parts else "0 second"
+
+    # From other type of duration
+    @classmethod
+    def from_minute(cls, minutes: int | float) -> Self:
+        return cls(minutes * 60)
+
+    @classmethod
+    def from_hour(cls, hours: int | float) -> Self:
+        return cls(hours * 3600)
+
+    @classmethod
+    def from_day(cls, days: int | float) -> Self:
+        return cls(days * 86400)
+
+    @classmethod
+    def from_month(cls, months: int | float) -> Self:
+        return cls(months * 86400 * 30)
+
+    @classmethod
+    def from_year(cls, years: int | float) -> Self:
+        return cls(years * 86400 * 365)

absfuyu/util/text_table.py

@@ -3,8 +3,8 @@ Absufyu: Utilities
 ------------------
 Text table
 
-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/zipped.py

@@ -4,8 +4,8 @@ Absfuyu: Zipped
 Zipping stuff
 (deprecated, use absfuyu.util.path.Directory)
 
-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