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

absfuyu/numbers/__init__.py

@@ -0,0 +1,13 @@
+"""
+Absfuyu: Numbers
+----------------
+Numbers related
+
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
+"""
+
+
+from absfuyu.numbers.number_to_word import NumberToWords
+from absfuyu.numbers.shorten_number import Decimal
+from absfuyu.numbers.time_duration import Duration

absfuyu/numbers/number_to_word.py

@@ -0,0 +1,321 @@
+"""
+Absfuyu: Number to word
+-----------------------
+Convert number to word
+
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
+"""
+
+# Module level
+# ---------------------------------------------------------------------------
+__all__ = ["NumberToWords"]
+
+
+# Library
+# ---------------------------------------------------------------------------
+from abc import ABC, abstractmethod
+from decimal import Decimal
+
+
+# Class
+# ---------------------------------------------------------------------------
+class NumberToWordsBase(ABC):
+    """
+    Base abstract class for Number to words
+    """
+
+    @abstractmethod
+    def convert(self, number: int) -> str:
+        """
+        Convert number to words
+
+        Parameters
+        ----------
+        number : int
+            Number to convert to
+
+        Returns
+        -------
+        str
+            Number in word form
+        """
+        pass
+
+
+class NumberToWordsEN(NumberToWordsBase):
+    """
+    Number to words - English
+
+    Support up to 10^120
+    """
+
+    _ones = [
+        "zero",
+        "one",
+        "two",
+        "three",
+        "four",
+        "five",
+        "six",
+        "seven",
+        "eight",
+        "nine",
+        "ten",
+        "eleven",
+        "twelve",
+        "thirteen",
+        "fourteen",
+        "fifteen",
+        "sixteen",
+        "seventeen",
+        "eighteen",
+        "nineteen",
+    ]
+
+    _tens = ["", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy", "eighty", "ninety"]
+
+    _scales = [
+        "",  # 10^0
+        "thousand",  # 10^3
+        "million",  # 10^6
+        "billion",  # 10^9
+        "trillion",  # 10^12
+        "quadrillion",  # 10^15
+        "quintillion",
+        "sextillion",
+        "septillion",
+        "octillion",
+        "nonillion",
+        "decillion",
+        "undecillion",
+        "duodecillion",
+        "tredecillion",
+        "quattuordecillion",
+        "quindecillion",
+        "sexdecillion",
+        "septendecillion",
+        "octodecillion",
+        "novemdecillion",
+        "vigintillion",
+        "unvigintillion",
+        "duovigintillion",
+        "tresvigintillion",
+        "quattuorvigintillion",
+        "quinvigintillion",
+        "sesvigintillion",
+        "septemvigintillion",
+        "octovigintillion",
+        "novemvigintillion",
+        "trigintillion",
+        "untrigintillion",
+        "duotrigintillion",
+        "trestrigintillion",
+        "quattuortrigintillion",
+        "quintrigintillion",
+        "sestrigintillion",
+        "septentrigintillion",
+        "octotrigintillion",
+        "noventrigintillion",
+    ]
+
+    def convert(self, number) -> str:
+        dec = Decimal(str(number))
+
+        if dec == 0:
+            return "zero"
+
+        sign = ""
+        if dec < 0:
+            sign = "minus "
+            dec = abs(dec)
+
+        integer_part = int(dec)
+        fractional_part = dec - integer_part
+
+        words = sign + self._convert_integer(integer_part)
+
+        if fractional_part != 0:
+            frac_digits = str(fractional_part).split(".")[1]
+            frac_words = " ".join(self._ones[int(d)] for d in frac_digits)
+            words += f" point {frac_words}"
+
+        return words
+
+    def _convert_integer(self, number: int) -> str:
+        if number == 0:
+            return "zero"
+
+        parts = []
+        scale_index = 0
+
+        try:
+            while number > 0:
+                number, group = divmod(number, 1000)
+                if group > 0:
+                    text = self._under_1000(group)
+                    scale = self._scales[scale_index]
+                    parts.append(f"{text} {scale}".strip())
+                scale_index += 1
+        except IndexError:
+            raise ValueError("Number to large")
+
+        return " ".join(reversed(parts))
+
+    def _under_1000(self, number: int) -> str:
+        hundreds, rest = divmod(number, 100)
+        parts = []
+
+        if hundreds > 0:
+            parts.append(f"{self._ones[hundreds]} hundred")
+
+        if rest > 0:
+            if hundreds > 0:
+                parts.append("and")
+            parts.append(self._under_100(rest))
+
+        return " ".join(parts)
+
+    def _under_100(self, number: int) -> str:
+        if number < 20:
+            return self._ones[number]
+
+        tens, unit = divmod(number, 10)
+        if unit == 0:
+            return self._tens[tens]
+
+        return f"{self._tens[tens]} {self._ones[unit]}"
+
+
+class NumberToWordsVI(NumberToWordsBase):
+    """
+    Number to words - Vietnamese
+
+    Support:
+    - Scale infinitely
+    - Decimal number
+    """
+
+    _ones = ["không", "một", "hai", "ba", "bốn", "năm", "sáu", "bảy", "tám", "chín"]
+
+    def convert(self, number: int | float) -> str:
+        dec = Decimal(str(number))
+
+        if dec == 0:
+            return "không"
+
+        sign = ""
+        if dec < 0:
+            sign = "âm "
+            dec = abs(dec)
+
+        integer_part = int(dec)
+        fractional_part = dec - integer_part
+
+        words = sign + self._convert_integer(integer_part)
+
+        if fractional_part != 0:
+            frac_digits = str(fractional_part).split(".")[1]
+            frac_words = " ".join(self._ones[int(d)] for d in frac_digits)
+            words += f" phẩy {frac_words}"
+
+        return words
+
+    def _convert_integer(self, number: int) -> str:
+        parts = []
+        index = 0
+
+        while number > 0:
+            number, group = divmod(number, 1000)
+            if group > 0:
+                text = self._under_1000(group)
+                scale = self._scale_name(index)
+                parts.append(f"{text} {scale}".strip())
+            index += 1
+
+        return " ".join(reversed(parts))
+
+    def _scale_name(self, index: int) -> str:
+        if index == 0:
+            return ""
+
+        base = ["", "nghìn", "triệu"]
+        pos = index % 3
+        level = index // 3
+
+        scale = base[pos]
+        if level > 0:
+            scale = f"{scale} {'tỷ ' * level}".strip()
+
+        return scale.strip()
+
+    def _under_1000(self, number: int) -> str:
+        hundreds, rest = divmod(number, 100)
+        parts = []
+
+        if hundreds > 0:
+            parts.append(f"{self._ones[hundreds]} trăm")
+
+        if rest > 0:
+            if hundreds > 0 and rest < 10:
+                parts.append("lẻ")
+            parts.append(self._under_100(rest))
+
+        return " ".join(parts)
+
+    def _under_100(self, number: int) -> str:
+        if number < 10:
+            return self._ones[number]
+
+        tens, unit = divmod(number, 10)
+
+        if tens == 1:
+            if unit == 0:
+                return "mười"
+            if unit == 5:
+                return "mười lăm"
+            return f"mười {self._ones[unit]}"
+
+        result = f"{self._ones[tens]} mươi"
+
+        if unit == 0:
+            return result
+        if unit == 1:
+            return f"{result} mốt"
+        if unit == 5:
+            return f"{result} lăm"
+
+        return f"{result} {self._ones[unit]}"
+
+
+# Main
+class NumberToWords:
+    _languages: dict[str, NumberToWordsBase] = {
+        "en": NumberToWordsEN,
+        "vi": NumberToWordsVI,
+    }
+
+    def __init__(self, lang: str = "en"):
+        self.set_language(lang)
+
+    def set_language(self, lang: str) -> None:
+        if lang not in self._languages:
+            raise ValueError(f"Unsupported language: {lang}")
+        # self._converter = self._languages[lang]()
+        self._converter: NumberToWordsBase = self._languages.get(lang, NumberToWordsEN)()
+
+    def convert(self, number: int) -> str:
+        """
+        Convert number to words
+
+        Parameters
+        ----------
+        number : int
+            Number to convert to
+
+        Returns
+        -------
+        str
+            Number in word form
+        """
+        return self._converter.convert(number)

absfuyu/numbers/shorten_number.py

@@ -0,0 +1,303 @@
+"""
+Absfuyu: Shorten number
+-----------------------
+Short number base on suffixes
+
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
+"""
+
+# Module level
+# ---------------------------------------------------------------------------
+__all__ = [
+    "UnitSuffixFactory",
+    "CommonUnitSuffixesFactory",
+    "Decimal",
+    "shorten_number",
+]
+
+
+# Library
+# ---------------------------------------------------------------------------
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from functools import wraps
+from typing import Annotated, NamedTuple, ParamSpec, Self, TypeVar
+
+from absfuyu.core import versionadded
+
+# Type
+# ---------------------------------------------------------------------------
+P = ParamSpec("P")  # Parameter type
+N = TypeVar("N", int, float)  # Number type
+
+
+# Class - Decimal
+# ---------------------------------------------------------------------------
+@versionadded("4.1.0")
+class UnitSuffixFactory(NamedTuple):
+    base: int
+    short_name: list[str]
+    full_name: list[str]
+
+
+@versionadded("4.1.0")
+class CommonUnitSuffixesFactory:
+    NUMBER = UnitSuffixFactory(
+        1000,
+        [
+            "",
+            "K",
+            "M",
+            "B",
+            "T",
+            "Qa",
+            "Qi",
+            "Sx",
+            "Sp",
+            "Oc",
+            "No",
+            "Dc",
+            "Ud",
+            "Dd",
+            "Td",
+            "Qad",
+            "Qid",
+            "Sxd",
+            "Spd",
+            "Ocd",
+            "Nod",
+            "Vg",
+            "Uvg",
+            "Dvg",
+            "Tvg",
+            "Qavg",
+            "Qivg",
+            "Sxvg",
+            "Spvg",
+            "Ovg",
+            "Nvg",
+            "Tg",
+            "Utg",
+            "Dtg",
+            "Ttg",
+            "Qatg",
+            "Qitg",
+            "Sxtg",
+            "Sptg",
+            "Otg",
+            "Ntg",
+        ],
+        [
+            "",  # < Thousand
+            "Thousand",
+            "Million",
+            "Billion",  # 1e9
+            "Trillion",
+            "Quadrillion",
+            "Quintillion",
+            "Sextillion",
+            "Septillion",
+            "Octillion",
+            "Nonillion",
+            "Decillion",  # 1e33
+            "Undecillion",
+            "Duodecillion",
+            "Tredecillion",
+            "Quattuordecillion",
+            "Quindecillion",
+            "Sexdecillion",
+            "Septendecillion",
+            "Octodecillion",
+            "Novemdecillion",
+            "Vigintillion",  #  1e63
+            "Unvigintillion",
+            "Duovigintillion",
+            "Tresvigintillion",
+            "Quattuorvigintillion",
+            "Quinvigintillion",
+            "Sesvigintillion",
+            "Septemvigintillion",
+            "Octovigintillion",
+            "Novemvigintillion",
+            "Trigintillion",  # 1e93
+            "Untrigintillion",
+            "Duotrigintillion",
+            "Trestrigintillion",
+            "Quattuortrigintillion",
+            "Quintrigintillion",
+            "Sestrigintillion",
+            "Septentrigintillion",
+            "Octotrigintillion",
+            "Noventrigintillion",  #  1e120
+        ],
+    )
+    DATA_SIZE = UnitSuffixFactory(
+        1024,
+        ["b", "Kb", "MB", "GB", "TB", "PB", "EB", "ZB", "YB", "BB"],
+        [
+            "byte",
+            "kilobyte",
+            "megabyte",
+            "gigabyte",
+            "terabyte",
+            "petabyte",
+            "exabyte",
+            "zetabyte",
+            "yottabyte",
+            "brontobyte",
+        ],
+    )
+
+
+@dataclass
+@versionadded("4.1.0")
+class Decimal:
+    """
+    Shorten large number
+
+    Parameters
+    ----------
+    original_value : int | float
+        Value to shorten
+
+    base : int
+        Short by base (must be > 0)
+
+    suffixes : list[str]
+        List of suffixes to use (ascending order)
+
+    factory : UnitSuffixFactory | None
+        ``UnitSuffixFactory`` to use
+        (will overwrite ``base`` and ``suffixes``)
+
+    suffix_full_name : bool
+        Use suffix full name (available with ``UnitSuffixFactory``), by default ``False``
+
+    Returns
+    -------
+    Decimal
+        Decimal instance
+    """
+
+    original_value: int | float = field(repr=False)
+    base: Annotated[int, "positive", "not_zero"] = field(repr=False, default=1000)
+    suffixes: list[str] = field(repr=False, default_factory=list)
+    factory: UnitSuffixFactory | None = field(repr=False, default=None)
+    suffix_full_name: bool = field(repr=False, default=False)
+    # Post init
+    value: int | float = field(init=False)
+    suffix: str = field(init=False)
+
+    def __post_init__(self) -> None:
+        self.base = max(1, self.base)  # Make sure that base >= 1
+        self._get_factory()
+        self.value, self.suffix = self._convert_decimal()
+
+    def __str__(self) -> str:
+        return self.to_text().strip()
+
+    @classmethod
+    def number(cls, value: int | float, suffix_full_name: bool = False) -> Self:
+        """Decimal for normal large number"""
+        return cls(
+            value,
+            factory=CommonUnitSuffixesFactory.NUMBER,
+            suffix_full_name=suffix_full_name,
+        )
+
+    @classmethod
+    def data_size(cls, value: int | float, suffix_full_name: bool = False) -> Self:
+        """Decimal for data size"""
+        return cls(
+            value,
+            factory=CommonUnitSuffixesFactory.DATA_SIZE,
+            suffix_full_name=suffix_full_name,
+        )
+
+    @staticmethod
+    def scientific_short(value: int | float) -> str:
+        """Short number in scientific format"""
+        return f"{value:.2e}"
+
+    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
+
+    def _convert_decimal(self) -> tuple[float, str]:
+        """Convert to smaller number"""
+        suffix = self.suffixes[0] if len(self.suffixes) > 0 else ""
+        unit = 1
+        for i, suffix in enumerate(self.suffixes):
+            unit = self.base**i
+            if self.original_value < unit * self.base:
+                break
+        output = self.original_value / unit
+        return output, suffix
+
+    def to_text(self, decimal: int = 2, *, separator: str = " ", float_only: bool = True) -> str:
+        """
+        Convert to string
+
+        Parameters
+        ----------
+        decimal : int, optional
+            Round up to which decimal, by default ``2``
+
+        separator : str, optional
+            Character between value and suffix, by default ``" "``
+
+        float_only : bool, optional
+            Returns value as <float> instead of <int> when ``decimal = 0``, by default ``True``
+
+        Returns
+        -------
+        str
+            Decimal string
+        """
+        val = self.value.__round__(decimal)
+        formatted_value = f"{val:,}"
+        if not float_only and decimal == 0:
+            formatted_value = f"{int(val):,}"
+        return f"{formatted_value}{separator}{self.suffix}"
+
+
+# Decorator
+# ---------------------------------------------------------------------------
+@versionadded("5.0.0")
+def shorten_number(f: Callable[P, N]) -> Callable[P, Decimal]:
+    """
+    Shorten the number value by name
+
+    Parameters
+    ----------
+    f : Callable[P, N]
+        Function that return ``int`` or ``float``
+
+    Returns
+    -------
+    Callable[P, Decimal]
+        Function that return ``Decimal``
+
+
+    Usage
+    -----
+    Use this as a decorator (``@shorten_number``)
+
+    Example:
+    --------
+    >>> import random
+    >>> @shorten_number
+    >>> def big_num() -> int:
+    ...     random.randint(100000000, 10000000000)
+    >>> big_num()
+    4.20 B
+    """
+
+    @wraps(f)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> Decimal:
+        value = Decimal.number(f(*args, **kwargs))
+        return value
+
+    return wrapper