py2ls 0.2.5.14__py3-none-any.whl → 0.2.6.1__py3-none-any.whl

py2ls/ips.py

@@ -1,18 +1,18 @@
 from tkinter import FALSE
 import numpy as np
 import pandas as pd
-import sys
-import os
+import sys # built-in
+import os # built-in
 from IPython.display import display
 import shutil
 import logging
 from pathlib import Path
 from datetime import datetime, date, time 
-import re
+import re # built-in
 import stat
 import platform
 
-from typing import Dict, List, Optional, Union, Any, Tuple, Literal
+from typing import Dict, List, Optional, Union, Any, Tuple, Literal,Callable
 from regex import X
 
 try:
@@ -26,7 +26,218 @@ import warnings
 warnings.simplefilter("ignore", category=pd.errors.SettingWithCopyWarning)
 warnings.filterwarnings("ignore", category=pd.errors.PerformanceWarning)
 warnings.filterwarnings("ignore")
+try:
+    import pkg_resources
+except ImportError:
+    pkg_resources = None
+import glob  # built-in
+import pkg_resources # built-in
+class PkgManager:
+    """
+    PkgManager.uninstall("py2ls")
+    PkgManager.uninstall("py2ls", mode="startswith")
+    PkgManager.uninstall("py2ls", mode="endswith")
+    PkgManager.uninstall("py2ls", mode="contains")
+    PkgManager.uninstall("py2ls", mode="regex")
+
+    PkgManager.timemachine()
+    """
 
+    @staticmethod
+    def uninstall(
+        kw: Union[str, List[str]],
+        mode: str = "exact",
+        dry_run: bool = False,
+        make_backup: bool = True,
+        make_log: bool = True,
+        station: Optional[str] = None,
+    ) -> None:
+        if station is None:
+            station = os.path.dirname(os.path.dirname(sys.executable)) 
+        os.makedirs(station, exist_ok=True)
+        timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
+
+        if isinstance(kw, str):
+            kw = [kw]
+        kw = [k.lower() for k in kw] if mode != "regex" else kw
+        mode = mode.lower()
+        valid_modes = {"exact", "startswith", "endswith", "contains", "regex"}
+        if mode not in valid_modes:
+            raise ValueError(f"Mode must be one of {valid_modes}")
+
+        installed_packages = {pkg.key: pkg.version for pkg in pkg_resources.working_set}
+        matched: Set[str] = set()
+
+        for name in installed_packages:
+            for key in kw:
+                if (
+                    (mode == "exact" and name == key)
+                    or (mode == "startswith" and name.startswith(key))
+                    or (mode == "endswith" and name.endswith(key))
+                    or (mode == "contains" and key in name)
+                    or (mode == "regex" and re.search(key, name))
+                ):
+                    matched.add(name)
+                    break
+
+        if not matched:
+            print("No packages matched the criteria.")
+            return
+
+        if make_backup and not dry_run:
+            backup_path = os.path.join(station, f"requirements_backup_{timestamp}.txt")
+            with open(backup_path, "w") as f:
+                subprocess.run(["pip", "freeze"], stdout=f, check=True)
+            print(f"Backup created at: '{backup_path}'")
+
+        if dry_run:
+            print("[DRY RUN] The following packages would be uninstalled:")
+            for pkg in sorted(matched):
+                print(f"  - {pkg}=={installed_packages[pkg]}")
+            return
+
+        print(f"[UNINSTALLING] {len(matched)} packages:")
+        for pkg in sorted(matched):
+            print(f"  - {pkg}=={installed_packages[pkg]}")
+            subprocess.run(["pip", "uninstall", "-y", pkg], check=True)
+
+        if make_log:
+            log_path = os.path.join(station, f"uninstall_{timestamp}.txt")
+            with open(log_path, "w") as f:
+                f.write(f"# Uninstallation log created at {timestamp}\n")
+                f.write(f"# Mode: {mode}, Keywords: {kw}\n\n")
+                for pkg in sorted(matched):
+                    f.write(f"{pkg}=={installed_packages[pkg]}\n")
+            print(f"Log written to '{log_path}'")
+
+    @staticmethod
+    def list_backups(station: Optional[str] = None) -> List[str]:
+        if station is None:
+            station = os.path.dirname(sys.executable)
+            if os.name == "nt":
+                station = os.path.dirname(station)
+        return sorted(glob.glob(os.path.join(station, "requirements_backup_*.txt")))
+
+    @staticmethod
+    def list_logs(station: Optional[str] = None) -> List[str]:
+        if station is None:
+            station = os.path.dirname(sys.executable)
+            if os.name == "nt":
+                station = os.path.dirname(station)
+        return sorted(glob.glob(os.path.join(station, "uninstall_*.txt")))
+
+    @staticmethod
+    def restore(
+        timestamp: Optional[str] = None,
+        station: Optional[str] = None,
+        dry_run: bool = False,
+    ) -> None:
+        if station is None:
+            station = os.path.dirname(sys.executable)
+            if os.name == "nt":
+                station = os.path.dirname(station)
+
+        backups = PkgManager.list_backups(station)
+        logs = PkgManager.list_logs(station)
+
+        if not timestamp:
+            print("Available restore points:\n\nBackups:")
+            for i, backup in enumerate(backups, 1):
+                ts = os.path.basename(backup)[18:-4]
+                print(f"  {i}. {ts} (backup)")
+            print("\nUninstall logs:")
+            for i, log in enumerate(logs, len(backups) + 1):
+                ts = os.path.basename(log)[10:-4]
+                print(f"  {i}. {ts} (log)")
+            print("\nSpecify timestamp or selection number to restore.")
+            return
+
+        try:
+            selection = int(timestamp)
+            all_files = backups + logs
+            if 1 <= selection <= len(all_files):
+                file_path = all_files[selection - 1]
+                is_log = selection > len(backups)
+            else:
+                raise ValueError("Invalid selection number")
+        except ValueError:
+            backup_pattern = os.path.join(
+                station, f"requirements_backup_{timestamp}.txt"
+            )
+            log_pattern = os.path.join(station, f"uninstall_{timestamp}.txt")
+            matching_backups = glob.glob(backup_pattern)
+            matching_logs = glob.glob(log_pattern)
+
+            if matching_backups:
+                file_path = matching_backups[0]
+                is_log = False
+            elif matching_logs:
+                file_path = matching_logs[0]
+                is_log = True
+            else:
+                print(f"No backup or log found for timestamp: {timestamp}")
+                return
+
+        with open(file_path, "r") as f:
+            packages = [
+                line.strip() for line in f if line.strip() and not line.startswith("#")
+            ]
+
+        if dry_run:
+            print(
+                f"[DRY RUN] Would restore {len(packages)} packages from:\n  {file_path}"
+            )
+            for pkg in packages:
+                print(f"  - {pkg}")
+            return
+
+        print(f"[RESTORING] {len(packages)} packages from:\n  {file_path}")
+        for pkg in packages:
+            print(f"  - Installing {pkg}")
+            subprocess.run(["pip", "install", pkg], check=True)
+
+    @staticmethod
+    def timemachine(station: Optional[str] = None) -> None:
+        if station is None:
+            station = os.path.dirname(sys.executable)
+            if os.name == "nt":
+                station = os.path.dirname(station)
+
+        backups = PkgManager.list_backups(station)
+        logs = PkgManager.list_logs(station)
+
+        if not backups and not logs:
+            print("No backup or log files found.")
+            return
+
+        print("\nTime Machine - Available Restore Points:")
+        print("--------------------------------------")
+        print("\nBackups (complete environment snapshots):")
+        for i, backup in enumerate(backups, 1):
+            ts = os.path.basename(backup)[18:-4]
+            print(f"  {i}. {ts}")
+        print("\nUninstall Logs (specific package lists):")
+        for i, log in enumerate(logs, len(backups) + 1):
+            ts = os.path.basename(log)[10:-4]
+            print(f"  {i}. {ts}")
+        print("\n0. Exit Time Machine")
+
+        while True:
+            try:
+                choice = input("\nSelect a restore point (number) or '0' to exit: ")
+                if choice == "0":
+                    return
+                selection = int(choice)
+                all_files = backups + logs
+                if 1 <= selection <= len(all_files):
+                    file_path = all_files[selection - 1]
+                    timestamp = os.path.basename(file_path).split("_")[-1][:-4]
+                    PkgManager.restore(timestamp, station)
+                    return
+                else:
+                    print("Invalid selection. Please try again.")
+            except ValueError:
+                print("Please enter a valid number.")
 
 def _yaoshi_fernet(mima="mimashigudingde",yan=b"mimashigudingde",verbose=True):
     import base64
@@ -5688,7 +5899,7 @@ def fload(fpath, kind=None, **kwargs):
         if output in ["dataframe", "df"]:
             if verbose:
                 print("loading data as a DataFrame")
-            if not password:
+            if not bool(password):
                 if verbose:
                     print("Reading Excel without password protection...")
                 df = pd.read_excel(fpath, engine=engine, sheet_name=sheet_name, **kwargs)
@@ -6636,27 +6847,6 @@ def fsave(
             print(
                 f"Error:\n{kind} is not in the supported list ['docx', 'txt', 'md', 'html', 'pdf', 'csv', 'xlsx', 'json', 'xml', 'yaml']"
             )
-
-
-# # Example usage
-# text_content = ["Hello, this is a sample text file.", "This is the second paragraph."]
-# tabular_content = {"Name": ["Alice", "Bob"], "Age": [24, 30]}
-# json_content = {"name": "Alice", "age": 24}
-# yaml_content = {"Name": "Alice", "Age": 24}
-# xml_content = {"Name": "Alice", "Age": 24}
-# dir_save = "/Users/macjianfeng/Dropbox/Downloads/"
-# fsave(dir_save + "sample.txt", text_content)
-# fsave(dir_save + "sample.md", text_content)
-# fsave(dir_save + "sample.html", text_content)
-# fsave(dir_save + "sample.pdf", text_content)
-# fsave(dir_save + "sample.docx", text_content)
-# fsave(dir_save + "sample.csv", tabular_content, index=False)
-# fsave(dir_save + "sample.xlsx", tabular_content, sheet_name="Sheet1", index=False)
-# fsave(dir_save + "sample.json", json_content, indent=4)
-# fsave(dir_save + "sample.yaml", yaml_content)
-# fsave(dir_save + "sample.xml", xml_content)
-
-
 def addpath(fpath):
     sys.path.insert(0, dir)
 
@@ -9410,12 +9600,6 @@ def thumbnail(dir_img_list, figsize=(10, 10), dpi=100, dir_save=None, kind=".png
         else:
             figsave(dirname(dir_save), fname)
 
-
-# usage:
-# fpath = "/Users/macjianfeng/Dropbox/github/python/py2ls/tests/xample_netfinder/images/"
-# thumbnail(listdir(fpath,'png').fpath.to_list(),dir_save=dirname(fpath))
-
-
 # search and fine the director of the libary, which installed at local
 def dir_lib(lib_oi):
     """
@@ -9832,7 +10016,7 @@ def hex2argb(color):
     
     # Validate hex format
     if not re.fullmatch(r"[A-F0-9]{6,8}", color):
-        raise ValueError(f"格式错误❌: {color}, 应该使用 RRGGBB, #RRGGBB, or aARRGGBB format.")
+        raise ValueError(f"格式错误: {color}, 应该使用 RRGGBB, #RRGGBB, or aARRGGBB format.")
 
     # If already in aARRGGBB format (8 chars), return as is
     if len(color) == 8:
@@ -10032,7 +10216,526 @@ def copy_format(
             wb_source.close()
         if "wb_target" in locals():
             wb_target.close()
+# ! =========(below) interact with worrkbook and DataFrame=========== 
+import pandas as pd
+from openpyxl import load_workbook 
+from openpyxl.workbook.workbook import Workbook 
+from openpyxl.utils import get_column_letter 
+
+class DataFrameAlignExcel:
+    """
+    A powerful tool for updating Excel files with data from DataFrames with various matching strategies.
+
+    Features:
+    - Accepts either file path or open Workbook object
+    - Multiple matching strategies (exact, contains, starts_with, ends_with, regex)
+    - Multiple value update strategies (overwrite, add, subtract, multiply, divide, append)
+    - Support for multiple worksheets
+    - Automatic column creation
+    - Value normalization options
+    - Detailed logging and dry-run mode
+    - Progress reporting
+    - Data validation
+    - make_backup functionality
+    """
+
+    def __init__(self, fpath: Union[str, Workbook], df: pd.DataFrame = None):
+        """
+        Initialize the DataFrameAlignExcel.
+
+        Args:
+            fpath: Path to the Excel file (str) or open Workbook object
+            df: Optional DataFrame to use for updates
+        """
+        self.fpath_or_wb = fpath
+        self.df = df
+        self.wb = None
+        self.backup_path = None
+        self.log = []
+        self.owns_workbook = (
+            False  # Track whether we created the workbook or it was passed in
+        )
+
+    def load_workbook(self) -> None:
+        """Load the Excel workbook if a path was provided."""
+        if isinstance(self.fpath_or_wb, str):
+            if not os.path.exists(self.fpath_or_wb):
+                raise FileNotFoundError(f"Excel file not found: {self.fpath_or_wb}")
+            self.wb = load_workbook(self.fpath_or_wb)
+            self.owns_workbook = True
+        elif isinstance(self.fpath_or_wb, Workbook):
+            self.wb = self.fpath_or_wb
+            self.owns_workbook = False
+        else:
+            raise TypeError(
+                "fpath must be either a string path or an openpyxl Workbook object"
+            )
+
+    def create_make_backup(self) -> None:
+        """Create a make_backup of the original Excel file (only if we loaded from a file)."""
+        if not isinstance(self.fpath_or_wb, str):
+            self.log.append(
+                "Skipping make_backup - working with Workbook object directly"
+            )
+            return
+
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        self.backup_path = os.path.join(
+            os.path.dirname(self.fpath_or_wb),
+            f"backup_{timestamp}_{os.path.basename(self.fpath_or_wb)}",
+        )
+        self.wb.save(self.backup_path)
+        self.log.append(f"Created make_backup at: {self.backup_path}")
+
+    def save_workbook(self, dir_save: str = None) -> None:
+        """
+        Save the workbook to a file.
+
+        Args:
+            dir_save: Optional path to save to. If None and we loaded from a file,
+                       saves to the original path.
+        """
+        if self.wb is None:
+            raise ValueError("No workbook loaded")
+
+        if dir_save is None:
+            if isinstance(self.fpath_or_wb, str):
+                dir_save = self.fpath_or_wb
+            else:
+                dir_save = datetime.now().strftime("%Y%m%d_%H%M%S") + ".xlsx"
+                print(
+                    f"No save path provided and original input was a Workbook object, so used : {dir_save}"
+                )
+            self.wb.save(dir_save)
+            self.log.append(f"Saved workbook to: {dir_save}")
+
+    def normalize_value(self, value, clean_keys: str = "strip_split_first") -> str:
+        """
+        Normalize a value based on the specified method.
+
+        Args:
+            value: Value to normalize
+            clean_keys: One of:
+                - 'strip': just strip whitespace
+                - 'strip_lower': strip and lowercase
+                - 'strip_split_first': strip and take first part before comma
+                - 'strip_split_last': strip and take last part after comma
+                - None: no normalization
+
+        Returns:
+            Normalized value
+        """
+        if value is None:
+            return None
+
+        value = str(value)
+
+        if clean_keys is None:
+            return value
+
+        if clean_keys == "strip":
+            return value.strip()
+        elif clean_keys == "strip_lower":
+            return value.strip().lower()
+        elif clean_keys == "strip_split_first":
+            return value.strip().split(",")[0].strip()
+        elif clean_keys == "strip_split_last":
+            parts = value.strip().split(",")
+            return parts[-1].strip() if len(parts) > 1 else value.strip()
+        else:
+            warnings.warn(f"Unknown clean_keys: {clean_keys}. Using 'strip'.")
+            return value.strip()
+
+    def find_column_index(self, ws, header_row: int, column_name: str, max_search_columns: int = 100) -> int:
+        """
+        Efficiently find the column index (1-based) for a given column name,
+        considering only non-empty cells and limiting search range.
+
+        Args:
+            ws: Worksheet object
+            header_row: Row number containing headers (1-based)
+            column_name: Column name to find
+            max_search_columns: Max number of columns to search (to prevent infinite loops)
+
+        Returns:
+            Column index (1-based), or -1 if not found
+        """
+        row_iter = ws.iter_rows(min_row=header_row, max_row=header_row, max_col=max_search_columns, values_only=False)
+        for row in row_iter:
+            for cell in row:
+                if cell.value and str(cell.value).strip().lower() == column_name.lower():
+                    return cell.column
+            break  # Only process the header row
+        return -1
+    # def find_column_index(self, ws, header_row: int, column_name: str, max_search_columns: int = 100) -> int:
+    #     """
+    #     Find the column index (1-based) for a given column name.
+    #     If not found, return the last non-empty header column index.
+
+    #     Args:
+    #         ws: Worksheet object
+    #         header_row: Row number containing headers (1-based)
+    #         column_name: Column name to find
+    #         max_search_columns: Max number of columns to search
+
+    #     Returns:
+    #         Column index (1-based)
+    #     """
+    #     row_iter = ws.iter_rows(min_row=header_row, max_row=header_row, max_col=max_search_columns, values_only=False)
+    #     last_non_empty_col = -1
+
+    #     for row in row_iter:
+    #         for cell in row:
+    #             if cell.value and str(cell.value).strip():
+    #                 last_non_empty_col = cell.column
+    #                 if str(cell.value).strip().lower() == column_name.lower():
+    #                     return cell.column
+    #         break  # Only one row being read
+
+    #     return last_non_empty_col
+
+    def update_values(
+        self,
+        df: pd.DataFrame = None,
+        sheet_name: Union[str, int, List[Union[str, int]]] = 0,
+        header_row: int = 1,
+        column_match: Union[Dict[str, str], List[Tuple[str, str]]] = None,
+        column_mapping: Union[Dict[str, str], List[Tuple[str, str]]] = None,
+        clean_keys: str = "strip_split_first",
+        match_method: str = "exact",
+        update_strategy: str = "overwrite",
+        create_missing_columns: bool = True,
+        preview_only: bool = False,
+        show_progress: bool = True,
+        skip_no_match: bool = True,
+        make_backup: bool = True,
+        dir_save: str = None,
+        row_max=500
+    ) -> Dict[str, int]:
+        """
+        Update Excel with values from DataFrame.
+
+        Args:
+            df: DataFrame containing update data (if None, uses self.df)
+            sheet_name: Sheet name(s) to update (str, int, or list of these)
+            header_row: Row number containing headers (1-based)
+            column_match: Dict or list of tuples mapping DataFrame columns to Excel columns for matching
+                          e.g., {'SampleID': 'ID'} or [('SampleID', 'ID'), ('Batch', 'Lot')]
+            column_mapping: Dict or list of tuples mapping DataFrame columns to Excel columns to update
+                          e.g., {'Vials': 'Qty'} or [('Vials', 'Qty'), ('Status', 'State')]
+            clean_keys: How to normalize matching values (see normalize_value())
+            match_method: How to match values ('exact', 'contains', 'starts_with', 'ends_with', 'regex')
+            update_strategy: How to update values ('overwrite', 'add', 'subtract', 'multiply', 'divide', 'append')
+            create_missing_columns: Whether to create columns that don't exist
+            preview_only: If True, don't actually update the Excel file
+            show_progress: If True, print progress updates
+            skip_no_match: If True, skip rows where match columns don't match
+            make_backup: If True, create a make_backup before updating (only if working with file path)
+            dir_save: Optional path to save to. If None and we loaded from a file,
+                      saves to the original path. Ignored if preview_only=True.
+
+        Returns:
+            Dictionary with update statistics
+        """
+        # Initialize
+        start_time = datetime.now()
+        if df is None:
+            df = self.df
+        if df is None:
+            raise ValueError("No DataFrame provided")
+
+        if not isinstance(column_match, (dict, list)) or not column_match:
+            raise ValueError(
+                "column_match must be a non-empty dict or list of tuples"
+            )
+
+        if not isinstance(column_mapping, (dict, list)) or not column_mapping:
+            raise ValueError("column_mapping must be a non-empty dict or list of tuples")
+
+        # Convert match/update columns to consistent format
+        if isinstance(column_match, dict):
+            column_match = list(column_match.items())
+        if isinstance(column_mapping, dict):
+            column_mapping = list(column_mapping.items())
+
+        # Load workbook if not already loaded
+        if self.wb is None:
+            self.load_workbook()
+
+        # Create make_backup (only if we're working with a file path)
+        if not preview_only:
+            self.create_make_backup()
+
+        # Prepare statistics
+        stats = {
+            "processed_sheet_names":[],
+            "processed_sheets": 0,
+            "total_updates": 0,
+            "skipped_rows": 0,
+            "created_columns": 0,
+        }
+
+        # Normalize sheet names
+        if not isinstance(sheet_name, list):
+            sheet_name = [sheet_name]
+
+        # Process each sheet
+        for sheet in sheet_name:
+            try:
+                if isinstance(sheet, str):
+                    ws = self.wb[sheet]
+                elif isinstance(sheet, int):
+                    ws = self.wb.worksheets[sheet]
+                else:
+                    ws = self.wb.active
+
+                sheet_name = ws.title
+                self.log.append(f"\nProcessing sheet: {sheet_name}")
+
+                # Prepare matching data
+                match_dict = {}
+                for df_col, excel_col in column_match:
+                    if clean_keys:
+                        match_dict[excel_col] = dict(
+                            zip(
+                                df[df_col].apply(
+                                    lambda x: self.normalize_value(x, clean_keys)
+                                ),
+                                df.index,
+                            )
+                        )
+                    else:
+                        match_dict[excel_col] = dict(zip(df[df_col], df.index))
+
+                # Find or create update columns
+                update_col_indices = {}
+                for df_col, excel_col in column_mapping: 
+                    col_idx = self.find_column_index(ws, header_row, excel_col)
+                    if col_idx == -1:
+                        if create_missing_columns:
+                            # Find last column
+                            last_col = max(
+                                [cell.column for cell in ws[header_row] if cell.value is not None], default=0
+                            )
+                            col_idx = last_col + 1
+                            ws.cell(row=header_row, column=col_idx, value=excel_col)
+                            update_col_indices[excel_col] = col_idx
+                            stats["created_columns"] += 1
+                            self.log.append(
+                                f"Created new column '{excel_col}' at position {col_idx}"
+                            )
+                        else:
+                            raise ValueError(
+                                f"Column '{excel_col}' not found and create_missing_columns=False"
+                            )
+                    else:
+                        update_col_indices[excel_col] = col_idx
+
+                # Process rows 
+                for row in ws.iter_rows(min_row=header_row + 1): 
+                    match_values = {}
+                    match_failed = False
+
+                    for excel_col in match_dict.keys():
+                        col_idx = self.find_column_index(ws, header_row, excel_col)
+                        if col_idx == -1:
+                            if skip_no_match:
+                                match_failed = True
+                                break
+                            else:
+                                raise ValueError(
+                                    f"Match column '{excel_col}' not found in sheet"
+                                )
+
+                        cell_value = row[
+                            col_idx - 1
+                        ].value  # -1 because iter_rows returns 0-based list
+                        if clean_keys:
+                            cell_value = self.normalize_value(cell_value, clean_keys)
+
+                        match_values[excel_col] = cell_value
+
+                    if match_failed:
+                        stats["skipped_rows"] += 1
+                        continue
+
+                    # Find matching DataFrame row
+                    df_index = None
+                    for excel_col, value in match_values.items():
+                        if value in match_dict[excel_col]:
+                            if df_index is None:
+                                df_index = match_dict[excel_col][value]
+                            elif df_index != match_dict[excel_col][value]:
+                                # Multiple match columns point to different rows - skip
+                                df_index = None
+                                break
+
+                    if df_index is None:
+                        stats["skipped_rows"] += 1
+                        continue
+
+                    # Update cells
+                    for df_col, excel_col in column_mapping:
+                        col_idx = update_col_indices[excel_col]
+                        cell = row[
+                            col_idx - 1
+                        ]  # -1 because iter_rows returns 0-based list
+                        new_value = df.at[df_index, df_col]
+
+                        # Apply update strategy
+                        if update_strategy == "overwrite":
+                            cell.value = new_value
+                        elif update_strategy in (
+                            "add",
+                            "subtract",
+                            "multiply",
+                            "divide",
+                        ):
+                            try:
+                                old_value = (
+                                    float(cell.value) if cell.value is not None else 0
+                                )
+                                new_value = (
+                                    float(new_value) if new_value is not None else 0
+                                )
+                                if update_strategy == "add":
+                                    cell.value = old_value + new_value
+                                elif update_strategy == "subtract":
+                                    cell.value = old_value - new_value
+                                elif update_strategy == "multiply":
+                                    cell.value = old_value * new_value
+                                elif update_strategy == "divide":
+                                    cell.value = (
+                                        old_value / new_value
+                                        if new_value != 0
+                                        else old_value
+                                    )
+                            except (ValueError, TypeError):
+                                if skip_no_match:
+                                    continue
+                                raise ValueError(
+                                    f"Could not perform {update_strategy} operation on non-numeric values"
+                                )
+                        elif update_strategy == "append":
+                            separator = ", " if cell.value else ""
+                            cell.value = (
+                                f"{cell.value}{separator}{new_value}"
+                                if cell.value
+                                else new_value
+                            )
+                        else:
+                            raise ValueError(
+                                f"Unknown update_strategy: {update_strategy}"
+                            )
+
+                        stats["total_updates"] += 1
+
+                stats["processed_sheets"] += 1
+                stats["processed_sheet_names"].append(sheet_name)
+            except Exception as e:
+                self.log.append(f"Error processing sheet {sheet}: {str(e)}")
+                if (
+                    not preview_only
+                    and self.backup_path
+                    and isinstance(self.fpath_or_wb, str)
+                ):
+                    self.log.append("Restoring from make_backup due to error")
+                    self.wb = load_workbook(self.backup_path)
+                raise
+
+        # Save changes if not dry run
+        if not preview_only:
+            self.save_workbook(dir_save)
+            if not make_backup:
+                if os.path.exists(self.backup_path):
+                    os.remove(self.backup_path)
+        else:
+            self.log.append("\nDry run complete - no changes saved") 
+
+        # Print summary
+        summary = (
+            f"\nUpdate Summary:\n"
+            f"\tProcessed {stats["processed_sheets"]} sheetnames: {stats['processed_sheet_names']}\n"
+            f"\tTotal updates: {stats['total_updates']}\n"
+            f"\tSkipped rows: {stats['skipped_rows']}\n" 
+        )
+        self.log.append(summary)
+
+        if show_progress:
+            print(summary)
 
+        return stats
+
+    def get_log(self) -> str:
+        """Get the operation log as a string."""
+        return "\n".join(self.log)
+
+    def close(self) -> None:
+        """Close the workbook if we own it."""
+        if self.wb is not None and self.owns_workbook:
+            self.wb.close()
+            self.wb = None
+
+
+DFToExcelMapping = Union[Dict[str, str], List[Tuple[str, str]]]
+def df_align(
+    fpath: Union[str, Workbook],
+    df: pd.DataFrame,
+    sheet_name: Union[str, int, List[Union[str, int]]] = 0,
+    header_row: int = 1,
+    column_match: DFToExcelMapping = None,
+    column_mapping: DFToExcelMapping = None,
+    clean_keys: str = "strip_split_first",
+    match_method: str = "exact",
+    update_strategy: str = "overwrite",
+    create_missing_columns: bool = True,
+    preview_only: bool = False,
+    show_progress: bool = True,
+    skip_no_match: bool = True,
+    make_backup: bool = True,
+    dir_save: str = None,
+) -> Dict[str, int]:
+    """
+    wb = fload(
+        dir_aml,
+        password="XBuzwVk4xsC2361cHzyi9JFgfJHaTSerjBOQ0JAJU24=",
+        sheet_name=0,
+        header=1,
+        output="bit",
+    )
+    ws = wb[wb.sheetnames[0]]
+    df_align(
+        fpath=wb,
+        df=df_,
+        sheet_name=None,
+        header_row=2,
+        column_match={"SampleID": "SampleID"},# key是 df中的列名, value是 excel中,
+        column_mapping={"Vials": "Vials", "Vials_": "Total Vials"}, # key是 df中的列名, value是 excel中,
+    )
+    """
+    updater = DataFrameAlignExcel(fpath, df)
+    try:
+        result = updater.update_values(
+            sheet_name=sheet_name,
+            header_row=header_row,
+            column_match=column_match,
+            column_mapping=column_mapping,
+            clean_keys=clean_keys,
+            match_method=match_method,
+            update_strategy=update_strategy,
+            create_missing_columns=create_missing_columns,
+            preview_only=preview_only,
+            show_progress=show_progress,
+            skip_no_match=skip_no_match,
+            make_backup=make_backup,
+            dir_save=dir_save,
+        )
+        return result
+    finally:
+        updater.close()
+
+
+# ! =========(Above) interact with worrkbook and DataFrame===========
 def set_sheet_visible(
     fpath: str,
     sheet_name: Union[int, str, None,list] = 1,
@@ -10159,7 +10862,7 @@ def format_excel(
     number_format:dict=None,  # dict: e.g., {1:"0.00", 2:"#,##0",3:"0%",4:"$#,##0.00"}
     data_validation=None,  # dict
     template:dict={},# e.g., template=dict(path="xx.xlsx",sheet_name=['sheet_name1',"sheet_name2"])
-    apply_filter:bool=True, # add filter 
+    apply_filter:bool=False, # add filter 
     freeze :str= False,#"A2",
     conditional_format:dict=None,  # dict
     verbose:bool=False,
@@ -10321,6 +11024,67 @@ def format_excel(
             if end_col_letter
             else f"{start_col_letter}{start_row}"
         )
+
+
+    def is_merged_cell(ws, cell):
+        """Check if a cell is part of any merged range."""
+        for merged_range in ws.merged_cells.ranges:
+            if cell.coordinate in merged_range:
+                return True
+        return False
+
+    def apply_auto_width(ws, width_factor=1.2, width_padding=2, width_max=50):
+        """
+        Automatically adjust column widths based on content length,
+        with complete protection against merged cell errors.
+        
+        Args:
+            ws: Worksheet object
+            width_factor: Multiplier for content length (default 1.2)
+            width_padding: Additional padding (default 2)
+            width_max: Maximum column width (default 50)
+        """
+        # First build a set of all merged cell coordinates
+        merged_coords = set()
+        for merged_range in ws.merged_cells.ranges:
+            for row in ws.iter_rows(min_row=merged_range.min_row,
+                                max_row=merged_range.max_row,
+                                min_col=merged_range.min_col,
+                                max_col=merged_range.max_col):
+                for cell in row:
+                    merged_coords.add(cell.coordinate)
+        
+        for col in ws.columns:
+            if not col:
+                continue
+                
+            col_letter = get_column_letter(col[0].column)
+            max_length = 0
+            
+            for cell in col:
+                # Skip merged cells entirely
+                if cell.coordinate in merged_coords:
+                    continue
+                    
+                try:
+                    if cell.value is not None:
+                        # Handle both single-line and multi-line content
+                        cell_value = str(cell.value)
+                        lines = cell_value.split('\n')
+                        current_max = max(len(line) for line in lines)
+                        max_length = max(max_length, current_max)
+                except Exception as e:
+                    print(f"Skipping cell {cell.coordinate} due to error: {e}")
+                    continue
+            
+            # Calculate width with constraints
+            adjusted_width = min(
+                max(1, (max_length * width_factor) + width_padding),
+                width_max if width_max is not None else float('inf')
+            )
+            
+            ws.column_dimensions[col_letter].width = adjusted_width
+
     def apply_color_to_worksheet(ws=None, sheet_name=None, conditions=None, cell_idx=None,where="text"):
         """
         Apply text color formatting to a specific cell range in an openpyxl workbook based on conditions.
@@ -10426,6 +11190,11 @@ def format_excel(
     
     def apply_format(ws, cell, cell_range):
         """Apply cell formatting to a specified range."""
+        # Get all merged cell coordinates first
+        merged_cells = set()
+        for merged_range in ws.merged_cells.ranges:
+            for coord in merged_range.cells:
+                merged_cells.add(coord)
         cell_font, cell_fill, cell_alignment, border = None, None, None, None
         kws_cell = ["font", "fill", "alignment", "border"]
         for K, _ in cell.items():
@@ -10623,6 +11392,7 @@ def format_excel(
                 )
                 # get colors config
                 for k, v in cell.get(K, {}).items():
+                    print(k, v,strcmp(k, kws_border)[0])
                     if strcmp(k, kws_border)[0] in ["color"]:
                         border_color_all = hex2argb(v)
                         # 如果设置了color,表示其它的所有的都设置成为一样的
@@ -10753,6 +11523,8 @@ def format_excel(
         #! final apply configs
         for row in ws[cell_range]:
             for cell_ in row:
+                if cell_.coordinate in merged_cells:
+                    continue  # Skip merged cells
                 if cell_font:
                     cell_.font = cell_font
                 if cell_fill:
@@ -10830,11 +11602,9 @@ def format_excel(
             if not os.path.exists(filename) or mode=="w":
                 # ws=wb.active
                 # ws.title = sheet_name
-                ws = wb.create_sheet(title=sheet_name)
-                print(1)
+                ws = wb.create_sheet(title=sheet_name) 
             else:# file exists
-                wb = load_workbook(filename)
-                print(2)
+                wb = load_workbook(filename) 
                 # with pd.ExcelWriter(filename, mode="a", engine=engine, if_sheet_exists=if_sheet_exists) as writer:
                 #     for ws in wb.worksheets:  # Iterate through worksheets in the input workbook
                 #         ws_df = pd.DataFrame(ws.values)
@@ -11161,44 +11931,62 @@ def format_excel(
             if freeze:
                 ws.freeze_panes = freeze  # Freeze everything above and to the left of A2
     # !widths 
-    if isinstance(width,bool):
+    if isinstance(width, bool):
         width=None if width else False
     if isinstance(height,bool):
         height=None if height else False
-    if width is None or width=={}:  # automatic adust width
-        for col in ws.columns:
-            max_length = 0
-            """column = col[0].column_letter  # Get the column letter"""
-                    # Check the first cell in the column to get the column letter
-            cell_first = col[0]
 
-            # Check if the cell is part of a merged range
-            if not any(cell_first.coordinate in range_ for range_ in ws.merged_cells.ranges):
-                column = get_column_letter(cell_first.column)  # Get the column letter from the first cell
-            else:
-                # Skip the column if the first cell is merged
+    merged_cells = set()
+    for merged_range in ws.merged_cells.ranges:
+        for row in ws.iter_rows(min_row=merged_range.min_row,
+                            max_row=merged_range.max_row,
+                            min_col=merged_range.min_col,
+                            max_col=merged_range.max_col):
+            for cell in row:
+                merged_cells.add(cell.coordinate)
+    if width is None or width == {}:  # automatic adjust width
+        print("auto-width")
+        for col in ws.columns:
+            if not col:
                 continue
-            for cell_ in col:
-                try:
-                    if cell_.value:
-                        max_length = max(max_length, len(str(cell_.value)))
-                except Exception:
-                    pass
-            adjusted_width = max_length*width_factor+width_padding
-            if width_max is not None:
-                adjusted_width = min(adjusted_width, width_max)
-            ws.column_dimensions[column].width = max(5,adjusted_width)
-    elif isinstance(width, (int, float)): #  set all columns to this value
+            try:
+                col_letter = get_column_letter(col[0].column)
+                
+                # Skip entire column if any cell is merged
+                if any(cell.coordinate in merged_cells for cell in col):
+                    continue
+                    
+                max_length = 0
+                for cell in col:
+                    try:
+                        if cell.value:
+                            cell_value = str(cell.value)
+                            if '\n' in cell_value:
+                                max_line_length = max(len(line) for line in cell_value.split('\n'))
+                                max_length = max(max_length, max_line_length)
+                            else:
+                                max_length = max(max_length, len(cell_value))
+                    except:
+                        pass
+                        
+                adjusted_width = (max_length * width_factor) + width_padding
+                if width_max is not None:
+                    adjusted_width = min(adjusted_width, width_max)
+                ws.column_dimensions[col_letter].width = max(5, adjusted_width)
+                
+            except Exception as e:
+                print(f"Error adjusting width for column: {e}")
+                continue
+    elif isinstance(width, (int, float)): # set all columns to this value
+        print("set to fixed width {}".format(width))
         for col in ws.columns:
-            column=get_column_letter(col[0].column)
-            ws.column_dimensions[column].width=width*width_factor+width_padding
-    elif isinstance(width,bool):
-        pass
-    else:
+            column = get_column_letter(col[0].column)
+            ws.column_dimensions[column].width = width * width_factor + width_padding
+    elif isinstance(width, dict):  # custom widths per column
         for col_idx, width_ in width.items():
             col_letter = get_column_letter(col_idx)
             ws.column_dimensions[col_letter].width = width_
-
+ 
     # !heights
     if height is None or height=={}:  # automatic adust height
         for row in ws.iter_rows(min_row=1, max_row=ws.max_row):
@@ -11655,9 +12443,28 @@ def format_excel(
 
     # ungroup sheets
     for sheet in wb.worksheets:
-        sheet.sheet_view.tabSelected = False 
+        sheet.sheet_view.tabSelected = False
     # !Save the workbook
-    wb.save(filename)
+    try:
+        wb.save(filename)
+    except Exception as e:
+         print(f"Error saving workbook: {str(e)}")
+    # Replace your final save operation with this:
+     # try:
+         # # Create a temporary file for safer saving
+         # temp_filename = filename + '.tmp'
+         # wb.save(temp_filename)
+        
+         # # If save succeeds, replace original file
+         # if os.path.exists(filename):
+             # os.remove(filename)
+         # os.rename(temp_filename, filename)
+        
+     # except Exception as e:
+         # print(f"Error saving workbook: {str(e)}")
+         # if os.path.exists(temp_filename):
+             # os.remove(temp_filename)
+         # raise
 
 
 def preview(var):
@@ -13716,6 +14523,575 @@ def df_fillna(
 #     print(method_name)
 #     display(df)
 #     display(df_fillna(data=df, method=method_name, inplace=False, axis=0))
+def df_cut(
+    df: pd.DataFrame,
+    column: str,
+    *,
+    new_col_name: Optional[str] = None,
+    bins: Optional[
+        Union[int, List[float], Dict[str, Union[float, str, pd.Timestamp]]]
+    ] = None,
+    range_start: Optional[Union[float, str, pd.Timestamp]] = None,
+    range_end: Optional[Union[float, str, pd.Timestamp]] = None,
+    step: Optional[Union[float, str, pd.Timedelta]] = None,
+    labels: Optional[List[str]] = None,
+    label_format: Optional[Union[str, Callable[[float, float], str]]] = None,
+    include_overflow: bool = True,
+    include_underflow: bool = False,
+    right: bool = False,
+    drop_original: bool = False,
+    precision: int = 2,
+    show_count: bool = False,
+    symbol_count: str = "n=",
+    show_percentage: bool = False,
+    symbol_percentage: str = "%",
+    show_total_count: bool = False,
+    symbol_total_count: str = "∑n=",
+    sep_between: str = " | ",
+    sort_labels: bool = True,
+    na_action: str = "keep",
+    na_fill_value: Optional[str] = None,
+    dtype: Optional[Union[str, pd.CategoricalDtype]] = None,
+    ordered: bool = True,
+    inplace: bool = False,
+    datetime_format: str = "%Y-%m-%d",
+    categorical_agg: str = "count",
+) -> Optional[pd.DataFrame]:
+    """
+            Enhanced binning function that works with numeric, datetime, and categorical columns.
+
+            Features:
+            - Automatic type detection (numeric, datetime, categorical)
+            - Flexible bin specification (number of bins, explicit edges, or range+step)
+            - Customizable labels with formatting
+            - Count and percentage display options
+            - NA value handling
+            square bracket: means inclusive
+            parenthesis: means exclusive
+            Parameters:
+            -----------
+            df : pd.DataFrame
+                Input DataFrame containing the column to bin
+            column : str
+                Name of column to bin
+            new_col_name : str, optional
+                Name for binned column (default: f"{column}_binned")
+            bins : int, list, or dict, optional
+                - int: Number of equal-width bins
+                - list: Explicit bin edges
+                - dict: {'start': x, 'end': y, 'step': z} for range specification
+            range_start : float or datetime-like, optional
+                Start value for bin range (required if bins is None or dict)
+            range_end : float or datetime-like, optional
+                End value for bin range (default: max of column)
+            step : float or timedelta-like, optional
+                Step size for bin creation (required if bins is None or dict)
+            labels : list of str, optional
+                Custom labels for bins (must match number of bins)
+            label_format : str or callable, optional
+                Format string or function for bin labels
+            include_overflow : bool, default True
+                Include catch-all bin for values above range_end
+            include_underflow : bool, default False
+                Include catch-all bin for values below range_start
+            right : bool, default False
+                Whether bins include the right edge
+            drop_original : bool, default False
+                Drop original column after binning
+            precision : int, default 2
+                Decimal precision for numeric bin labels
+            show_count : bool, default False
+                Show count of items in each bin
+            show_percentage : bool, default False
+                Show percentage of items in each bin
+            show_total_count : bool, default False
+                Show total count in labels
+            na_action : str, default 'keep'
+                How to handle NA values ('keep', 'drop', or 'fill')
+            na_fill_value : str, optional
+                Value to fill NAs with if na_action='fill'
+            dtype : dtype or CategoricalDtype, optional
+                Output dtype for binned column
+            ordered : bool, default True
+                Whether bins are ordered
+            inplace : bool, default False
+                Modify DataFrame in place
+            datetime_format : str, default "%Y-%m-%d"
+                Format string for datetime labels
+            categorical_agg : str, default 'count'
+                For categorical data: 'count' or 'ratio'
+
+            Returns:
+            --------
+            pd.DataFrame or None
+                Returns modified DataFrame unless inplace=True
+
+            Examples:
+            --------
+            # Numeric binning
+            df_cut(df, 'age', bins=5)
+            df_cut(df, 'price', range_start=0, range_end=1000, step=100)
+
+            # Datetime binning
+            df_cut(df, 'date', bins={'start': '2023-01-01', 'end': '2023-12-31', 'step': '1M'})
+
+            # Categorical binning
+            df_cut(df, 'category', bins=5, categorical_agg='ratio')
+
+    # Sample datetime data
+    dates = pd.date_range("2020-01-01", "2023-12-31", freq="D")
+    df = pd.DataFrame(
+        {
+            "order_date": np.random.choice(dates, 500),
+            "delivery_time": np.random.randint(1, 72, 500),  # hours
+        }
+    )
+    # Example 1: Monthly bins
+    # Monthly binning with exact month boundaries
+    df_cut(
+        df,
+        "order_date",
+        bins={"start": "2019-01-01", "end": "2023-12-31", "step": "1Y"},
+        datetime_format="%Y-%m-%d",
+        label_format="%m-%d",
+        show_count=True,
+        show_percentage=True,
+        show_total_count=True,
+    )
+    # Weekly binning
+    df_cut(
+        df,
+        "order_date",
+        bins={"start": "2019-01-01", "end": "2023-12-31", "step": "1W"},
+        label_format="%Y-%m-%d",
+        datetime_format="%Y-%m-%d",
+        show_count=True,
+        show_percentage=True,
+        show_total_count=True,
+    )
+
+
+    # Sample numeric data
+    df = pd.DataFrame(
+        {"price": np.random.uniform(10, 1000, 1000), "age": np.random.randint(18, 80, 1000)}
+    )
+
+    # Example 1: Equal-width bins
+    df_cut(df, "price", bins=5, show_count=True)
+
+    # Example 2: Custom range with step
+    df_cut(
+        df,
+        "price",
+        range_start=0,
+        range_end=1000,
+        step=200,
+        label_format="${left:.0f}-${right:.0f}",
+        show_percentage=True,
+    )
+    df_cut(
+        df,
+        "price",
+        bins={"start": 0, "end": 1000, "step": 200},
+        # label_format="${left:.0f}-${right:.0f}",
+        show_percentage=True,
+    )
+    """
+    from pandas.api.types import is_numeric_dtype, is_datetime64_any_dtype
+
+    def _process_time_step(step: Union[str, int, float, pd.Timedelta]) -> str:
+        """Convert step to pandas frequency string."""
+        if isinstance(step, pd.Timedelta):
+            return step.freqstr if step.freqstr else str(step)
+
+        if isinstance(step, (int, float)):
+            return f"{step}S"  # Interpret numbers as seconds
+
+        if isinstance(step, str):
+            step = step.strip().lower()
+            match = re.match(r"(\d*\.?\d+)?\s*([a-z]+)", step)
+            if not match:
+                raise ValueError(f"Invalid time step format: {step}")
+
+            num_part, unit_part = match.groups()
+            num = float(num_part) if num_part else 1.0
+
+            unit_map = {
+                "y": "Y",
+                "yr": "Y",
+                "yrs": "Y",
+                "year": "Y",
+                "years": "Y",
+                "m": "M",
+                "mo": "M",
+                "mon": "M",
+                "month": "M",
+                "months": "M",
+                "w": "W",
+                "wk": "W",
+                "wks": "W",
+                "week": "W",
+                "weeks": "W",
+                "d": "D",
+                "day": "D",
+                "days": "D",
+                "h": "H",
+                "hr": "H",
+                "hrs": "H",
+                "hour": "H",
+                "hours": "H",
+                "min": "T",
+                "mins": "T",
+                "minute": "T",
+                "minutes": "T",
+                "s": "S",
+                "sec": "S",
+                "secs": "S",
+                "second": "S",
+                "seconds": "S",
+            }
+
+            if unit_part not in unit_map:
+                raise ValueError(f"Unknown time unit: {unit_part}")
+
+            freq = unit_map[unit_part]
+            if num.is_integer():
+                num = int(num)
+            return f"{num}{freq}"
+
+        raise TypeError(f"Unsupported step type: {type(step)}")
+
+
+    def _process_datetime_column(
+        col: pd.Series,
+        bins: Optional[Union[int, List[pd.Timestamp]]],
+        range_start: Optional[Union[str, pd.Timestamp]],
+        range_end: Optional[Union[str, pd.Timestamp]],
+        step: Optional[Union[str, pd.Timedelta]],
+        labels: Optional[List[str]],
+        label_format: Optional[Union[str, Callable]],
+        datetime_format: str,
+        right: bool,
+        include_underflow: bool,
+        include_overflow: bool,
+    ) -> Tuple[pd.Categorical, List[str]]:
+        """Process datetime column with accurate counting."""
+        col = pd.to_datetime(col)
+
+        # Handle bin edges
+        if bins is None:
+            if step is None:
+                raise ValueError("Step must be provided for datetime binning")
+
+            # Convert step to pandas frequency string
+            step_freq = _process_time_step(step)
+
+            # Set default range if needed
+            range_start = (
+                pd.to_datetime(range_start) if range_start is not None else col.min()
+            )
+            range_end = pd.to_datetime(range_end) if range_end is not None else col.max()
+
+            # Generate bins
+            try:
+                bin_edges = pd.date_range(start=range_start, end=range_end, freq=step_freq)
+                if len(bin_edges) == 0:
+                    bin_edges = pd.date_range(start=range_start, end=range_end, periods=2)
+                elif bin_edges[-1] < range_end:
+                    bin_edges = bin_edges.append(pd.DatetimeIndex([range_end]))
+            except ValueError as e:
+                raise ValueError(f"Invalid frequency specification: {step_freq}") from e
+        elif isinstance(bins, int):
+            bin_edges = pd.date_range(start=col.min(), end=col.max(), periods=bins + 1)
+        else:
+            bin_edges = pd.to_datetime(bins)
+
+        # Add overflow/underflow bins
+        if include_underflow:
+            bin_edges = bin_edges.insert(0, pd.Timestamp.min)
+        if include_overflow:
+            bin_edges = bin_edges.append(pd.DatetimeIndex([pd.Timestamp.max]))
+
+        # Perform the cut - this is where we ensure proper binning
+        binned = pd.cut(
+            col.astype("int64"),  # Convert to nanoseconds for precise binning
+            bins=bin_edges.astype("int64"),
+            right=right,
+            include_lowest=True,
+        )
+
+        # Generate labels if not provided
+        if labels is None:
+            labels = []
+            for i in range(len(bin_edges) - 1):
+                left = bin_edges[i]
+                right_ = bin_edges[i + 1]
+
+                # Handle special cases
+                if left == pd.Timestamp.min:
+                    left_str = "<"
+                else:
+                    left_str = left.strftime(datetime_format)
+
+                if right_ == pd.Timestamp.max:
+                    right_str = ">"
+                else:
+                    right_str = right_.strftime(datetime_format)
+
+                # Apply label formatting
+                if callable(label_format):
+                    label = label_format(left, right_)
+                elif isinstance(label_format, str):
+                    try:
+                        if left != pd.Timestamp.min and right_ != pd.Timestamp.max:
+                            label = f"{left.strftime(label_format)}-{right_.strftime(label_format)}"
+                        else:
+                            label = f"{left_str}-{right_str}"
+                    except (ValueError, AttributeError):
+                        label = f"{left_str}-{right_str}"
+                else:
+                    label = f"{left_str}-{right_str}"
+
+                labels.append(label)
+
+        return binned, labels
+
+
+    def _process_categorical_column(
+        col: pd.Series,
+        bins: Optional[Union[int, List[str]]],
+        labels: Optional[List[str]],
+        categorical_agg: str,
+    ) -> Tuple[pd.Categorical, List[str]]:
+        value_counts = col.value_counts(normalize=(categorical_agg == "ratio"))
+
+        if bins is not None and isinstance(bins, int):
+            top_categories = value_counts.head(bins).index
+            binned = col.where(col.isin(top_categories), "Other")
+        elif isinstance(bins, list):
+            binned = col.where(col.isin(bins), "Other")
+        else:
+            binned = col
+
+        binned = binned.astype("category")
+
+        if labels is not None:
+            binned = binned.cat.rename_categories(dict(zip(binned.cat.categories, labels)))
+
+        return binned, list(binned.cat.categories)
+
+
+    def _process_numeric_column(
+        col: pd.Series,
+        bins: Optional[Union[int, List[float]]],
+        range_start: Optional[float],
+        range_end: Optional[float],
+        step: Optional[float],
+        labels: Optional[List[str]],
+        label_format: Optional[Union[str, Callable]],
+        precision: int,
+        right: bool,
+        include_underflow: bool,
+        include_overflow: bool,
+    ) -> Tuple[pd.Categorical, List[str]]:
+        if bins is None:
+            if range_start is None or step is None:
+                raise ValueError("If bins not provided, must set range_start and step")
+            if range_end is None:
+                range_end = col.max()
+
+            bin_edges = list(np.arange(range_start, range_end + step, step))
+        elif isinstance(bins, int):
+            bin_edges = np.linspace(col.min(), col.max(), bins + 1).tolist()
+        else:
+            bin_edges = list(bins)
+
+        # Add overflow/underflow bins if needed
+        if include_underflow and not np.isinf(bin_edges[0]):
+            bin_edges.insert(0, float("-inf"))
+        if include_overflow and not np.isinf(bin_edges[-1]):
+            bin_edges.append(float("inf"))
+
+        # Generate labels if not provided
+        if labels is None:
+            labels = []
+            for i in range(len(bin_edges) - 1):
+                left = round(bin_edges[i], precision)
+                right_ = round(bin_edges[i + 1], precision)
+
+                if label_format:
+                    label = (
+                        label_format(left, right_)
+                        if callable(label_format)
+                        else label_format.format(left=left, right=right_)
+                    )
+                else:
+                    if np.isinf(left) and left < 0:
+                        label = f"<{right_}"
+                    elif np.isinf(right_):
+                        label = f">{left}"
+                    else:
+                        label = f"[{left}, {right_}{']' if right else ')'}"
+
+                labels.append(label)
+
+        binned = pd.cut(
+            col, bins=bin_edges, labels=labels, right=right, include_lowest=True
+        )
+        return binned, labels
+
+
+    def _handle_na_values(
+        col: pd.Series, na_action: str, na_fill_value: Optional[str]
+    ) -> pd.Series:
+        if na_action == "drop":
+            return col.dropna()
+        elif na_action == "fill" and na_fill_value is not None:
+            return col.fillna(na_fill_value)
+        return col
+
+
+    def _add_statistical_labels(
+        binned: pd.Categorical,
+        labels: List[str],
+        show_count: bool,
+        show_percentage: bool,
+        show_total_count: bool,
+        symbol_count: str,
+        symbol_percentage: str,
+        symbol_total_count: str,
+        sep_between: str, 
+    ) -> List[str]:
+        """Add statistical information with accurate counts."""
+        # Get counts by matching the exact bin intervals
+        value_counts = binned.value_counts()
+        total = len(binned.dropna())
+
+        new_labels = []
+        for i, (label, category) in enumerate(zip(labels, binned.cat.categories)):
+            count = value_counts.get(category, 0)
+            parts = [label]
+
+            if show_count:
+                parts.append(f"{symbol_count}{count}")
+            if show_percentage:
+                percentage = (count / total * 100) if total > 0 else 0
+                parts.append(f"{percentage:.1f}{symbol_percentage}")
+            if show_total_count:
+                parts.append(f"{symbol_total_count}{total}")
+
+            # Ensure unique labels 
+            new_label = sep_between.join(parts)                
+            if new_label in new_labels:
+                new_label = f"{new_label}_{i}"
+            new_labels.append(new_label)
+
+        return new_labels
+
+
+    def _sort_bin_labels(binned: pd.Categorical, labels: List[str]) -> pd.Categorical:
+        try:
+            # Attempt to sort by the underlying intervals
+            sorted_categories = sorted(binned.cat.categories)
+            binned = binned.cat.reorder_categories(sorted_categories, ordered=True)
+        except Exception:
+            # If sorting fails (e.g., string labels), fallback to given label order
+            binned = binned.cat.set_categories(labels, ordered=True)
+        return binned
+    # Input validation
+    if column not in df.columns:
+        raise ValueError(f"Column '{column}' not found in DataFrame")
+
+    if not inplace:
+        df = df.copy()
+
+    col_data = df[column]
+
+    # Determine column type
+    if is_datetime64_any_dtype(col_data):
+        col_type = "datetime"
+        col_data = pd.to_datetime(col_data)
+    elif isinstance(col_data.dtype, pd.CategoricalDtype) or col_data.dtype == "object":
+        col_type = "categorical"
+    elif is_numeric_dtype(col_data):
+        col_type = "numeric"
+    else:
+        raise TypeError(f"Unsupported column type: {col_data.dtype}")
+
+    # Handle dictionary bin specification
+    if isinstance(bins, dict):
+        range_start = bins.get("start", range_start)
+        range_end = bins.get("end", range_end)
+        step = bins.get("step", step)
+        bins = None
+
+    # Process based on column type
+    if col_type == "datetime":
+        binned, bin_labels = _process_datetime_column(
+            col_data,
+            bins,
+            range_start,
+            range_end,
+            step,
+            labels,
+            label_format,
+            datetime_format,
+            right,
+            include_underflow,
+            include_overflow,
+        )
+    elif col_type == "categorical":
+        binned, bin_labels = _process_categorical_column(
+            col_data, bins, labels, categorical_agg
+        )
+    else:
+        binned, bin_labels = _process_numeric_column(
+            col_data,
+            bins,
+            range_start,
+            range_end,
+            step,
+            labels,
+            label_format,
+            precision,
+            right,
+            include_underflow,
+            include_overflow,
+        )
+
+    # Handle NA values
+    binned = _handle_na_values(binned, na_action, na_fill_value)
+
+    # Add statistical information to labels if requested
+    if show_count or show_percentage or show_total_count:
+        bin_labels = _add_statistical_labels(
+            binned,
+            bin_labels,
+            show_count,
+            show_percentage,
+            show_total_count,
+            symbol_count,
+            symbol_percentage,
+            symbol_total_count,
+            sep_between,
+        )
+        binned = binned.cat.rename_categories(
+            dict(zip(binned.cat.categories, bin_labels))
+        )
+
+    # Sort labels if requested
+    if sort_labels and not right and len(bin_labels) > 1:
+        binned = _sort_bin_labels(binned, bin_labels)
+
+    # Create final output column
+    new_col = new_col_name or f"{column}_binned"
+    df[new_col] = binned.astype(dtype) if dtype else binned
+
+    if drop_original:
+        df.drop(columns=[column], inplace=True)
+
+    return None if inplace else df
+
 
 
 def df_encoder(
@@ -16300,7 +17676,7 @@ def df_corr(df: pd.DataFrame, method="pearson"):
 def use_pd(
     func_name="excel",
     verbose=True,
-    dir_json="/Users/macjianfeng/Dropbox/github/python/py2ls/py2ls/data/usages_pd.json",
+    dir_json="./data/usages_pd.json",
 ):
     try:
         default_settings = fload(dir_json, output="json")