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

absfuyu/extra/da/dadf.py

@@ -3,8 +3,8 @@ Absfuyu: Data Analysis
 ----------------------
 Data Analyst DataFrame
 
-Version: 5.6.1
-Date updated: 12/09/2025 (dd/mm/yyyy)
+Version: 6.1.2
+Date updated: 30/12/2025 (dd/mm/yyyy)
 """
 
 # Module level
@@ -17,6 +17,7 @@ __all__ = [
     "DataAnalystDataFrameNAMixin",
     "DataAnalystDataFrameOtherMixin",
     "DataAnalystDataFrameDateMixin",
+    "DataAnalystDataFrameExportMixin",
     "DataAnalystDataFrameCityMixin",
 ]
 
@@ -25,24 +26,21 @@ __all__ = [
 # ---------------------------------------------------------------------------
 import random
 import string
-from collections.abc import Callable, Sequence
+from collections.abc import Callable, Iterable, Mapping, Sequence
 from datetime import datetime, timedelta
-from typing import Any, Literal, Self
+from typing import Any, Literal, Self, cast, override
 
 import numpy as np
 import pandas as pd
-
-try:
-    from typing import override  # type: ignore
-except ImportError:
-    from absfuyu.core.decorator import dummy_decorator as override
+from xlsxwriter import Workbook
+from xlsxwriter.worksheet import Worksheet
 
 from absfuyu.core.baseclass import GetClassMembersMixin
-from absfuyu.core.docstring import deprecated, versionadded
+from absfuyu.core.docstring import deprecated, versionadded, versionchanged
+from absfuyu.core.dummy_func import unidecode
 from absfuyu.extra.da.dadf_base import CityData
 from absfuyu.extra.da.dadf_base import DataAnalystDataFrameBase as DFBase
 from absfuyu.extra.da.dadf_base import SplittedDF
-from absfuyu.logger import logger
 from absfuyu.typings import R as _R
 from absfuyu.typings import T as _T
 from absfuyu.util import set_min_max
@@ -59,6 +57,8 @@ class DataAnalystDataFrameColumnMethodMixin(DFBase):
     - Drop rightmost column
     - Add blank column
     - Split str column
+    - Get column name unidecoded
+    - Get column unidecoded
     """
 
     def rearrange_rightmost_column(
@@ -135,8 +135,8 @@ class DataAnalystDataFrameColumnMethodMixin(DFBase):
             try:
                 self.drop(columns=[column], inplace=True)
             except KeyError:
-                logger.debug(f"{column} column does not exist")
-                # pass
+                # logger.debug(f"{column} column does not exist")
+                pass
         return self
 
     def drop_rightmost(self, num_of_cols: int = 1) -> Self:
@@ -183,7 +183,9 @@ class DataAnalystDataFrameColumnMethodMixin(DFBase):
     @deprecated("5.1.0", reason="Use pd.DataFrame.assign(...) method instead")
     def add_blank_column(self, column_name: str, fill: Any = np.nan, /) -> Self:
         """
-        Add a blank column
+        [DEPRECATED] Add a blank column.
+
+        E.g: Use `pd.DataFrame.assign(new_col=lambda x: x['old_col'])` instead
 
         Parameters
         ----------
@@ -246,14 +248,75 @@ class DataAnalystDataFrameColumnMethodMixin(DFBase):
         """
         if n is None:
             pass
-        splited_data: pd.DataFrame = self[col].str.split(
-            pat=pattern, n=n, expand=True, regex=regex
-        )
+        splited_data: pd.DataFrame = self[col].str.split(pat=pattern, n=n, expand=True, regex=regex)  # type: ignore
         num_of_splitted_cols = splited_data.shape[1]
         new_col_names = [f"{col}_{x}" for x in range(num_of_splitted_cols)]
         self[new_col_names] = splited_data
         return self
 
+    @versionadded("5.12.0")  # No test cases
+    def get_column_name_unidecoded(self, col_name: str, /, *, mode: Literal["start", "end", "in"] = "start") -> str:
+        """
+        Get column name from lowercase unidecode'd version name
+
+        Parameters
+        ----------
+        col_name : str
+            Column name to find
+
+        mode : Literal["start", "end", "in"], optional
+            Which mode to find, by default "start"
+            - "start": str.startswith()
+            - "end": str.endswith()
+            - "in": if x in y
+
+        Returns
+        -------
+        str
+            Column name
+
+        Raises
+        ------
+        ValueError
+            Column not found
+        """
+        for x in self.columns.to_list():
+            col_name_mod = cast(str, unidecode(x.strip().lower()))
+            if mode == "start":
+                if col_name_mod.startswith(col_name):
+                    return x
+            elif mode == "end":
+                if col_name_mod.endswith(col_name):
+                    return x
+            elif mode == "in":
+                if col_name_mod in col_name:
+                    return x
+
+        raise ValueError(f"Column not found: {col_name}")
+
+    @versionadded("5.12.0")  # No test cases
+    def get_column_unidecoded(self, col_name: str, /, *, mode: Literal["start", "end", "in"] = "start") -> pd.Series:
+        """
+        Get column from lowercase unidecode'd version column name
+
+        Parameters
+        ----------
+        col_name : str
+            Column name to find
+
+        mode : Literal["start", "end", "in"], optional
+            Which mode to find, by default "start"
+            - "start": str.startswith()
+            - "end": str.endswith()
+            - "in": if x in y
+
+        Returns
+        -------
+        Series
+            Column data
+        """
+        return self[self.get_column_name_unidecoded(col_name, mode=mode)]
+
 
 # Row method
 # ---------------------------------------------------------------------------
@@ -262,6 +325,7 @@ class DataAnalystDataFrameRowMethodMixin(DFBase):
     Data Analyst ``pd.DataFrame`` - Row method
 
     - Get different rows
+    - Add blank row
     """
 
     @versionadded("4.0.0")
@@ -297,6 +361,190 @@ class DataAnalystDataFrameRowMethodMixin(DFBase):
         )
         return self.__class__(out)
 
+    @versionchanged("6.1.3", reason="Reverted back to original logic")
+    @versionchanged("6.0.0", reason="Improved logic")
+    @versionadded("5.7.0")
+    def add_blank_row(self, fill: Any = np.nan, /) -> Self:
+        """
+        Add a new row to the end of a DataFrame.
+
+        Parameters
+        ----------
+        fill : Any, default np.nan
+            Value to fill in the new row (e.g., np.nan, None, "", 0).
+
+        Returns
+        -------
+        Self
+            DataFrame with the new row appended.
+        """
+        # Create a dict with all columns filled with fill
+        new_row = {col: fill for col in self.columns}
+        self.loc[len(self)] = new_row  # type: ignore
+        return self
+
+    @versionadded("6.1.3")
+    def add_blank_row2(self, fill: Any = np.nan, /) -> Self:
+        """
+        Add a new row to the end of a DataFrame.
+        (Improved version - but not working right now)
+
+        Parameters
+        ----------
+        fill : Any, default np.nan
+            Value to fill in the new row (e.g., np.nan, None, "", 0).
+
+        Returns
+        -------
+        Self
+            DataFrame with the new row appended.
+        """
+        # Create a dict with all columns filled with fill
+        new_row = {col: fill for col in self.columns}
+        safe_types = self._safe_dtypes(self.dtypes)
+        blank_row_df = pd.DataFrame([new_row], columns=self.columns).astype(safe_types)
+
+        # self.loc[len(self)] = new_row  # type: ignore
+        # return self
+        out = cast(pd.DataFrame, pd.concat([self, blank_row_df], ignore_index=True))
+        return self.__class__(out)
+
+    @versionadded("6.0.0")  # Support
+    def _safe_dtypes(self, dtypes: pd.Series) -> dict[str, Any]:
+        """
+        Convert DataFrame dtypes into a safe mapping for operations involving
+        missing values (NA), especially during row insertion or concatenation.
+
+        This function is primarily used to prevent pandas errors when inserting
+        rows containing missing values (``NaN``) into columns with non-nullable
+        integer dtypes (e.g. ``int64``). Since standard NumPy integer dtypes do not
+        support missing values, they are converted to pandas' nullable integer
+        dtype (``Int64``).
+
+        All non-integer dtypes are preserved without modification.
+
+        - Pandas nullable integer dtypes (``Int64``, ``Int32``, etc.) allow missing
+        values via ``pd.NA``, unlike NumPy integer dtypes.
+        - This function is commonly used before calling ``DataFrame.astype`` to
+        avoid ``IntCastingNaNError`` when NA values are present.
+        - The function does **not** modify floating-point, boolean, datetime,
+        categorical, or object dtypes.
+
+        Parameters
+        ----------
+        dtypes : Series
+            A Series mapping column names to their pandas dtypes, typically obtained
+            from ``DataFrame.dtypes``.
+
+        Returns
+        -------
+        dict
+            A dictionary mapping column names to safe dtypes. Integer dtypes are
+            converted to pandas nullable integer dtype (``"Int64"``), while all
+            other dtypes remain unchanged.
+
+
+        Example:
+        --------
+        Basic usage with a DataFrame::
+
+            >>> df.dtypes
+            id        int64
+            name     object
+            amount  float64
+            dtype: object
+
+            >>> _safe_dtypes(df.dtypes)
+            {
+                "id": "Int64",
+                "name": dtype("O"),
+                "amount": dtype("float64"),
+            }
+
+        Typical integration with ``astype``::
+
+            >>> safe_types = _safe_dtypes(df.dtypes)
+            >>> new_df = df.astype(safe_types)
+
+        This is especially useful when inserting rows with missing values::
+
+            >>> sep_row = {"id": pd.NA, "name": "---", "amount": pd.NA}
+            >>> sep_df = pd.DataFrame([sep_row]).astype(_safe_dtypes(df.dtypes))
+        """
+        out = {}
+        for col, dt in dtypes.items():
+            if pd.api.types.is_integer_dtype(dt):
+                out[col] = "Int64"  # nullable integer
+            else:
+                out[col] = dt
+        return out
+
+    @versionadded("6.0.0")  # Better version of add_blank_row()
+    def add_separator_row(
+        self,
+        group_cols: str | Iterable[str],
+        *,
+        separator: Mapping[str, object] | None = None,
+        drop_last: bool = True,
+    ) -> Self:
+        """
+        Insert a separator row after each group in a DataFrame.
+
+        Parameters
+        ----------
+        df : pandas.DataFrame
+            Input DataFrame (must be pre-sorted by ``group_cols``).
+
+        group_cols : str | Iterable[str]
+            Column(s) used to define grouping boundaries.
+
+        separator : Mapping[str, object] | None, optional
+            Custom separator row values (e.g. {"col": "---"}).
+            Columns not provided will be filled with NaN.
+            If None, a fully blank row is inserted.
+
+        drop_last : bool, optional
+            If True, do not insert a separator after the last group.
+
+        Returns
+        -------
+        Self
+            DataFrame with separator rows inserted.
+        """
+        df = self.copy()
+
+        if isinstance(group_cols, str):
+            group_cols = [group_cols]
+
+        # Validate columns
+        missing = set(group_cols) - set(df.columns)
+        if missing:
+            raise KeyError(f"Missing columns: {missing}")
+
+        # Build separator row template
+        if separator is None:
+            sep_row = {c: np.nan for c in df.columns}
+        else:
+            sep_row = {c: separator.get(c, np.nan) for c in df.columns}
+
+        rows = []
+
+        safe_types = self._safe_dtypes(df.dtypes)
+
+        # Group while preserving order
+        for _, g in df.groupby(group_cols, sort=False):
+            rows.append(g)
+
+            sep_df = pd.DataFrame([sep_row], columns=df.columns).astype(safe_types)
+            rows.append(sep_df)
+
+        out = cast(pd.DataFrame, pd.concat(rows, ignore_index=True))
+
+        if drop_last:
+            out = out.iloc[:-1].reset_index(drop=True)
+
+        return self.__class__(out)
+
 
 # Info
 # ---------------------------------------------------------------------------
@@ -342,7 +590,7 @@ class DataAnalystDataFrameInfoMixin(DFBase):
         return info
 
     @override
-    def describe(self, percentiles=None, include=None, exclude=None) -> Self:
+    def describe(self, percentiles=None, include=None, exclude=None) -> Self:  # type: ignore
         """pd.DataFrame.describe() override"""
         return self.__class__(super().describe(percentiles, include, exclude))  # type: ignore [no-any-return]
 
@@ -486,7 +734,7 @@ class DataAnalystDataFrameInfoMixin(DFBase):
         if top is not None:
             list_of_keep: list = (
                 col_df[destination_column]
-                .head(set_min_max(top - 1, min_value=1, max_value=col_df.shape[0]))
+                .head(set_min_max(top - 1, min_value=1, max_value=col_df.shape[0]))  # type: ignore
                 .to_list()
             )
             # logger.debug(list_of_keep)
@@ -561,7 +809,7 @@ class DataAnalystDataFrameNAMixin(DFBase):
         except KeyError:
             if getattr(self, "add_blank_column", None) is not None:
                 # Compatible with DataAnalystDataFrameColumnMethodMixin
-                self.add_blank_column(column_name, fill_when_not_exist)
+                self.add_blank_column(column_name, fill_when_not_exist)  # type: ignore
         return self
 
     def get_missing_values(
@@ -679,7 +927,7 @@ class DataAnalystDataFrameNAMixin(DFBase):
         3 -1.435079         400          400      REPLACED  ywahcasi 2024-05-20
         4  0.118993         861          800      REPLACED  saoupuby 2019-04-28
         """
-        self[col] = self[col].apply(lambda x: callable(x) if pd.notnull(x) else x)
+        self[col] = self[col].apply(lambda x: callable(x) if pd.notnull(x) else x)  # type: ignore
         return self
 
     @versionadded("5.1.0")  # type: ignore
@@ -750,7 +998,7 @@ class DataAnalystDataFrameNAMixin(DFBase):
 
         # Column name
         cname = "applied_row_null" if col_name is None else col_name
-        self[cname] = self.apply(apply_func, axis=1)
+        self[cname] = self.apply(apply_func, axis=1)  # type: ignore
 
         return self
 
@@ -825,7 +1073,7 @@ class DataAnalystDataFrameOtherMixin(DFBase):
 
             if getattr(self, "drop_columns", None) is not None:
                 # Compatible with DataAnalystDataFrameColumnMethodMixin
-                self.drop_columns(cols)
+                self.drop_columns(cols)  # type: ignore
 
         out = self.merge(other, how="left", on=on)
         return self.__class__(out)
@@ -935,19 +1183,19 @@ class DataAnalystDataFrameDateMixin(DFBase):
         col_counter = 0
         # self["weekday"] = self["day"].dt.isocalendar().day # Weekday
         if mode.find("d") != -1:
-            logger.debug("Mode: 'day'")
+            # logger.debug("Mode: 'day'")
             self["day"] = self["date"].dt.day
             col_counter += 1
         if mode.find("w") != -1:
-            logger.debug("Mode: 'weekday'")
+            # logger.debug("Mode: 'weekday'")
             self["week"] = self["date"].dt.isocalendar().week
             col_counter += 1
         if mode.find("m") != -1:
-            logger.debug("Mode: 'month'")
+            # logger.debug("Mode: 'month'")
             self["month"] = self["date"].dt.month
             col_counter += 1
         if mode.find("y") != -1:
-            logger.debug("Mode: 'year'")
+            # logger.debug("Mode: 'year'")
             self["year"] = self["date"].dt.year
             col_counter += 1
 
@@ -1017,6 +1265,172 @@ class DataAnalystDataFrameDateMixin(DFBase):
             )
         return self
 
+    @versionadded("6.0.0")
+    def normalize_datetime_column(
+        self,
+        col: str,
+        *,
+        inplace: bool = False,
+    ) -> Self:
+        """
+        Normalize a datetime column by removing the time component.
+
+        This function converts the specified column to pandas datetime (``datetime64[ns]``)
+        (if not already), then normalizes all values so that the time
+        component is set to ``00:00:00``. The date component is preserved.
+
+        The function safely handles missing or invalid values by coercing
+        them to ``NaT``.
+
+        Parameters
+        ----------
+        col : str
+            Name of the column to normalize. The column may contain
+            datetime-like values, strings, or mixed types.
+
+        inplace : bool, default False
+            | If ``True``, modify the input DataFrame in place.
+            | If ``False``, operate on a copy and return the modified DataFrame.
+
+        Returns
+        -------
+        Self
+            DataFrame with the normalized datetime column.
+
+
+        Example:
+        --------
+        Basic usage::
+
+            >>> df = DADF({
+            ...     "created_at": ["2024-01-01 10:15:30", "2024-01-02 23:59:59"]
+            ... })
+            >>> normalize_datetime_column(df, "created_at")
+            created_at
+            0 2024-01-01 00:00:00
+            1 2024-01-02 00:00:00
+
+        In-place modification::
+
+            >>> normalize_datetime_column(df, "created_at", inplace=True)
+
+        Handling invalid values::
+
+            >>> df = DADF({"dt": ["2024-01-01 10:00", "invalid"]})
+            >>> normalize_datetime_column(df, "dt")
+                    dt
+            0 2024-01-01 00:00:00
+            1                NaT
+
+        """
+        if not inplace:
+            df = self.copy()
+        else:
+            df = self
+
+        # Using ``df.loc[:, col]`` avoids ``SettingWithCopyWarning`` when the input DataFrame is a slice.
+        df.loc[:, col] = pd.to_datetime(df[col], errors="coerce").dt.normalize()
+        return df
+
+
+# Export
+# ---------------------------------------------------------------------------
+class DataAnalystDataFrameExportMixin(DFBase):
+    """
+    Data Analyst ``pd.DataFrame`` - Export method
+
+    - da_export
+    """
+
+    @versionchanged("5.8.0", "New parameter")
+    def da_export(
+        self,
+        path: str,
+        sheet_name: str = "Sheet1",
+        *,
+        auto_width: bool = True,
+        cols_contain_centered_text: list[str] | None = None,
+        cols_contain_number: list[str] | None = None,
+        cols_contain_percentage: list[str] | None = None,
+    ) -> None:
+        """
+        Export DataFrame with `xlsxwriter` engine
+
+        Parameters
+        ----------
+        path : Path | str
+            Path to export
+
+        sheet_name : str, optional
+            Sheet name, by default "Sheet1"
+
+        auto_width : bool, optional
+            Auto resize column width, by default ``True``
+
+        cols_contain_centered_text : list[str] | None, optional
+            Columns that contain centered text (Align center), by default None
+
+        cols_contain_number : list[str] | None, optional
+            Columns that contain number value (to format as number - int), by default None
+
+        cols_contain_percentage : list[str] | None, optional
+            Columns that contain percentage value (to format as percentage), by default None
+        """
+
+        # Using xlsxwriter engine
+        with pd.ExcelWriter(path, engine="xlsxwriter") as writer:
+            self.to_excel(writer, sheet_name=sheet_name, index=False, float_format="%.2f", na_rep="")
+
+            # Format style
+            workbook: Workbook = writer.book  # type: ignore
+            header_fmt = workbook.add_format(
+                {
+                    "bold": True,
+                    "text_wrap": True,
+                    "border": 1,
+                    "align": "center",
+                    "valign": "vcenter",
+                    # "bg_color": "#A0BEFD",
+                }
+            )
+            number_fmt = workbook.add_format(
+                {"num_format": "#,##0", "align": "center", "valign": "vcenter"}
+            )  # 1,000,000
+            percent_fmt = workbook.add_format({"num_format": "0.00%", "align": "center", "valign": "vcenter"})  # 1.00%
+            text_fmt = workbook.add_format({"valign": "vcenter"})
+            text_center_fmt = workbook.add_format({"align": "center", "valign": "vcenter"})
+
+            # Format sheet
+            worksheet: Worksheet = writer.sheets[sheet_name]
+
+            # Format header - First row
+            for col_num, value in enumerate(self.columns.values):
+                worksheet.write(0, col_num, value, header_fmt)
+
+            rules = [
+                (cols_contain_number, number_fmt),
+                (cols_contain_percentage, percent_fmt),
+                (cols_contain_centered_text, text_center_fmt),
+            ]
+
+            # Auto width + col format
+            for i, col in enumerate(self.columns):
+                # Max str len of each column
+                max_len = None if auto_width is None else max(self[col].astype(str).map(len).max(), len(col)) + 2
+                worksheet.set_column(i, i, max_len)  # Set width
+
+                # Format style
+                fmt = text_fmt  # default
+                for cols, f in rules:
+                    if cols is not None and col in cols:
+                        fmt = f
+                        break
+                worksheet.set_column(i, i, max_len, fmt)
+
+            # if cols_contain_number is not None:
+            #     for x in cols_contain_number:
+            #         self[x] = pd.to_numeric(self[x], errors="coerce")
+
 
 # City
 # ---------------------------------------------------------------------------
@@ -1068,13 +1482,13 @@ class DataAnalystDataFrameCityMixin(DFBase):
         # Convert
         col_counter = 0
         if mode.find("r") != -1:
-            logger.debug("Mode: 'region'")
+            # logger.debug("Mode: 'region'")
             self["region"] = self[city_column].apply(
                 lambda x: _convert_city_support(x).region
             )
             col_counter += 1
         if mode.find("a") != -1:
-            logger.debug("Mode: 'area'")
+            # logger.debug("Mode: 'area'")
             self["area"] = self[city_column].apply(
                 lambda x: _convert_city_support(x).area
             )
@@ -1091,6 +1505,7 @@ class DataAnalystDataFrameCityMixin(DFBase):
 class DADF(
     GetClassMembersMixin,
     DataAnalystDataFrameCityMixin,
+    DataAnalystDataFrameExportMixin,
     DataAnalystDataFrameDateMixin,
     DataAnalystDataFrameOtherMixin,
     DataAnalystDataFrameNAMixin,
@@ -1191,3 +1606,17 @@ class DADF_WIP(DADF):
     """
 
     pass
+
+if __name__ == "__main__":
+    from pathlib import Path
+
+    # t = DADF.sample_df().show_distribution("number_range", show_percentage=False)
+    # t.da_export(
+    #     Path(__file__).parent.joinpath("a.xlsx").resolve().__str__(),
+    #     cols_contain_number=["number_range"],
+    #     cols_contain_percentage=["percentage"],
+    # )
+    # print(t)
+
+    df = DADF.sample_df(10)
+    print(df.add_blank_row())

absfuyu/extra/da/dadf_base.py

@@ -3,8 +3,8 @@ Absfuyu: Data Analysis
 ----------------------
 Data Analyst DataFrame - Base/Core
 
-Version: 5.6.1
-Date updated: 12/09/2025 (dd/mm/yyyy)
+Version: 6.1.2
+Date updated: 30/12/2025 (dd/mm/yyyy)
 """
 
 # Module level