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

absfuyu/general/content.py

@@ -3,8 +3,8 @@ Absfuyu: Content
 ----------------
 Handle .txt file
 
-Version: 1.2.6
-Date updated: 05/04/2024 (dd/mm/yyyy)
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
 
 Usage:
 ------
@@ -28,7 +28,7 @@ from itertools import chain
 from pathlib import Path
 from typing import Self
 
-from absfuyu.core import BaseClass, ShowAllMethodsMixin, unidecode
+from absfuyu.core import BaseClass, GetClassMembersMixin, unidecode
 from absfuyu.logger import logger
 
 
@@ -140,7 +140,7 @@ class Content(BaseClass):
         return self.__class__([self.data, self.tag])
 
 
-class LoadedContent(list[Content], ShowAllMethodsMixin):
+class LoadedContent(list[Content], GetClassMembersMixin):
     """
     Contain list of ``Content``
     """

absfuyu/general/human.py

@@ -3,8 +3,8 @@ Absfuyu: Human
 --------------
 Human related stuff
 
-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

absfuyu/general/resrel.py

@@ -0,0 +1,213 @@
+"""
+Absfuyu: Relative resolution
+----------------------------
+Relative resolution
+
+Use with screen resolution getter like ``tkinter``, ``ctypes``, ``screeninfo`` is recommended
+
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
+"""
+
+# Module level
+# ---------------------------------------------------------------------------
+__all__ = ["RelativeResoluton", "RelativeResolutonTranslater"]
+
+
+# Library
+# ---------------------------------------------------------------------------
+from fractions import Fraction
+from typing import Self, overload
+
+from absfuyu.core.baseclass import BaseClass
+
+
+# Class
+# ---------------------------------------------------------------------------
+class RelativeResoluton(BaseClass):
+    def __init__(self, x: int, y: int) -> None:
+        """
+        Resolution
+
+        Parameters
+        ----------
+        x : int
+            Normally width
+
+        y : int
+            Normally height
+
+        Raises
+        ------
+        ValueError
+            When x or y < 1
+        """
+        if x < 1 or y < 1:
+            raise ValueError("Resolution must be >= 1")
+
+        self.x = x
+        self.y = y
+
+    @property
+    def ratio(self) -> Fraction:
+        """
+        Ratio of the resolution
+        """
+        return Fraction(self.x, self.y)
+
+    def scale_by(self, by: int | float | Fraction, /) -> Self:
+        """
+        Scale the resolution by an amount
+
+        Parameters
+        ----------
+        by : int | float | Fraction
+            Amount to scale
+
+        Returns
+        -------
+        Self
+            New scaled resolution
+        """
+        if isinstance(by, Fraction):
+            x = int(self.x * by.numerator / by.denominator)
+            y = int(self.y * by.numerator / by.denominator)
+        else:
+            x = int(self.x * by)
+            y = int(self.y * by)
+        return self.__class__(x, y)
+
+    @overload
+    def get_point_relative(self, x: int, y: int, /) -> tuple[Fraction, Fraction]: ...
+    @overload
+    def get_point_relative(self, x: int, y: int, /, *, strict: bool = True) -> tuple[Fraction, Fraction]: ...
+    def get_point_relative(self, x: int, y: int, /, *, strict: bool = True) -> tuple[Fraction, Fraction]:
+        """
+        Get relative point from fixed point.
+
+        Parameters
+        ----------
+        x : int
+            Normally width
+
+        y : int
+            Normally height
+
+        strict : bool, optional
+            Convert ``x`` and ``y`` into type int first, by default ``True``
+
+        Returns
+        -------
+        tuple[Fraction, Fraction]
+            Relative point
+        """
+        if strict:
+            x = int(x)
+            y = int(y)
+        x_rel = Fraction(x, self.x)
+        y_rel = Fraction(y, self.y)
+        return x_rel, y_rel
+
+    def get_fixed_point(self, x_rel: Fraction, y_rel: Fraction, /) -> tuple[int, int]:
+        """
+        Get fixed point from relative point.
+
+        Parameters
+        ----------
+        x_rel : Fraction
+            Normally width
+
+        y_rel : Fraction
+            Normally height
+
+        Returns
+        -------
+        tuple[int, int]
+            Fixed point
+        """
+        x = int(self.x * x_rel.numerator / x_rel.denominator)
+        y = int(self.y * y_rel.numerator / y_rel.denominator)
+        return x, y
+
+
+class RelativeResolutonTranslater(RelativeResoluton):
+    """
+    Relative resolution translater
+
+    It is recommended to use with screen resolution getter like
+    ``tkinter``, ``ctypes``, ``screeninfo``, ``pyautogui``
+
+
+    Example:
+    --------
+    >>> import tkinter as tk
+    >>> root = tk.Tk()
+    >>> width, height = root.winfo_screenwidth(), root.winfo_screenheight()
+    >>> rr = RelativeResolutonTranslater(width, height)
+    >>> rr.add_target_scale((1920, 1080))
+    >>> rr.t(1280, 720)
+
+    >>> import tkinter as tk
+    >>> root = tk.Tk()
+    >>> width, height = root.winfo_screenwidth(), root.winfo_screenheight()
+    >>> rr = RelativeResolutonTranslater(1920, 1080)
+    >>> rr.add_target_scale((width, height))
+    >>> rr.t(1280, 720)
+    """
+
+    def __init__(self, x: int, y: int) -> None:
+        super().__init__(x, y)
+        self._target_scale = Fraction(1, 1)
+
+    @overload
+    def add_target_scale(self, target: int | float, /) -> None: ...
+    @overload
+    def add_target_scale(self, target: Fraction, /) -> None: ...
+    @overload
+    def add_target_scale(self, target: tuple[int, int], /) -> None: ...
+    def add_target_scale(self, target: tuple[int, int] | Fraction | int | float, /) -> None:
+        """
+        Add target scale to scale resolution to
+
+        Parameters
+        ----------
+        target : tuple[int, int] | Fraction | int | float
+            Target scale (tuple[int, int] for desire resolution)
+
+        Raises
+        ------
+        NotImplementedError
+            When ratio of new and old resolution is not equal
+        """
+        if isinstance(target, tuple):  # Resolution
+            if self.ratio == Fraction(*target):  # Same ratio
+                self._target_scale = Fraction(target[0] / self.x)
+            else:
+                raise NotImplementedError("Resolution's ratio conversion not supported")
+        else:
+            self._target_scale = Fraction(target)
+
+    def translate_point(self, x: int, y: int, /) -> tuple[int, int]:
+        """
+        Translate point(x, y) to target_scale fixed point through relative point.
+
+        Parameters
+        ----------
+        x : int
+            Normally width
+
+        y : int
+            Normally height
+
+        Returns
+        -------
+        tuple[int, int]
+            Translated point
+        """
+        x_rel, y_rel = self.get_point_relative(x, y)
+        fixed_point = self.scale_by(self._target_scale).get_fixed_point(x_rel, y_rel)
+        return fixed_point
+
+    def t(self, x: int, y: int, /) -> tuple[int, int]:
+        """Wrapper for self.translate_point"""
+        return self.translate_point(x, y)

absfuyu/general/shape.py

@@ -3,8 +3,8 @@ Absfuyu: Shape
 --------------
 Shapes
 
-Version: 5.0.0
-Date updated: 19/02/2025 (dd/mm/yyyy)
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
 """
 
 # Module level
@@ -33,12 +33,7 @@ __all__ = [
 # ---------------------------------------------------------------------------
 import math
 from abc import ABC, abstractmethod
-from typing import ClassVar, Self
-
-try:
-    from typing import override  # type: ignore
-except ImportError:
-    from absfuyu.core.decorator import dummy_decorator as override
+from typing import ClassVar, Self, override
 
 from absfuyu.core import BaseClass
 

absfuyu/general/tax.py

@@ -0,0 +1,344 @@
+"""
+Absfuyu: Tax calculator
+-----------------------
+Tax calculator
+
+Version: 6.1.1
+Date updated: 30/12/2025 (dd/mm/yyyy)
+"""
+
+# Module level
+# ---------------------------------------------------------------------------
+__all__ = ["PersonalIncomeTaxCalculator"]
+
+
+# Library
+# ---------------------------------------------------------------------------
+from dataclasses import dataclass
+from typing import Literal, TypedDict, overload
+
+from absfuyu.core.baseclass import BaseClass, BaseDataclass
+
+# Class
+# ---------------------------------------------------------------------------
+type TaxLevel = list[tuple[float | int | None, float]]
+
+
+@dataclass
+class TaxLevelResult(BaseDataclass):
+    """
+    Result for a single tax level.
+
+    Parameters
+    ----------
+    lower : float
+        Lower bound
+
+    upper : float | None
+        Upper bound. ``None`` means +infinite
+
+    rate : float
+        Tax percentage in decimal (0.1 for 10%)
+
+    amount_taxed : float
+        Amount to calculate in current tax level
+
+    tax : float
+        Tax amount in current tax level
+    """
+
+    lower: float
+    upper: float | None
+    rate: float
+    amount_taxed: float
+    tax: float
+
+
+class TaxCalculationResult(TypedDict):
+    """
+    Tax calculation result.
+
+    Parameters
+    ----------
+    gross_income : float
+        The input gross income for the calculation.
+
+    deductions : float, optional
+        Amount to subtract from gross income before tax.
+
+    taxable_income : float
+        Gross income minus deductions.
+
+    per_tax_level : list[TaxLevelResult]
+        Detailed breakdown of income taxed at each tax level.
+
+    gross_tax : float
+        Total tax before credits.
+
+    tax_credits : float, optional
+        Amount subtracted from the computed tax after calculation.
+
+    net_tax : float
+        Total tax after applying credits.
+
+    effective_rate : float
+        Ratio of net tax to gross income (net_tax / gross_income).
+
+    marginal_rate : float
+        Tax rate applied to the last amount of money of taxable income.
+    """
+
+    gross_income: float
+    deductions: float
+    taxable_income: float
+    per_tax_level: list[TaxLevelResult]
+    gross_tax: float
+    tax_credits: float
+    net_tax: float
+    effective_rate: float
+    marginal_rate: float
+
+
+class TaxCalculationResultRaw(TypedDict):
+    """
+    Tax calculation result.
+
+    Parameters
+    ----------
+    gross_income : float
+        The input gross income for the calculation.
+
+    deductions : float, optional
+        Amount to subtract from gross income before tax.
+
+    taxable_income : float
+        Gross income minus deductions.
+
+    per_tax_level : list[TaxLevelResult]
+        Detailed breakdown of income taxed at each tax level.
+
+    gross_tax : float
+        Total tax before credits.
+
+    tax_credits : float, optional
+        Amount subtracted from the computed tax after calculation.
+
+    net_tax : float
+        Total tax after applying credits.
+
+    effective_rate : float
+        Ratio of net tax to gross income (net_tax / gross_income).
+
+    marginal_rate : float
+        Tax rate applied to the last amount of money of taxable income.
+    """
+
+    gross_income: float
+    deductions: float
+    taxable_income: float
+    per_tax_level: list[dict[str, float | None]]
+    gross_tax: float
+    tax_credits: float
+    net_tax: float
+    effective_rate: float
+    marginal_rate: float
+
+
+class PersonalIncomeTaxCalculator(BaseClass):
+    """
+    Progressive personal income tax calculator.
+
+    Parameters
+    ----------
+    tax_levels : list[tuple[float | int | None, float]], optional
+        Ordered list of tax levels.
+        Each tax level is represented as a tuple of (upper_bound, rate),
+        where ``upper_bound`` is the cumulative upper limit of the tax level.
+        Use ``None`` for the last tax level (no upper limit).
+        Example: ``[(10000, 0.10), (50000, 0.2), (None, 0.3)]``.
+        Set to ``None`` to have 0% tax rate, by default ``None``
+
+    deductions : float, optional
+        Amount to subtract from gross income before tax, by default 0.0
+
+    tax_credits : float, optional
+        Amount subtracted from the computed tax after calculation, by default 0.0
+
+    Attributes
+    ----------
+    gross_income : float
+        The input gross income for the calculation.
+
+    taxable_income : float
+        Gross income minus deductions.
+
+    per_tax_level : list[TaxLevelResult]
+        Detailed breakdown of income taxed at each tax level.
+
+    gross_tax : float
+        Total tax before credits.
+
+    net_tax : float
+        Total tax after applying credits.
+
+    effective_rate : float
+        Ratio of net tax to gross income.
+
+    marginal_rate : float
+        Tax rate applied to the last amount of money of taxable income.
+
+
+    Example:
+    --------
+    >>> tax_levels = [(100, 0.05), (None, 0.1)]
+    >>> cal = PersonalIncomeTaxCalculator(tax_levels)
+    >>> cal.calculate(500)
+    >>> cal.to_dict(raw=True)
+    {...}
+
+    >>> cal.interpret_result()
+    ===== Tax information =====
+    Taxable income: 500.00 (500.00 - 0.00)
+    - Level 1: 0.00 - 100.00 @ 5.0%: 100.00 -> tax 5.00
+    - Level 2: 100.00 - 500.00 @ 10.0%: 400.00 -> tax 40.00
+    Net tax: 45.00 (45.00 - 0.00)
+    Effective rate: 9.00%
+    Marginal rate: 10.0%
+    """
+
+    def __init__(self, tax_levels: TaxLevel | None = None, deductions: float = 0.0, tax_credits: float = 0.0) -> None:
+        """
+        Progressive personal income tax calculator.
+
+        Parameters
+        ----------
+        tax_levels : list[tuple[float | int | None, float]], optional
+            Ordered list of tax levels.
+            Each tax level is represented as a tuple of (upper_bound, rate),
+            where ``upper_bound`` is the cumulative upper limit of the tax level.
+            Use ``None`` for the last tax level (no upper limit).
+            Example: ``[(10000, 0.10), (50000, 0.2), (None, 0.3)]``.
+            Set to ``None`` to have 0% tax rate, by default ``None``
+
+        deductions : float, optional
+            Amount to subtract from gross income before tax, by default 0.0
+
+        tax_credits : float, optional
+            Amount subtracted from the computed tax after calculation, by default 0.0
+        """
+        self.tax_levels = [] if tax_levels is None else tax_levels
+        self.deductions = deductions
+        self.tax_credits = tax_credits
+
+        # Results populated after calculation
+        self.gross_income: float = 0.0
+        self.taxable_income: float = 0.0
+        self.per_tax_level: list[TaxLevelResult] = []
+        self.gross_tax: float = 0.0
+        self.net_tax: float = 0.0
+        self.effective_rate: float = 0.0
+        self.marginal_rate: float = 0.0
+
+    def calculate(self, gross_income: float) -> None:
+        """
+        Compute tax for a given gross income.
+
+        Parameters
+        ----------
+        gross_income : float
+            Total gross income (unless tax levels are defined otherwise).
+        """
+        if gross_income < 0:
+            raise ValueError("gross_income must be non-negative")
+
+        self.gross_income = gross_income
+        self.taxable_income = max(0.0, gross_income - max(0.0, self.deductions))
+
+        self.per_tax_level = []
+        prev_upper = 0.0
+        remaining = self.taxable_income
+        self.gross_tax = 0.0
+        self.marginal_rate = 0.0
+
+        for upper, rate in self.tax_levels:
+            lower = prev_upper
+            if upper is None:
+                amount_taxed = remaining
+            else:
+                band = upper - prev_upper
+                amount_taxed = min(band, max(0.0, remaining))
+            tax = max(0.0, amount_taxed) * rate
+            self.per_tax_level.append(TaxLevelResult(lower, upper, rate, amount_taxed, tax))
+            self.gross_tax += tax
+            remaining -= amount_taxed
+            prev_upper = upper if upper is not None else prev_upper
+            if remaining <= 1e-9:
+                self.marginal_rate = rate
+                break
+            self.marginal_rate = rate
+
+        self.net_tax = max(0.0, self.gross_tax - max(0.0, self.tax_credits))
+        self.effective_rate = self.net_tax / gross_income if gross_income > 0 else 0.0
+
+    @overload
+    def to_dict(self) -> TaxCalculationResult: ...  # type: ignore
+
+    @overload
+    def to_dict(self, *, raw: Literal[True] = ...) -> TaxCalculationResultRaw: ...
+
+    def to_dict(self, *, raw: bool = False) -> TaxCalculationResult | TaxCalculationResultRaw:
+        """
+        Returns calculation result in dict format
+
+        Parameters
+        ----------
+        raw : bool, optional
+            Convert every value to dict, by default ``False``
+
+        Returns
+        -------
+        TaxCalculationResult
+            Tax calculation result
+        """
+        result: TaxCalculationResult = {
+            "gross_income": self.gross_income,
+            "deductions": self.deductions,
+            "taxable_income": self.taxable_income,
+            "per_tax_level": self.per_tax_level,
+            "gross_tax": self.gross_tax,
+            "tax_credits": self.tax_credits,
+            "net_tax": self.net_tax,
+            "effective_rate": self.effective_rate,
+            "marginal_rate": self.marginal_rate,
+        }
+        if raw:
+            result_raw: TaxCalculationResultRaw = result  # type: ignore
+            result_raw["per_tax_level"] = [x.to_dict() for x in result["per_tax_level"]]
+            return result
+        return result
+
+    def interpret_result(self) -> str:
+        result = self.to_dict()
+        text = ["===== Tax information ====="]
+
+        # text.append(f"Gross income: {result['gross_income']:,}")
+        # text.append(f"Deduction: {result['deductions']:,}")
+        # text.append(f"Taxable income: {result['taxable_income']:,}")
+        text.append(
+            f"Taxable income: {result['taxable_income']:,.2f} ({result['gross_income']:,.2f} - {result['deductions']:,.2f})"
+        )
+
+        for idx, tax_level in enumerate(result["per_tax_level"], start=1):
+            upper = f"{tax_level.upper:,.2f}" if tax_level.upper is not None else f"{self.gross_income:,.2f}"
+            text.append(
+                f"- Level {idx}: {tax_level.lower:,.2f} - {upper} @ {tax_level.rate*100:.1f}%: {tax_level.amount_taxed:,.2f} -> tax {tax_level.tax:,.2f}"
+            )
+
+        # text.append(f"Gross tax: {result['gross_tax']:,}")
+        # text.append(f"Tax credits: {result['tax_credits']:,}")
+        # text.append(f"Net tax: {result['net_tax']:,}")
+        text.append(f"Net tax: {result['net_tax']:,.2f} ({result['gross_tax']:,.2f} - {result['tax_credits']:,.2f})")
+
+        text.append(f"Effective rate: {result['effective_rate']*100:.2f}%")
+        text.append(f"Marginal rate: {result['marginal_rate']*100:.1f}%")
+        return "\n".join(text)