py2ls 0.2.5.12__py3-none-any.whl → 0.2.5.15__py3-none-any.whl

py2ls/ips.py

@@ -1,19 +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
-
+from typing import Dict, List, Optional, Union, Any, Tuple, Literal,Callable
 from regex import X
 
 try:
@@ -27,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
@@ -1663,76 +1873,465 @@ def flatten(nested: Any, unique_list=True, verbose=False):
         return flattened_list
 
 
-# def strcmp(
-#     search_term,
-#     candidates,
-#     ignore_case=True,
-#     get_rank=False,
-#     verbose=False,
-#     scorer="WR",
-#     method=None,
-# ):
-#     """
-#     Compares a search term with a list of candidate strings and finds the best match based on similarity score.
+#! ===========extract_text===========
+def extract_text(
+    text: Union[str, List[str]],
+    patterns: Union[str, List[str]],
+    *,
+    mode: Literal["between", "split", "extract"] = "between",
+    keep: Literal["none", "left", "right", "both", "markers"] = "none",
+    case: Literal["sensitive", "insensitive"] = "insensitive",
+    all_matches: bool = False,
+    positions: bool = False,
+    regex: bool = False,
+    delimiter: Optional[str] = None,
+    trim: bool = True,
+    as_dict: bool = False,
+    verbose: bool = False,
+    **kwargs,
+) -> Union[List[str], Tuple[int, str], Dict[str, Any], List[Dict[str, Any]], None]:
+    """
+    Ultimate text extraction tool with enhanced reliability and features.
 
-#     Parameters:
-#     search_term (str): The term to be searched for.
-#     candidates (list of str): A list of candidate strings to compare against the search term.
-#     ignore_case (bool): If True, the comparison ignores case differences.
-#     verbose (bool): If True, prints the similarity score and the best match.
+    Key improvements:
+    - Robust split mode with proper delimiter handling
+    - Consistent return types across all modes
+    - Improved pattern matching logic
+    - Better edge case handling
 
-#     Returns:
-#     tuple: A tuple containing the best match and its index in the candidates list.
-#     """
-#     from fuzzywuzzy import fuzz, process
-
-#     def to_lower(s, ignore_case=True):
-#         # Converts a string or list of strings to lowercase if ignore_case is True.
-#         if ignore_case:
-#             if isinstance(s, str):
-#                 return s.lower()
-#             elif isinstance(s, list):
-#                 s = [str(i) for i in s]  # convert all to str
-#                 return [elem.lower() for elem in s]
-#         return s
-#     scorer = str(method).lower() if method is not None else scorer
-#     str1_, str2_ = to_lower(search_term, ignore_case), to_lower(candidates, ignore_case)
-#     if isinstance(str2_, list):
-#         if "part" in scorer.lower():
-#             similarity_scores = [fuzz.partial_ratio(str1_, word) for word in str2_]
-#         elif "w" in scorer.lower():
-#             similarity_scores = [fuzz.WRatio(str1_, word) for word in str2_]
-#         elif "ratio" in scorer.lower() or "stri" in scorer.lower():  # Ratio (Strictest)
-#             similarity_scores = [fuzz.ratio(str1_, word) for word in str2_]
-#         else:
-#             similarity_scores = [fuzz.WRatio(str1_, word) for word in str2_]
-#         if get_rank:
-#             idx = [
-#                 similarity_scores.index(i)
-#                 for i in sorted(similarity_scores, reverse=True)
-#             ]
-#             if verbose:
-#                 display([candidates[ii] for ii in idx])
-#             return [candidates[ii] for ii in idx]
-#         best_match_index = similarity_scores.index(max(similarity_scores))
-#         best_match_score = similarity_scores[best_match_index]
-#     else:
-#         best_match_index = 0
-#         if "part" in scorer.lower():
-#             best_match_score = fuzz.partial_ratio(str1_, str2_)
-#         elif "w" in scorer.lower():
-#             best_match_score = fuzz.WRatio(str1_, str2_)
-#         elif "Ratio" in scorer.lower():
-#             best_match_score = fuzz.ratio(str1_, str2_)
-#         else:
-#             best_match_score = fuzz.WRatio(str1_, str2_)
-#     if verbose:
-#         print(f"\nbest_match is: {candidates[best_match_index],best_match_score}")
-#         best_match = process.extract(search_term, candidates)
-#         print(f"建议: {best_match}")
-#     return candidates[best_match_index], best_match_index
+
+    print(extract_text("A,B,C", ",", mode="split", keep="none", all_matches=True))
+    # Correctly returns: ['A', 'B', 'C']
+
+    print(extract_text("A,B,C", ",", mode="split", keep="left"))
+    # Returns: ['A,', 'B,', 'C']
+
+    print(extract_text("A,B,C", ",", mode="split", keep="right"))
+    # Returns: [',B', ',C']
+
+    print(extract_text("A,B,C", ",", mode="split", keep="both"))
+    # Returns: ['A', ',', 'B', ',', 'C']
+    """
+    if verbose:
+        print("""
+extract_text(
+    text: Union[str, List[str]],
+    patterns: Union[str, List[str]],
+    *,
+    mode: Literal["between", "split", "extract"] = "between",
+    keep: Literal["none", "left", "right", "both", "markers"] = "none",
+    case: Literal["sensitive", "insensitive"] = "insensitive",
+    all_matches: bool = False,
+    positions: bool = False,
+    regex: bool = False,
+    delimiter: Optional[str] = None,
+    trim: bool = True,
+    as_dict: bool = False,
+    verbose: bool = False,
+    **kwargs,
+) 
+              """)
+    # Normalization and validation
+    text = _normalize_text(text, delimiter)
+    patterns = _validate_patterns(patterns)
+    flags = re.IGNORECASE if case == "insensitive" else 0
+
+    # Find all matches with enhanced validation
+    matches = _find_matches(text, patterns, regex, flags)
+    if not matches:
+        return None
+
+    # Mode-specific processing
+    if mode == "extract":
+        return _handle_extract(matches, all_matches, as_dict, positions, trim)
+    elif mode == "split":
+        return _handle_split(text, matches, keep, all_matches, as_dict, positions, trim)
+    elif mode == "between":
+        return _handle_between(text, matches, patterns, keep, as_dict, positions, trim)
+    else:
+        raise ValueError(f"Invalid mode: {mode}")
+
+
+def _normalize_text(text: Union[str, List[str]], delimiter: Optional[str]) -> str:
+    """Normalize text input to single string"""
+    if isinstance(text, list):
+        return delimiter.join(text) if delimiter else " ".join(text)
+    return text
+
+
+def _validate_patterns(patterns: Union[str, List[str]]) -> List[str]:
+    """Validate and normalize patterns"""
+    if isinstance(patterns, str):
+        return [patterns]
+    if not patterns:
+        raise ValueError("At least one pattern required")
+    return patterns
+
+
+def _find_matches(
+    text: str, patterns: List[str], regex: bool, flags: int
+) -> List[dict]:
+    """Find all pattern matches with enhanced regex handling"""
+    matches = []
+    for pattern in patterns:
+        try:
+            search_pattern = pattern if regex else re.escape(pattern)
+            for match in re.finditer(search_pattern, text, flags=flags):
+                matches.append(
+                    {
+                        "text": match.group(),
+                        "start": match.start(),
+                        "end": match.end(),
+                        "pattern": pattern,
+                        "full_match": match,
+                    }
+                )
+        except re.error as e:
+            raise ValueError(f"Invalid pattern '{pattern}': {e}")
+    return sorted(matches, key=lambda x: x["start"])
+
+
+def _handle_extract(
+    matches: List[dict], all_matches: bool, as_dict: bool, positions: bool, trim: bool
+) -> Union[List, dict]:
+    """Handle text extraction of matched patterns"""
+    results = []
+    for match in matches if all_matches else [matches[0]]:
+        content = match["text"].strip() if trim else match["text"]
+        result = (
+            {
+                "text": content,
+                "start": match["start"],
+                "end": match["end"],
+                "pattern": match["pattern"],
+            }
+            if as_dict
+            else content
+        )
+        if positions and as_dict:
+            result["positions"] = [(match["start"], match["end"])]
+        results.append(result)
+
+    return results[0] if not all_matches else results
+
+
+def _create_part(
+    content: str,
+    start: int,
+    end: int,
+    match: Optional[dict],
+    as_dict: bool,
+    positions: bool,
+    trim: bool,
+) -> Union[str, dict]:
+    """Create a standardized result part"""
+    content = content.strip() if trim else content
+    if not as_dict:
+        return content
+
+    part = {
+        "text": content,
+        "start": start,
+        "end": end,
+        "pattern": match["pattern"] if match else None,
+    }
+    if positions and match:
+        part["positions"] = [(match["start"], match["end"])]
+    return part
+
+
+def _handle_between(
+    text: str,
+    matches: List[dict],
+    patterns: List[str],
+    keep: str,
+    as_dict: bool,
+    positions: bool,
+    trim: bool,
+) -> Union[Tuple, dict]:
+    """Reliable between-mode implementation with boundary checks"""
+    first_pattern, last_pattern = patterns[0], patterns[-1]
+    first_matches = [m for m in matches if m["pattern"] == first_pattern]
+    last_matches = [m for m in matches if m["pattern"] == last_pattern]
+
+    if not first_matches or not last_matches:
+        return None
+
+    first = first_matches[0]
+    last = last_matches[-1]
+
+    if first["start"] > last["start"]:
+        return None
+
+    # Calculate extraction window
+    start, end = first["start"], last["end"]
+    if keep == "none":
+        start, end = first["end"], last["start"]
+    elif keep == "left":
+        end = last["start"]
+    elif keep == "right":
+        start = first["end"]
+
+    extracted = text[start:end].strip() if trim else text[start:end]
+
+    if as_dict:
+        result = {
+            "text": extracted,
+            "start": start,
+            "end": end,
+            "patterns": patterns,
+            "match_positions": [(m["start"], m["end"]) for m in matches],
+        }
+        return result
+
+    return (
+        (start, extracted)
+        if not positions
+        else (start, extracted, [(m["start"], m["end"]) for m in matches])
+    )
+
+
+def _handle_split(
+    text: str,
+    matches: List[dict],
+    keep: str,
+    all_matches: bool,
+    as_dict: bool,
+    positions: bool,
+    trim: bool,
+) -> Union[List, dict]:
+    """Split text with proper handling of keep='both' to include delimiters on both sides"""
+    if not matches:
+        return (
+            [text]
+            if not as_dict
+            else [{"text": text, "start": 0, "end": len(text), "pattern": None}]
+        )
+
+    parts = []
+    prev_end = 0
+    process_matches = matches if all_matches else [matches[0]]
+
+    # Special handling for keep="both"
+    if keep == "both":
+        for i, match in enumerate(process_matches):
+            start, end = match["start"], match["end"]
+            matched_text = text[start:end]
+
+            # First segment (text before first delimiter + first delimiter)
+            if i == 0:
+                segment = text[prev_end:end]  # From start to end of first delimiter
+                if trim:
+                    segment = segment.strip()
+                if segment or not trim:
+                    if as_dict:
+                        parts.append(
+                            {
+                                "text": segment,
+                                "start": prev_end,
+                                "end": end,
+                                "pattern": match["pattern"],
+                                **({"positions": [(start, end)]} if positions else {}),
+                            }
+                        )
+                    else:
+                        parts.append(segment)
+                prev_end = end
+
+            # Middle segments (delimiter + text + next delimiter)
+            if i > 0 and i < len(process_matches):
+                next_match = process_matches[i]
+                next_start, next_end = next_match["start"], next_match["end"]
+                segment = text[
+                    prev_end:next_end
+                ]  # From prev_end to end of next delimiter
+                if trim:
+                    segment = segment.strip()
+                if segment or not trim:
+                    if as_dict:
+                        parts.append(
+                            {
+                                "text": segment,
+                                "start": prev_end,
+                                "end": next_end,
+                                "pattern": next_match["pattern"],
+                                **(
+                                    {"positions": [(next_start, next_end)]}
+                                    if positions
+                                    else {}
+                                ),
+                            }
+                        )
+                    else:
+                        parts.append(segment)
+                prev_end = next_end
+
+        # Last segment (last delimiter + remaining text)
+        if process_matches and prev_end < len(text):
+            last_match = process_matches[-1]
+            segment = text[
+                last_match["start"] : len(text)
+            ]  # From last delimiter to end
+            if trim:
+                segment = segment.strip()
+            if segment or not trim:
+                if as_dict:
+                    parts.append(
+                        {
+                            "text": segment,
+                            "start": last_match["start"],
+                            "end": len(text),
+                            "pattern": last_match["pattern"],
+                            **(
+                                {
+                                    "positions": [
+                                        (last_match["start"], last_match["end"])
+                                    ]
+                                }
+                                if positions
+                                else {}
+                            ),
+                        }
+                    )
+                else:
+                    parts.append(segment)
+
+        return parts
+
+    # Original handling for other keep modes
+    for i, match in enumerate(process_matches):
+        start, end = match["start"], match["end"]
+        matched_text = text[start:end]
+
+        # Handle text before the match
+        if prev_end < start:
+            before = text[prev_end:start]
+            if trim:
+                before = before.strip()
+            if before or not trim:
+                if as_dict:
+                    parts.append(
+                        {
+                            "text": before,
+                            "start": prev_end,
+                            "end": start,
+                            "pattern": None,
+                            **({"positions": []} if positions else {}),
+                        }
+                    )
+                else:
+                    parts.append(before)
+
+        # Handle the match based on keep mode
+        if keep == "none":
+            pass  # Skip the delimiter
+        elif keep == "left":
+            if parts:
+                if as_dict:
+                    parts[-1]["text"] += matched_text
+                    parts[-1]["end"] = end
+                else:
+                    parts[-1] += matched_text
+            else:
+                if as_dict:
+                    parts.append(
+                        {
+                            "text": matched_text,
+                            "start": start,
+                            "end": end,
+                            "pattern": match["pattern"],
+                            **({"positions": [(start, end)]} if positions else {}),
+                        }
+                    )
+                else:
+                    parts.append(matched_text)
+        elif keep == "right":
+            if i < len(process_matches) - 1:
+                next_start = process_matches[i + 1]["start"]
+                if end < next_start:
+                    between = text[end:next_start]
+                    if as_dict:
+                        parts.append(
+                            {
+                                "text": matched_text + between,
+                                "start": start,
+                                "end": next_start,
+                                "pattern": match["pattern"],
+                                **({"positions": [(start, end)]} if positions else {}),
+                            }
+                        )
+                    else:
+                        parts.append(matched_text + between)
+                    prev_end = next_start
+                    continue
+
+        prev_end = end
+
+    # Handle remaining text after last match
+    if prev_end < len(text):
+        remaining = text[prev_end:]
+        if trim:
+            remaining = remaining.strip()
+        if remaining or not trim:
+            if keep == "right" and parts and process_matches:
+                last_match = process_matches[-1]
+                matched_text = text[last_match["start"] : last_match["end"]]
+                if as_dict:
+                    parts.append(
+                        {
+                            "text": matched_text + remaining,
+                            "start": last_match["start"],
+                            "end": len(text),
+                            "pattern": last_match["pattern"],
+                            **(
+                                {
+                                    "positions": [
+                                        (last_match["start"], last_match["end"])
+                                    ]
+                                }
+                                if positions
+                                else {}
+                            ),
+                        }
+                    )
+                else:
+                    parts.append(matched_text + remaining)
+            else:
+                if as_dict:
+                    parts.append(
+                        {
+                            "text": remaining,
+                            "start": prev_end,
+                            "end": len(text),
+                            "pattern": None,
+                            **({"positions": []} if positions else {}),
+                        }
+                    )
+                else:
+                    parts.append(remaining)
+
+    # Filter empty parts if trimming
+    if trim:
+        parts = [p for p in parts if (p["text"].strip() if as_dict else p.strip())]
+
+    return parts
 
 
+def _merge_parts(
+    parts: List[Union[str, dict]], text: str, as_dict: bool, trim: bool
+) -> Union[str, dict]:
+    """Merge adjacent parts for keep=left mode"""
+    if as_dict:
+        merged_text = "".join(p["text"] for p in parts)
+        return {
+            "text": merged_text.strip() if trim else merged_text,
+            "start": parts[0]["start"],
+            "end": parts[-1]["end"],
+            "patterns": list(set(p["pattern"] for p in parts if p["pattern"])),
+        }
+    return "".join(parts).strip() if trim else "".join(parts)
+#! ===========extract_text===========
+
 def strcmp(
     search_term: str,
     candidates: List[str],
@@ -2794,73 +3393,6 @@ def text2audio(
 
 # from datetime import datetime
 from dateutil import parser
-# import re
-# from typing import Union, Optional, Dict, Any
-# def str2time(time_str, fmt="24"):
-#     """
-#     Convert a time string into the specified format.
-#     Parameters:
-#     - time_str (str): The time string to be converted.
-#     - fmt (str): The format to convert the time to. Defaults to '%H:%M:%S'.
-#     Returns:
-#         %I represents the hour in 12-hour format.
-#         %H represents the hour in 24-hour format (00 through 23).
-#         %M represents the minute.
-#         %S represents the second.
-#         %p represents AM or PM.
-#     - str: The converted time string.
-#     """
-#     from datetime import datetime
-
-#     def time_len_corr(time_str):
-#         time_str_ = (
-#             ssplit(time_str, by=[":", " ", "digital_num"]) if ":" in time_str else None
-#         )
-#         time_str_split = []
-#         [time_str_split.append(i) for i in time_str_ if is_num(i)]
-#         if time_str_split:
-#             if len(time_str_split) == 2:
-#                 H, M = time_str_split
-#                 time_str_full = H + ":" + M + ":00"
-#             elif len(time_str_split) == 3:
-#                 H, M, S = time_str_split
-#                 time_str_full = H + ":" + M + ":" + S
-#         else:
-#             time_str_full = time_str_
-#         if "am" in time_str.lower():
-#             time_str_full += " AM"
-#         elif "pm" in time_str.lower():
-#             time_str_full += " PM"
-#         return time_str_full
-
-#     if "12" in fmt:
-#         fmt = "%I:%M:%S %p"
-#     elif "24" in fmt:
-#         fmt = "%H:%M:%S"
-
-#     try:
-#         # Try to parse the time string assuming it could be in 24-hour or 12-hour format
-#         time_obj = datetime.strptime(time_len_corr(time_str), "%H:%M:%S")
-#     except ValueError:
-#         try:
-#             time_obj = datetime.strptime(time_len_corr(time_str), "%I:%M:%S %p")
-#         except ValueError as e:
-#             raise ValueError(f"Unable to parse time string: {time_str}. Error: {e}")
-
-#     # Format the time object to the desired output format
-#     formatted_time = time_obj.strftime(fmt)
-#     return formatted_time
-
-
-# # # Example usage:
-# # time_str1 = "14:30:45"
-# # time_str2 = "02:30:45 PM"
-
-# # formatted_time1 = str2time(time_str1, fmt='12')  # Convert to 12-hour format
-# # formatted_time2 = str2time(time_str2, fmt='24')    # Convert to 24-hour format
-
-# # print(formatted_time1)  # Output: 02:30:45 PM
-# # print(formatted_time2)  # Output: 14:30:45
 def str2time(
     time_str: str, 
     fmt: str = "24", 
@@ -2964,57 +3496,6 @@ def str2time(
             raise ValueError(f"Unable to parse time string: '{time_str}'. Error: {e}")
         return default
 
-
-# def str2date(date_str, original_fmt=None, fmt="%Y-%m-%d"):
-#     """
-#     Convert a date string to the desired format and extract components if needed.
-#     Usage:
-#         str2date(x, fmt="%d.%m.%y",original_fmt="%d.%m.%y")
-#     Parameters:
-#     - date_str (str): The input date string.
-#     - original_fmt (str, optional): The original format of the date string. If not provided, it will be auto-detected.
-#     - fmt (str): The desired format for the output date string. Defaults to '%Y-%m-%d'.
-
-#     Returns:
-#     - dict: A dictionary containing the converted date string and its components (year, month, day).
-    
-#     Raises:
-#     - ValueError: If the date cannot be parsed.
-#     """ 
-#     from dateutil import parser
-#     try:
-#         if not isinstance(date_str,str):
-#             date_str=str(date_str) 
-#         # Parse the date using the provided original format or auto-detect
-#         if original_fmt:
-#             try:
-#                 date_obj = datetime.strptime(date_str, original_fmt)
-#             except Exception as e:
-#                 print(e)
-#                 date_obj=None
-#         else:
-#             try:
-#                 date_obj = parser.parse(date_str)
-#             except Exception as e:
-#                 print(e)
-#                 date_obj=None
-#         # Return formatted string if `fmt` is specified, otherwise return the datetime object
-#         if date_obj is not None:
-#             if fmt: 
-#                 date_obj=date_obj.strftime(fmt)
-#         else:
-#             date_obj=date_str
-#         return date_obj
-
-#     except (ValueError, TypeError) as e:
-#         raise ValueError(f"Unable to process date string: '{date_str}'. Error: {e}")
-
-
-# # str1=str2date(num2str(20240625),fmt="%a %d-%B-%Y")
-# # print(str1)
-# # str2=str2num(str2date(str1,fmt='%a %Y%m%d'))
-# # print(str2)
- 
 def str2date(
     date_str: Union[str, int, float], 
     fmt: Optional[str] = "%Y-%m-%d",
@@ -4054,8 +4535,7 @@ def pdf2ppt(dir_pdf, dir_ppt):
 
 
 def ssplit(text, by="space", verbose: bool =False, strict: bool =False, strip_results: bool = True, **kws):
-    """
-    #         Determines the splitting strategy:
+    """# Determines the splitting strategy:
     #         - "space", "whitespace", "sp": split by whitespace (default)
     #         - "word": split into words using NLTK's word_tokenize
     #         - "sentence", "sent": split into sentences using NLTK's sent_tokenize
@@ -4172,13 +4652,6 @@ def ssplit(text, by="space", verbose: bool =False, strict: bool =False, strip_re
 
     def split_by_regex_end(text, pattern):
         return re.split(f"(?={pattern})", text)
-
-    # def split_by_sentence_endings(text):
-    #     return re.split(r"(?<=[.!?])", text)
-    # def split_non_ascii(text):
-    #     # return re.split(r"([^\x00-\x7F\w\s,.!?:\"'()\-]+)", text)
-    #     # return re.split(r"[^\x00-\x7F]+", text)
-    #     return re.split(r"([^\x00-\x7F]+)", text)
     def split_non_ascii(text, keep_delimiters=False):
         """
         Split text at non-ASCII characters.
@@ -4903,145 +5376,6 @@ def _backup_validations(sheet, verbose=False):
 
     return backup
 
-# def _backup_validations(sheet):
-#     """
-#     Complete validation backup with XML-level cross-sheet detection
-#     """
-#     from openpyxl.utils import get_column_letter
-#     import re
-#     from openpyxl.worksheet.datavalidation import DataValidation
-#     from openpyxl.xml.functions import fromstring
-
-#     backup = {
-#         "validations": [],
-#         "conditional_formatting": [],
-#         "merged_cells": [str(mr) for mr in sheet.merged_cells.ranges],
-#         "_metadata": {
-#             "validated_cells": set(),
-#             "validated_columns": set(),
-#             "validation_types": set(),
-#             "cross_sheet_validations": set()
-#         }
-#     }
-
-#     # METHOD 1: Primary validation backup (standard method)
-#     for dv in sheet.data_validations:
-#         # ... (existing standard validation backup code) ...
-
-#     # METHOD 2: XML-based cross-sheet validation detection
-#     print("Performing deep XML scan for cross-sheet validations...")
-    
-#     # Access the worksheet XML directly
-#     xml_source = sheet._worksheet.xml
-#     if not xml_source:
-#         print("Warning: Could not access worksheet XML source")
-#         return backup
-
-#     try:
-#         # Parse the XML
-#         root = fromstring(xml_source)
-#         ns = {'ns': 'http://schemas.openxmlformats.org/spreadsheetml/2006/main'}
-        
-#         # Find all dataValidation elements
-#         for dv_xml in root.findall('.//ns:dataValidation', ns):
-#             try:
-#                 # Extract validation attributes
-#                 dv_type = dv_xml.get('type', 'none')
-#                 formula1 = dv_xml.find('.//ns:formula1', ns)
-#                 formula_text = formula1.text if formula1 is not None else None
-                
-#                 # Skip if not a list type or no formula
-#                 if dv_type != 'list' or not formula_text:
-#                     continue
-                
-#                 # Clean the formula
-#                 clean_formula = formula_text.strip('"\'')
-                
-#                 # Check for cross-sheet patterns
-#                 cross_sheet_patterns = [
-#                     (r'^[\w\s]+!\$?[A-Za-z]+\$?\d+(?::\$?[A-Za-z]+\$?\d+)?$', "direct sheet reference"),
-#                     (r'INDIRECT\(["\'][\w\s]+![A-Za-z]+\d+(?::[A-Za-z]+\d+)?["\']\)', "INDIRECT sheet reference"),
-#                     (r'^[^\s!]+$', "potential named range"),
-#                 ]
-                
-#                 # Determine if this is a cross-sheet reference
-#                 is_cross_sheet = False
-#                 detection_method = ""
-                
-#                 for pattern, description in cross_sheet_patterns:
-#                     if re.match(pattern, clean_formula, re.IGNORECASE):
-#                         is_cross_sheet = True
-#                         detection_method = description
-#                         break
-                
-#                 if not is_cross_sheet:
-#                     continue
-                
-#                 # Process the ranges
-#                 ranges = []
-#                 sqref = dv_xml.get('sqref', '')
-#                 for range_str in sqref.split():
-#                     try:
-#                         # Convert range to coordinates
-#                         if ':' in range_str:
-#                             start, end = range_str.split(':')
-#                             col_start = int(''.join(filter(str.isdigit, start)))
-#                             col_end = int(''.join(filter(str.isdigit, end)))
-#                             row_start = int(''.join(filter(str.isalpha, start)))
-#                             row_end = int(''.join(filter(str.isalpha, end)))
-#                             ranges.append({
-#                                 'range': range_str,
-#                                 'cells': [f"{get_column_letter(col)}{row}" 
-#                                          for col in range(col_start, col_end+1)
-#                                          for row in range(row_start, row_end+1)]
-#                             })
-#                         else:
-#                             col = int(''.join(filter(str.isdigit, range_str)))
-#                             row = int(''.join(filter(str.isalpha, range_str)))
-#                             ranges.append({
-#                                 'range': range_str,
-#                                 'cells': [f"{get_column_letter(col)}{row}"]
-#                             })
-#                     except Exception as e:
-#                         print(f"Error parsing range {range_str}: {e}")
-                
-#                 # Create validation record
-#                 validation_data = {
-#                     'type': 'list',
-#                     'formula1': formula_text,
-#                     'formula2': None,
-#                     'allow_blank': dv_xml.get('allowBlank', '1') == '1',
-#                     'showDropDown': dv_xml.get('showDropDown', '1') == '1',
-#                     'showInputMessage': dv_xml.get('showInputMessage', '1') == '1',
-#                     'showErrorMessage': dv_xml.get('showErrorMessage', '0') == '1',
-#                     'errorTitle': dv_xml.get('errorTitle', ''),
-#                     'error': dv_xml.get('error', ''),
-#                     'promptTitle': dv_xml.get('promptTitle', ''),
-#                     'prompt': dv_xml.get('prompt', ''),
-#                     'ranges': ranges,
-#                     '_source': 'xml_validation',
-#                     '_detection_method': detection_method,
-#                     '_is_cross_sheet': True,
-#                     '_formula_clean': clean_formula
-#                 }
-                
-#                 # Add to backup
-#                 backup['validations'].append(validation_data)
-#                 for rng in ranges:
-#                     for cell_ref in rng['cells']:
-#                         backup['_metadata']['validated_cells'].add(cell_ref)
-#                         backup['_metadata']['validated_columns'].add(''.join(filter(str.isalpha, cell_ref)))
-#                 backup['_metadata']['validation_types'].add('list')
-#                 backup['_metadata']['cross_sheet_validations'].add(clean_formula.split('!')[0])
-                
-#             except Exception as e:
-#                 print(f"Error processing XML validation: {e}")
-                
-#     except Exception as e:
-#         print(f"Error parsing worksheet XML: {e}")
-    
-#     return backup
-
 def _restore_validations(sheet, backup,verbose=False):
     """
     恢复数据验证和条件格式规则到工作表
@@ -5247,11 +5581,6 @@ def fload(fpath, kind=None, **kwargs):
         with open(fpath, "r") as file:
             content = file.read()
         return content
-
-    # def load_html(fpath):
-    #     with open(fpath, "r") as file:
-    #         content = file.read()
-    #     return content
     def load_html(fpath, **kwargs):
         return pd.read_html(fpath, **kwargs)
 
@@ -5570,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)
@@ -6518,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)
 
@@ -7118,7 +7426,7 @@ def listdir(
     hidden=False,  # Include hidden files/folders
     orient="list",
     output="df",  # "df", 'list','dict','records','index','series'
-    verbose=True,
+    verbose=False,
 ):
     def is_hidden(filepath):
         """Check if a file or folder is hidden."""
@@ -7348,7 +7656,7 @@ def listdir(
         if "se" in orient.lower():  # records
             return Box(f.to_dict(orient="series"))
 
-
+ 
 def listpkg(where="env", verbose=False):
     """list all pacakages"""
 
@@ -7829,87 +8137,7 @@ def split_path(fpath):
     dir_par = f_slash.join(fpath.split(f_slash)[:-1])
     dir_ch = "".join(fpath.split(f_slash)[-1:])
     return dir_par, dir_ch
-
-
-def figsave(*args, dpi=300, **kwargs): 
-    import matplotlib.pyplot as plt
-    from PIL import Image
-    bbox_inches = kwargs.pop("bbox_inches", "tight")
-    pad_inches = kwargs.pop("pad_inches", 0)
-    facecolor = kwargs.pop("facecolor", "white")
-    edgecolor = kwargs.pop("edgecolor", "auto")
-
-    dir_save = None
-    fname = None
-    img = None
-
-    for arg in args:
-        if isinstance(arg, str):
-            path = Path(arg)
-            if path.suffix:  # Has file extension
-                fname = path.name
-                dir_save = path.parent
-            else:
-                dir_save = path
-        elif isinstance(arg, (Image.Image, np.ndarray)):
-            img = arg  # Store PIL image or numpy array
-
-    # Set default save directory
-    dir_save = Path(dir_save) if dir_save else Path(".")
-    dir_save.mkdir(parents=True, exist_ok=True)
-
-    # Handle filename and extension
-    if fname is None:
-        fname = "figure"
-    fname = dir_save / fname
-    if fname.suffix == "":
-        fname = fname.with_suffix(".pdf")  # Default format
-
-    ftype = fname.suffix.lstrip(".").lower()
-
-    # Save figure based on file type
-    if ftype == "eps":
-        plt.savefig(fname, format="eps", bbox_inches=bbox_inches)
-        plt.savefig(fname.with_suffix(".pdf"), format="pdf", dpi=dpi,
-                    pad_inches=pad_inches, bbox_inches=bbox_inches,
-                    facecolor=facecolor, edgecolor=edgecolor)
-    elif ftype == "pdf":
-        plt.savefig(fname, format="pdf", dpi=dpi, pad_inches=pad_inches,
-                    bbox_inches=bbox_inches, facecolor=facecolor, edgecolor=edgecolor)
-    elif ftype in ["jpg", "jpeg", "png", "tiff", "tif"]:
-        if img is not None:  # If an image is provided
-            if isinstance(img, Image.Image):
-                img = img.convert("RGB") if img.mode == "RGBA" else img
-                img.save(fname, format=ftype.upper(), dpi=(dpi, dpi))
-            elif isinstance(img, np.ndarray):
-                import cv2
-                if img.ndim == 2:
-                    Image.fromarray(img).save(fname, format=ftype.upper(), dpi=(dpi, dpi))
-                elif img.ndim == 3:
-                    if img.shape[2] == 3:
-                        img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
-                    elif img.shape[2] == 4:
-                        img = cv2.cvtColor(img, cv2.COLOR_BGRA2RGBA)
-                    Image.fromarray(img).save(fname, format=ftype.upper(), dpi=(dpi, dpi))
-                else:
-                    raise ValueError("Unexpected image dimensions.")
-        else:
-            plt.savefig(fname, format=ftype, dpi=dpi, pad_inches=pad_inches,
-                        bbox_inches=bbox_inches, facecolor=facecolor, edgecolor=edgecolor)
-    elif ftype == "ico":
-        if img is None:
-            plt.savefig(fname, dpi=dpi, pad_inches=pad_inches,
-                        bbox_inches=bbox_inches, facecolor=facecolor, edgecolor=edgecolor)
-            img = Image.open(fname)
-        img = img.convert("RGBA")
-        icon_sizes = [(32, 32), (64, 64), (128, 128), (256, 256)]
-        img.save(fname, format="ICO", sizes=icon_sizes)
-        print(f"Icon saved @: {fname} with sizes: {icon_sizes}")
-    else:
-        raise ValueError(f"Unsupported file format: {ftype}")
-
-    print(f"\nSaved @ {fname} (dpi={dpi})")
-
+ 
 def figsave(*args, dpi=300, **kwargs):
     """
     Save a Matplotlib figure or image file in various formats.
@@ -8038,7 +8266,7 @@ def figsave(*args, dpi=300, **kwargs):
         img = img.convert("RGBA") 
         img.save(fname, format="ICO", sizes=icon_sizes)
         print(f"Icon saved @: {fname} with sizes: {icon_sizes}")
-    print(f"\n✅ Saved @: dpi={dpi}\n{fname}")
+    print(f"\nSaved @: dpi={dpi}\n{fname}")
 
 
 def is_str_color(s):
@@ -8806,7 +9034,8 @@ def detect_angle(image, by="median", template=None):
 
     # Use Hough transform to detect lines
     lines = transform.probabilistic_hough_line(edges)
-
+    if isinstance(by, bool):
+        by="mean" if by else 0
     if not lines and any(["me" in by, "pca" in by]):
         print("No lines detected. Adjust the edge detection parameters.")
         return 0
@@ -9180,7 +9409,7 @@ def imgsets(
         elif "cro" in k.lower() or "cut" in k.lower():
             img_update = img_update.crop(value)
         elif "rota" in k.lower():
-            if isinstance(value, str):
+            if isinstance(value, (str,bool)):
                 value = detect_angle(img_update, by=value)
                 print(f"rotated by {value}°")
             img_update = img_update.rotate(value)
@@ -9371,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):
     """
@@ -9524,35 +9747,276 @@ def finfo(fpath, output='json', verbose=False):
         extra_info=extra_info,
     )
 
-
-
-# ! format excel file
-
-
-def hex2argb(color):
+def color2rgb(
+    color_input: str | tuple | list | None, 
+    alpha: float | None = None
+) -> tuple | None:
     """
-    Convert a color name or hex code to aARGB format required by openpyxl.
-
-    :param color: A color in the format: 'blue', '#RRGGBB', 'RRGGBB', 'aARRGGBB'
-    :return: A hex color code in the format aARRGGBB.
-
-    Example:
-        print(hex2argb("blue"))      # Output: FF0000FF
-        print(hex2argb("FFFF00"))    # Output: FFFFFF00
-        print(hex2argb("#DF4245"))   # Output: FFDf4245
-        print(hex2argb("FF00FF00"))  # Output: FF00FF00 (already in aARGB format)
+    Ultimate color conversion utility with support for multiple formats and transparency.
+    
+    Parameters:
+    -----------
+    color_input : str | tuple | list | None
+        Supported formats:
+        - Hex strings ("#RRGGBB", "#RGB")
+        - Named colors ("red", "blue")
+        - RGB tuples ((0.2, 0.4, 0.6))
+        - RGBA tuples ((0.2, 0.4, 0.6, 0.8))
+        - HTML/CSS colors ("cornflowerblue")
+        - CSS formats:
+          - rgb(100,200,50)
+          - rgba(100,200,50,0.8)
+          - hsl(120,60%,70%)
+          - hsla(120,60%,70%,0.8)
+    alpha : float | None, optional
+        Opacity value (0.0-1.0). If provided, adds/overrides alpha channel.
+    
+    Returns:
+    --------
+    tuple | None
+        (R, G, B) or (R, G, B, A) tuple in 0-1 range, or None if invalid
     """
-    import matplotlib.colors as mcolors
+    from matplotlib import colors as mcolors
     import re
-    color = color.lower().replace(" ", "") # 'light blue'
-    # Convert color name (e.g., "blue") to hex
+    
+    if color_input is None:
+        return None
+    
+    # Case 1: Already in RGB/RGBA tuple format
+    if isinstance(color_input, (tuple, list)):
+        if 3 <= len(color_input) <= 4:
+            if all(0 <= x <= 1 for x in color_input):
+                if alpha is not None and len(color_input) == 3:
+                    return (*color_input, alpha)
+                return tuple(color_input)
+    
+    # Case 2: String input
+    if isinstance(color_input, str):
+        # Remove whitespace and make lowercase
+        color_str = color_input.strip().lower()
+        
+        # Handle CSS rgb/rgba format
+        if color_str.startswith(('rgb(', 'rgba(')):
+            try:
+                nums = list(map(float, re.findall(r"[\d.]+", color_str)))
+                if 3 <= len(nums) <= 4:
+                    rgb = tuple(x/255 if i < 3 else x for i, x in enumerate(nums))
+                    if alpha is not None:
+                        return (*rgb[:3], alpha)
+                    return rgb[:4] if len(rgb) == 4 else rgb[:3]
+            except:
+                pass
+        
+        # Handle CSS hsl/hsla format
+        elif color_str.startswith(('hsl(', 'hsla(')):
+            try:
+                nums = list(map(float, re.findall(r"[\d.]+", color_str)))
+                if 3 <= len(nums) <= 4:
+                    h, s, l = nums[0]/360, nums[1]/100, nums[2]/100
+                    rgb = mcolors.hsv_to_rgb((h, s, l))
+                    if len(nums) == 4:
+                        rgb += (nums[3],)
+                    if alpha is not None:
+                        return (*rgb[:3], alpha)
+                    return rgb[:4] if len(rgb) == 4 else rgb[:3]
+            except:
+                pass
+        
+        # Standard hex/named color processing
+        try:
+            rgb = mcolors.to_rgba(color_str)
+            if alpha is not None:
+                return (*rgb[:3], alpha)
+            return rgb if len(rgb) == 4 and rgb[3] != 1 else rgb[:3]
+        except ValueError:
+            pass
+    
+    # Fallback for invalid colors
+    print(f"Warning: Invalid color format '{color_input}'")
+    return None
+ 
+def color2hex(
+    color_input: str | tuple | list | dict | int | None,
+    keep_alpha: bool = False,
+    force_long: bool = False,
+    uppercase: bool = False,
+    prefix: str = "#",
+    allow_short: bool = True
+) -> str | None:
+    """
+    Ultimate color to hex converter with comprehensive format support.
+    
+    Parameters:
+    -----------
+    color_input : str | tuple | list | dict | int | None
+        Input color in any of these formats:
+        - Hex strings ("#RRGGBB", "#RGB", "RRGGBB", "RGB")
+        - Named colors ("red", "blue", "transparent")
+        - RGB/RGBA tuples ((0.2, 0.4, 0.6), (255, 0, 0), (100, 100, 100, 0.5))
+        - CSS formats:
+          - rgb(100,200,50)
+          - rgba(100,200,50,0.8)
+          - hsl(120,60%,70%)
+          - hsla(120,60%,70%,0.8)
+        - Integer RGB (0xFF0000 for red)
+        - Dictionary {"r": 255, "g": 0, "b": 0} or {"h": 0, "s": 100, "l": 50}
+    keep_alpha : bool, optional
+        Whether to include alpha channel in hex format (#RRGGBBAA)
+    force_long : bool, optional
+        Force 6/8-digit hex even when 3/4-digit would be possible
+    uppercase : bool, optional
+        Use uppercase hex characters (False for lowercase)
+    prefix : str, optional
+        Prefix for hex string ("#" for CSS, "0x" for programming, "" for raw)
+    allow_short : bool, optional
+        Allow shortened 3/4-digit hex when possible
+    
+    Returns:
+    --------
+    str | None
+        Hex color string or None if invalid
+        
+    Examples:
+    ---------
+    >>> color2hex((0.5, 0.2, 0.8)) → "#7f33cc"
+    >>> color2hex("rgb(127, 51, 204)") → "#7f33cc"
+    >>> color2hex((0.2, 0.4, 0.6, 0.8), True) → "#336699cc"
+    >>> color2hex(0xFF0000, uppercase=True) → "#FF0000"
+    >>> color2hex({"r": 255, "g": 165, "b": 0}, prefix="") → "ffa500"
+    >>> color2hex("hsl(120, 100%, 50%)") → "#00ff00"
+    """
+    from matplotlib import colors as mcolors
+    import re
+    
+    def to_rgba(color) -> tuple | None:
+        """Internal conversion to RGBA tuple"""
+        # Handle None
+        if color is None:
+            return None
+            
+        # Handle integer RGB
+        if isinstance(color, int):
+            if color < 0:
+                return None
+            return (
+                (color >> 16) & 0xFF,
+                (color >> 8) & 0xFF,
+                color & 0xFF,
+                255
+            )
+        
+        # Handle dictionary formats
+        if isinstance(color, dict):
+            keys = set(color.keys())
+            if {'r','g','b'}.issubset(keys):
+                return (
+                    color['r'] / 255 if color['r'] > 1 else color['r'],
+                    color['g'] / 255 if color['g'] > 1 else color['g'],
+                    color['b'] / 255 if color['b'] > 1 else color['b'],
+                    color.get('a', 1.0)
+                )
+            elif {'h','s','l'}.issubset(keys):
+                return mcolors.hsv_to_rgb((
+                    color['h'] / 360,
+                    color['s'] / 100,
+                    color['l'] / 100
+                )) + (color.get('a', 1.0),)
+            return None
+        
+        # Handle string formats
+        if isinstance(color, str):
+            color = color.strip().lower()
+            
+            # Handle hex without prefix
+            if re.match(r'^[0-9a-f]{3,8}$', color):
+                return mcolors.to_rgba(f"#{color}")
+                
+            # Handle CSS functions
+            if color.startswith(('rgb(', 'rgba(', 'hsl(', 'hsla(')):
+                try:
+                    return mcolors.to_rgba(color)
+                except ValueError:
+                    return None
+                    
+            # Handle named colors (including 'transparent')
+            try:
+                return mcolors.to_rgba(color)
+            except ValueError:
+                return None
+        
+        # Handle tuple/list formats
+        if isinstance(color, (tuple, list)):
+            if len(color) in (3, 4):
+                # Normalize values
+                normalized = []
+                for i, v in enumerate(color):
+                    if i < 3:  # RGB channels
+                        if isinstance(v, int):
+                            normalized.append(v / 255 if v > 1 else v)
+                        else:
+                            normalized.append(float(v))
+                    else:  # Alpha channel
+                        normalized.append(float(v))
+                return tuple(normalized)
+        
+        return None
+    
+    # Convert input to RGBA
+    rgba = to_rgba(color_input)
+    if rgba is None:
+        return None
+    
+    # Extract components
+    components = []
+    for i, c in enumerate(rgba):
+        if i == 3 and not keep_alpha:
+            break
+        components.append(round(c * 255 if c <= 1 else c))
+    
+    # Determine if we can use short format
+    use_short = (allow_short and 
+                not force_long and 
+                len(components) in (3, 4) and
+                all((x % 17 == 0) for x in components[:3]))
+    
+    # Format the hex string
+    if use_short:
+        short_components = [x//17 for x in components[:3]] + components[3:]
+        hex_str = "".join(f"{x:1x}" for x in short_components)
+    else:
+        hex_str = "".join(f"{x:02x}" for x in components)
+    
+    # Apply case and prefix
+    if uppercase:
+        hex_str = hex_str.upper()
+    
+    return f"{prefix}{hex_str}"
+# ! format excel file
+ 
+def hex2argb(color):
+    """
+    Convert a color name or hex code to aARGB format required by openpyxl.
+
+    :param color: A color in the format: 'blue', '#RRGGBB', 'RRGGBB', 'aARRGGBB'
+    :return: A hex color code in the format aARRGGBB.
+
+    Example:
+        print(hex2argb("blue"))      # Output: FF0000FF
+        print(hex2argb("FFFF00"))    # Output: FFFFFF00
+        print(hex2argb("#DF4245"))   # Output: FFDf4245
+        print(hex2argb("FF00FF00"))  # Output: FF00FF00 (already in aARGB format)
+    """
+    import matplotlib.colors as mcolors
+    import re
+    color = color.lower().replace(" ", "") # 'light blue'
+    # Convert color name (e.g., "blue") to hex
     if color.lower() in mcolors.CSS4_COLORS:
         color = mcolors.CSS4_COLORS[color.lower()].lstrip("#")
     color = color.lstrip("#").upper()# Remove '#' if present
     
     # 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:
@@ -9752,6 +10216,624 @@ 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,
+    show: Union[bool, str] = True,
+    exclude: Union[List[str], None,list,int] = None,
+    verbose: bool = False
+) -> None:
+    """
+    Modify sheet visibility in an Excel workbook.
+    set_sheet_visible(fpath=dir_data_collection,sheet_name=None,show=1,verbose=1)
+    Args:
+        fpath (str): Path to the Excel workbook.
+        sheet_name (int | str | None): Index or name of the sheet to apply visibility to.
+                                       If None, all sheets are considered.
+        show (bool | str): Visibility mode. Can be:
+                           - True -> visible
+                           - False -> veryHidden
+                           - 'visible', 'hidden', 'veryHidden' as str
+        exclude (list[str] | None): List of sheet names to exclude from changes.
+        verbose (bool): If True, logs actions.
+    """
+
+    try: 
+        wb = fload(fpath, output="bit", get_validations=1)
+    except Exception as e:
+        raise FileNotFoundError(f"Unable to load workbook: {e}")
+
+    sheet_names = wb.sheetnames
+    if verbose:
+        print("Workbook loaded with sheets:")
+        for i, name in enumerate(sheet_names):
+            print(f"  [{i}] {name}")
+
+    excludes=[]
+    if exclude is None:
+        exclude=[]
+    if ~isinstance(exclude, list):
+        exclude = [exclude]
+    for exclude_ in exclude: 
+        if isinstance(exclude_, str):
+            excludes.append(strcmp(exclude_, sheet_names)[0])
+        elif isinstance(exclude_, int):
+            if 0 <= exclude_ < len(sheet_names):
+                excludes.append(sheet_names[exclude_])
+            else:
+                raise IndexError(f"sheet_name index {exclude_} is out of range:0~{len(sheet_names)-1}.")
+
+    # Resolve the sheet_name target
+    target_indices = []
+    if not isinstance(sheet_name,list):
+        sheet_name=[sheet_name]
+    for sheet_name_ in sheet_name:
+        if sheet_name_ is None:
+            target_indices = list(range(len(sheet_names)))
+            break
+        elif isinstance(sheet_name_, int):
+            if 0 <= sheet_name_ < len(sheet_names):
+                target_indices.append(sheet_name_)
+            else:
+                raise IndexError(f"sheet_name index {sheet_name_} is out of range :0~{len(sheet_names)-1}.")
+        elif isinstance(sheet_name_, str):
+            idx = strcmp(sheet_name_, sheet_names)[1]
+            if idx == -1:
+                raise ValueError(f"Sheet '{sheet_name_}' not found.")
+            target_indices.append(idx)
+
+    # Map show argument to valid state
+    valid_states = ["veryHidden", "visible", "hidden"]
+    if isinstance(show, str):
+        if show not in valid_states:
+            raise ValueError(f"Invalid show value '{show}'. Must be one of {valid_states}")
+        state = show
+    else:
+        state = "visible" if show else "veryHidden" 
+    # Modify sheet visibility
+    for idx in target_indices:
+        ws= wb[sheet_names[idx]]
+        if ws.title in excludes:
+            if verbose:
+                print(f"Skipping excluded sheet: '{ws.title}'")
+            continue
+        ws.sheet_state = state 
+    # Ensure at least one sheet is visible
+    visible_sheets = [s for s in wb.worksheets if s.sheet_state == "visible"]
+    not_visible_sheets = [s for s in wb.worksheets if s.sheet_state != "visible"]
+    if not visible_sheets:
+        fallback_sheet = wb.worksheets[0]
+        fallback_sheet.sheet_state = "visible"
+        if verbose:
+            print(f"No visible sheets found. Setting '{fallback_sheet.title}' to visible.")
+    if verbose:
+        print(f"visible sheets:{[s.title for s in visible_sheets]}")
+
+    try:
+        wb.save(fpath) 
+    except Exception as e:
+        raise IOError(f"Error saving workbook: {e}") 
+
 
 def format_excel(
     df: pd.DataFrame=None,
@@ -9780,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,
@@ -9942,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.
@@ -10047,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():
@@ -10244,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,表示其它的所有的都设置成为一样的
@@ -10374,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:
@@ -10451,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)
@@ -10782,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):
@@ -11276,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):
@@ -13282,61 +14468,630 @@ def df_fillna(
                 strategy="constant", fill_value=constant
             )
         else:
-            non_numeric_imputer = SimpleImputer(strategy="most_frequent")
+            non_numeric_imputer = SimpleImputer(strategy="most_frequent")
+
+        # Impute non-numeric columns column-wise (axis=0)
+        imputed_non_numeric = non_numeric_imputer.fit_transform(non_numeric_data)
+
+        # Convert imputed non-numeric array back to DataFrame with original index and column names
+        imputed_non_numeric_df = pd.DataFrame(
+            imputed_non_numeric,
+            index=non_numeric_data.index,
+            columns=non_numeric_data.columns,
+        )
+    else:
+        imputed_non_numeric_df = pd.DataFrame(index=data.index)
+
+    imputed_data = pd.concat([imputed_data, imputed_non_numeric_df], axis=1).reindex(
+        columns=data.columns
+    )
+
+    if inplace:
+        # Modify the original DataFrame
+        data[:] = imputed_data[col_names_org]
+        return None
+    else:
+        # Return the modified DataFrame
+        return imputed_data[col_names_org]
+
+
+# # example
+# data = {
+#     "A": [1, 2, np.nan, 4, 5],
+#     "B": [np.nan, 2, 3, 4, np.nan],
+#     "C": [1, np.nan, 3, 4, 5],
+#     "D": [1, 2, 3, 4, np.nan],
+# }
+
+# # Define a function to test each imputation method
+# methods = [
+#     "mean",
+#     "median",
+#     "most_frequent",
+#     "constant",
+#     "knn",
+#     "iterative",
+#     # "missforest",
+#     # "softimpute",
+#     # "svd",
+# ]
+
+# # Create a dictionary to hold results
+# results = {}
+
+# for method_name in methods:
+#     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 ')'}"
 
-        # Impute non-numeric columns column-wise (axis=0)
-        imputed_non_numeric = non_numeric_imputer.fit_transform(non_numeric_data)
+                labels.append(label)
 
-        # Convert imputed non-numeric array back to DataFrame with original index and column names
-        imputed_non_numeric_df = pd.DataFrame(
-            imputed_non_numeric,
-            index=non_numeric_data.index,
-            columns=non_numeric_data.columns,
+        binned = pd.cut(
+            col, bins=bin_edges, labels=labels, right=right, include_lowest=True
         )
-    else:
-        imputed_non_numeric_df = pd.DataFrame(index=data.index)
+        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")
 
-    imputed_data = pd.concat([imputed_data, imputed_non_numeric_df], axis=1).reindex(
-        columns=data.columns
-    )
+    if not inplace:
+        df = df.copy()
 
-    if inplace:
-        # Modify the original DataFrame
-        data[:] = imputed_data[col_names_org]
-        return None
+    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:
-        # Return the modified DataFrame
-        return imputed_data[col_names_org]
+        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))
+        )
 
-# # example
-# data = {
-#     "A": [1, 2, np.nan, 4, 5],
-#     "B": [np.nan, 2, 3, 4, np.nan],
-#     "C": [1, np.nan, 3, 4, 5],
-#     "D": [1, 2, 3, 4, np.nan],
-# }
+    # Sort labels if requested
+    if sort_labels and not right and len(bin_labels) > 1:
+        binned = _sort_bin_labels(binned, bin_labels)
 
-# # Define a function to test each imputation method
-# methods = [
-#     "mean",
-#     "median",
-#     "most_frequent",
-#     "constant",
-#     "knn",
-#     "iterative",
-#     # "missforest",
-#     # "softimpute",
-#     # "svd",
-# ]
+    # Create final output column
+    new_col = new_col_name or f"{column}_binned"
+    df[new_col] = binned.astype(dtype) if dtype else binned
 
-# # Create a dictionary to hold results
-# results = {}
+    if drop_original:
+        df.drop(columns=[column], inplace=True)
+
+    return None if inplace else df
 
-# for method_name in methods:
-#     print(method_name)
-#     display(df)
-#     display(df_fillna(data=df, method=method_name, inplace=False, axis=0))
 
 
 def df_encoder(
@@ -14580,209 +16335,213 @@ def df_reducer(
 
 # example:
 # df_reducer(data=data_log, columns=markers, n_components=2)
+ 
 
 
-def get_df_format(data, threshold_unique=0.5, verbose=False):
+def get_df_format(data, threshold_unique=0.5, verbose=False, sample_size=1000):
     """
-    检测表格: long, wide or uncertain.
-
+    Detect whether a DataFrame is in long or wide format with optimized performance and accuracy.
+    
     Parameters:
-    - data (pd.DataFrame): DataFrame to check.
-    - threshold_unique (float): Proportion threshold for detecting categorical columns.
-
+    - data (pd.DataFrame): DataFrame to analyze
+    - threshold_unique (float): Threshold for categorical column detection (0-1)
+    - verbose (bool): Whether to print diagnostic messages
+    - sample_size (int): Maximum number of rows/columns to sample for large datasets
+    
     Returns:
-    - "long" if detected as long format,
+    - "long" if detected as long format
     - "wide" if detected as wide format
-    - "uncertain" if ambiguous.
+    - "uncertain" if format is ambiguous
     """
+    import pandas as pd
+    import numpy as np
     from scipy.stats import entropy
     from sklearn.cluster import AgglomerativeClustering
     from sklearn.preprocessing import StandardScaler
-
-    long_score,wide_score,fs = 0,0,500
-    n_rows, n_cols = data.shape
-    # -----to reduce memory, only check 500 rows/columns----
-    if n_rows > fs:
-        if verbose:
-            print(f"Sampling {fs} rows from {n_rows} rows.")
-        data = data.sample(n=fs, random_state=1)
-    if n_cols > fs:
-        if verbose:
-            print(f"Using first {fs} columns out of {n_cols} columns.")
-        data = data.iloc[:, :fs]
+    from sklearn.metrics import pairwise_distances
+    from collections import Counter
+    import re
+    # ----- Initial Setup and Sampling -----
     n_rows, n_cols = data.shape
+    if verbose:
+        print(f"Initial shape: {n_rows} rows, {n_cols} columns")
     
-    # Step 1: Row-Column Ratio Heuristic
-    if n_rows > 3 * n_cols:
-        long_score += 2
-        if verbose:
-            print(
-                "Row-Column Ratio suggests long format (many rows relative to columns)."
-            )
-    elif n_cols > 3 * n_rows:
-        wide_score += 2
-        if verbose:
-            print(
-                "Row-Column Ratio suggests wide format (many columns relative to rows)."
-            )
-
-    # Step 2: Unique-to-duplicate ratio and entropy for categorical variables
-    unique_counts = data.apply(lambda x: x.nunique())
+    # Sample data if too large
+    if n_rows > sample_size:
+        data = data.sample(n=sample_size, random_state=42)
+        n_rows = sample_size
+    if n_cols > sample_size:
+        data = data.iloc[:, :sample_size]
+        n_cols = sample_size
+    
+    # Early exit for tiny datasets
+    if n_rows < 3 or n_cols < 3:
+        return "uncertain"
+    
+    long_score = 0
+    wide_score = 0
+    
+    # ----- Feature Extraction -----
+    # Basic statistics
+    row_col_ratio = n_rows / n_cols if n_cols != 0 else float('inf')
+    
+    # Column types
+    numeric_cols = data.select_dtypes(include=np.number).columns
+    cat_cols = data.select_dtypes(include=['object', 'category']).columns
+    other_cols = [col for col in data.columns if col not in numeric_cols and col not in cat_cols]
+    
+    # Unique value analysis
+    unique_counts = data.nunique(dropna=False)
     duplicate_ratio = 1 - unique_counts / n_rows
-    if (duplicate_ratio > 0.2).sum() > 0.5 * n_cols:
-        wide_score += 2
-        if verbose:
-            print("High duplicate values in columns suggest wide format.")
-    else:
-        long_score += 1
-        if verbose:
-            print(
-                "Lower duplicate ratio suggests long format (higher row variability)."
-            )
-
-    # Calculate entropy for categorical columns
-    categorical_cols = data.select_dtypes(include=["object", "category"]).columns
-    if len(categorical_cols) > 0:
-        for col in categorical_cols:
-            counts = data[col].value_counts(normalize=True)
-            col_entropy = entropy(counts)
-            if col_entropy < 1.5:
-                long_score += 1
-                if verbose:
-                    print(
-                        f"Column '{col}' entropy suggests categorical, supporting long format."
-                    )
-            else:
-                wide_score += 1
-                if verbose:
-                    print(f"Column '{col}' entropy is higher, supporting wide format.")
-
-    # Step 3: Column grouping analysis for patterns in suffixes/prefixes
+    
+    # Missing values
+    missing_per_row = data.isna().sum(axis=1)
+    missing_per_col = data.isna().sum()
+    
+    # Column name patterns
     col_names = data.columns.astype(str)
-    suffix_count = sum("_" in col or col[-1].isdigit() for col in col_names)
-    if suffix_count > 0.3 * n_cols:
+    has_suffix = sum(bool(re.search(r'(_\d+|\d+_?$)', col)) for col in col_names)
+    has_time = sum(bool(re.search(r'(^time|^date|^year|^month|^day|^t\d+)', col.lower())) for col in col_names)
+    
+    # ----- Scoring Rules -----
+    
+    # 1. Row-Column Ratio (weighted)
+    if row_col_ratio > 5:
+        long_score += 3
+        if verbose: print(f"High row/col ratio ({row_col_ratio:.1f}) → long +3")
+    elif row_col_ratio < 0.2:
+        wide_score += 3
+        if verbose: print(f"Low row/col ratio ({row_col_ratio:.1f}) → wide +3")
+    elif row_col_ratio > 2:
+        long_score += 1
+        if verbose: print(f"Moderate row/col ratio ({row_col_ratio:.1f}) → long +1")
+    elif row_col_ratio < 0.5:
+        wide_score += 1
+        if verbose: print(f"Moderate row/col ratio ({row_col_ratio:.1f}) → wide +1")
+    
+    # 2. Duplication Patterns
+    high_dupe_cols = sum(duplicate_ratio > 0.3)
+    if high_dupe_cols > 0.6 * n_cols:
         wide_score += 2
-        if verbose:
-            print(
-                "Detected suffix/prefix patterns in column names, suggesting wide format."
-            )
-
-    # Step 4: Entity identifier detection for long format with categorical columns
-    if len(categorical_cols) > 0 and n_rows > n_cols:
-        entity_identifier_count = sum(
-            data.duplicated(subset=categorical_cols, keep=False)
-        )
-        if entity_identifier_count > 0.2 * n_rows:
+        if verbose: print(f"Many columns ({high_dupe_cols}/{n_cols}) with duplicates → wide +2")
+    elif high_dupe_cols < 0.2 * n_cols:
+        long_score += 1
+        if verbose: print(f"Few columns ({high_dupe_cols}/{n_cols}) with duplicates → long +1")
+    
+    # 3. Categorical Column Analysis
+    if len(cat_cols) > 0:
+        # Entropy analysis
+        cat_entropies = []
+        for col in cat_cols:
+            counts = data[col].value_counts(normalize=True, dropna=False)
+            cat_entropies.append(entropy(counts))
+        
+        avg_cat_entropy = np.mean(cat_entropies) if cat_entropies else 0
+        if avg_cat_entropy < 1.2:
             long_score += 2
-            if verbose:
-                print(
-                    "Significant duplicate rows based on categorical columns, suggesting long format."
-                )
-
-    # Step 5: Clustering analysis on numerical columns for correlation in wide format
-    numeric_cols = data.select_dtypes(include="number").columns
-    if len(numeric_cols) > 1:
-        try:
-            scaled_data = StandardScaler().fit_transform(data[numeric_cols].dropna())
-            clustering = AgglomerativeClustering(n_clusters=2).fit(scaled_data.T)
-            cluster_labels = pd.Series(clustering.labels_)
-            if cluster_labels.nunique() < len(numeric_cols) * 0.5:
-                wide_score += 2
-                if verbose:
-                    print(
-                        "Clustering on columns shows grouping, suggesting wide format."
-                    )
-        except Exception as e:
-            print(e) if verbose else None
-
-    # Step 6: Inter-column correlation analysis
-    if len(numeric_cols) > 1:
+            if verbose: print(f"Low categorical entropy ({avg_cat_entropy:.2f}) → long +2")
+        elif avg_cat_entropy > 2:
+            wide_score += 1
+            if verbose: print(f"High categorical entropy ({avg_cat_entropy:.2f}) → wide +1")
+        
+        # Entity identifier detection
+        if len(cat_cols) >= 2 and n_rows > 10:
+            dup_rows = data.duplicated(subset=cat_cols.tolist()[:2], keep=False).sum()
+            if dup_rows > 0.3 * n_rows:
+                long_score += 2
+                if verbose: print(f"Duplicate rows in categorical cols ({dup_rows}/{n_rows}) → long +2")
+    
+    # 4. Column Name Patterns
+    if has_suffix > 0.4 * n_cols:
+        wide_score += 2
+        if verbose: print(f"Many suffix patterns ({has_suffix}/{n_cols}) → wide +2")
+    if has_time > 0.3 * n_cols:
+        wide_score += 1
+        if verbose: print(f"Time-like columns ({has_time}/{n_cols}) → wide +1")
+    
+    # 5. Numeric Column Analysis (only if enough numeric columns)
+    if len(numeric_cols) > 2:
+        # Correlation analysis
         corr_matrix = data[numeric_cols].corr().abs()
-        avg_corr = (
-            corr_matrix.where(~np.eye(len(corr_matrix), dtype=bool)).mean().mean()
-        )
-        if avg_corr > 0.6:
+        avg_corr = corr_matrix.values[np.triu_indices_from(corr_matrix, k=1)].mean()
+        
+        if avg_corr > 0.5:
             wide_score += 2
-            if verbose:
-                print("High inter-column correlation suggests wide format.")
-
-    # Step 7: Missing value pattern analysis
-    missing_patterns = data.isna().sum(axis=1)
-    if missing_patterns.std() < 2:
+            if verbose: print(f"High numeric correlation ({avg_corr:.2f}) → wide +2")
+        elif avg_corr < 0.2:
+            long_score += 1
+            if verbose: print(f"Low numeric correlation ({avg_corr:.2f}) → long +1")
+        
+        # Entropy analysis
+        try:
+            numeric_data = data[numeric_cols].dropna()
+            if len(numeric_data) > 10:
+                numeric_entropy = numeric_data.apply(lambda x: entropy(pd.cut(x, bins=min(10, len(x.unique())).value_counts(normalize=True))))
+                if numeric_entropy.mean() < 1.5:
+                    wide_score += 1
+                    if verbose: print(f"Low numeric entropy ({numeric_entropy.mean():.2f}) → wide +1")
+        except Exception as e:
+            if verbose: print(f"Numeric entropy failed: {str(e)}")
+    
+    # 6. Missing Value Patterns
+    missing_row_std = missing_per_row.std()
+    if missing_row_std < 1 and missing_per_row.mean() > 0.1 * n_cols:
         wide_score += 1
-        if verbose:
-            print(
-                "Low variation in missing patterns across rows, supporting wide format."
-            )
-    elif missing_patterns.mean() < 1:
+        if verbose: print(f"Uniform missing pattern (std={missing_row_std:.2f}) → wide +1")
+    elif missing_per_row.mean() < 0.05 * n_cols:
         long_score += 1
-        if verbose:
-            print("Lower missing pattern suggests long format (less structured).")
-
-    # Step 8: Multi-level clustering on rows to detect block structure for wide format
-    if len(numeric_cols) > 1 and n_rows > 5:
+        if verbose: print(f"Few missing values → long +1")
+    
+    # 7. Advanced Clustering (only for medium/large datasets)
+    if len(numeric_cols) > 3 and n_rows > 10 and n_cols > 5:
         try:
-            clustering_rows = AgglomerativeClustering(n_clusters=2).fit(scaled_data)
-            if pd.Series(clustering_rows.labels_).nunique() < 2:
-                wide_score += 2
-                if verbose:
-                    print("Row clustering reveals homogeneity, suggesting wide format.")
+            # Efficient clustering with sampling
+            sample_data = data[numeric_cols].sample(n=min(100, n_rows), random_state=42)
+            scaled_data = StandardScaler().fit_transform(sample_data.dropna())
+            
+            if scaled_data.shape[0] > 5:
+                # Column clustering
+                col_dist = pairwise_distances(scaled_data.T)
+                col_clusters = AgglomerativeClustering(n_clusters=2, 
+                                                     affinity='precomputed', 
+                                                     linkage='complete').fit(col_dist)
+                cluster_counts = Counter(col_clusters.labels_)
+                if max(cluster_counts.values()) > 0.7 * len(numeric_cols):
+                    wide_score += 2
+                    if verbose: print(f"Column clustering shows dominant group → wide +2")
+                
+                # Row clustering
+                row_clusters = AgglomerativeClustering(n_clusters=2).fit(scaled_data)
+                row_cluster_counts = Counter(row_clusters.labels_)
+                if max(row_cluster_counts.values()) > 0.8 * scaled_data.shape[0]:
+                    wide_score += 1
+                    if verbose: print(f"Row clustering shows homogeneity → wide +1")
         except Exception as e:
-            print(e) if verbose else None
-
-    # Step 9: Sequential name detection for time-series pattern in wide format
-    if any(col.isdigit() or col.startswith("T") for col in col_names):
-        wide_score += 1
-        if verbose:
-            print("Detected time-like sequential column names, supporting wide format.")
-
-    # Step 10: Entropy of numeric columns
-    try:
-        numeric_entropy = data[numeric_cols].apply(
-            lambda x: entropy(pd.cut(x, bins=10).value_counts(normalize=True))
-        )
-        if numeric_entropy.mean() < 2:
-            wide_score += 2
-            if verbose:
-                print(
-                    "Low entropy in numeric columns indicates stability across columns, supporting wide format."
-                )
-    except Exception as e:
-        print(e) if verbose else None
-
-    # Step 11: Tie-breaking strategy if scores are equal
-    if wide_score == long_score:
-        if n_cols > n_rows:
-            wide_score += 1
-            if verbose:
-                print(
-                    "Tie-breaking based on column-major structure, favoring wide format."
-                )
-        elif n_rows > n_cols:
-            long_score += 1
-            if verbose:
-                print(
-                    "Tie-breaking based on row-major structure, favoring long format."
-                )
-        else:
-            if verbose:
-                print("Tie-breaking inconclusive; returning 'uncertain'.")
-            return "uncertain"
-
-    # Final decision
-    if wide_score > long_score:
-        if verbose:
-            print("Final decision: Wide format.")
-        return "wide"
-    elif long_score > wide_score:
-        if verbose:
-            print("Final decision: Long format.")
-        return "long"
+            if verbose: print(f"Clustering skipped: {str(e)}")
+    
+    # ----- Decision Logic -----
+    score_diff = long_score - wide_score
+    abs_diff = abs(score_diff)
+    
+    if verbose:
+        print(f"\nFinal scores - Long: {long_score}, Wide: {wide_score}")
+    
+    if abs_diff >= 3:
+        return "long" if score_diff > 0 else "wide"
+    elif abs_diff >= 1:
+        # Additional tie-breakers
+        if score_diff == 0:
+            if row_col_ratio > 1.5:
+                return "long"
+            elif row_col_ratio < 0.67:
+                return "wide"
+            elif len(cat_cols) > len(numeric_cols):
+                return "long"
+            else:
+                return "wide"
+        return "long" if score_diff > 0 else "wide"
     else:
-        if verbose:
-            print("Final decision: Uncertain format.")
         return "uncertain"
-
 #! ========== workbook, worksheet, wb,ws =============
 
 import openpyxl
@@ -15917,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")
@@ -17221,3 +18980,290 @@ def set_theme(
         color_codes=color_codes,
         rc=rc_params,
     )
+
+
+
+def df_wide_long(df):
+    rows, columns = df.shape
+    if columns > rows:
+        return "Wide"
+    elif rows > columns:
+        return "Long"
+
+def df2array(data: pd.DataFrame, x=None, y=None, hue=None, sort=False):
+    
+    def sort_rows_move_nan(arr, sort=False):
+        # Handle edge cases where all values are NaN
+        if np.all(np.isnan(arr)):
+            return arr  # Return unchanged if the entire array is NaN
+
+        if sort:
+            # Replace NaNs with a temporary large value for sorting
+            temp_value = (
+                np.nanmax(arr[np.isfinite(arr)]) + 1 if np.any(np.isfinite(arr)) else np.inf
+            )
+            arr_no_nan = np.where(np.isnan(arr), temp_value, arr)
+
+            # Sort each row
+            sorted_arr = np.sort(arr_no_nan, axis=1)
+
+            # Move NaNs to the end
+            result_arr = np.where(sorted_arr == temp_value, np.nan, sorted_arr)
+        else:
+            result_rows = []
+            for row in arr:
+                # Separate non-NaN and NaN values
+                non_nan_values = row[~np.isnan(row)]
+                nan_count = np.isnan(row).sum()
+                # Create a new row with non-NaN values followed by NaNs
+                new_row = np.concatenate([non_nan_values, [np.nan] * nan_count])
+                result_rows.append(new_row)
+            # Convert the list of rows back into a 2D NumPy array
+            result_arr = np.array(result_rows)
+
+        # Remove rows/columns that contain only NaNs
+        clean_arr = result_arr[~np.isnan(result_arr).all(axis=1)]
+        clean_arr_ = clean_arr[:, ~np.isnan(clean_arr).all(axis=0)]
+
+        return clean_arr_
+    # data = data.copy()
+    # data[y] = pd.to_numeric(data[y], errors="coerce")
+    # data = data.dropna(subset=[y])
+    if hue is None:
+        a = []
+        if sort:
+            cat_x = np.sort(data[x].unique().tolist()).tolist()
+        else:
+            cat_x = data[x].unique().tolist()
+        for i, x_ in enumerate(cat_x):
+            new_ = data.loc[data[x] == x_, y].to_list()
+            a = padcat(a, new_, axis=0)
+        return sort_rows_move_nan(a).T
+    else:
+        a = []
+        if sort:
+            cat_x = np.sort(data[x].unique().tolist()).tolist()
+            cat_hue = np.sort(data[hue].unique().tolist()).tolist()
+        else:
+            cat_x = data[x].unique().tolist()
+            cat_hue = data[hue].unique().tolist()
+        for i, x_ in enumerate(cat_x):
+            for j, hue_ in enumerate(cat_hue):
+                new_ = data.loc[(data[x] == x_) & (data[hue] == hue_), y].to_list()
+                a = padcat(a, new_, axis=0)
+        return sort_rows_move_nan(a).T
+
+
+def array2df(data: np.ndarray):
+    df = pd.DataFrame()
+    df["group"] = (
+        np.tile(
+            ["group" + str(i) for i in range(1, data.shape[1] + 1)], [data.shape[0], 1]
+        )
+        .reshape(-1, 1, order="F")[:, 0]
+        .tolist()
+    )
+    df["value"] = data.reshape(-1, 1, order="F")
+    return df
+
+
+def padcat(*args, fill_value=np.nan, axis=1, order="row"):
+    """
+    Concatenate vectors with padding.
+
+    Parameters:
+    *args : variable number of list or 1D arrays
+        Input arrays to concatenate.
+    fill_value : scalar, optional
+        The value to use for padding the shorter lists (default is np.nan).
+    axis : int, optional
+        The axis along which to concatenate (0 for rows, 1 for columns, default is 1).
+    order : str, optional
+        The order for flattening when required: "row" or "column" (default is "row").
+
+    Returns:
+    np.ndarray
+        A 2D array with the input arrays concatenated along the specified axis,
+        padded with fill_value where necessary.
+
+
+# Example usage:
+a = [1, np.nan]
+b = [1, 3, 4, np.nan, 2, np.nan]
+c = [1, 2, 3, 4, 5, 6, 7, 8, 10]
+d = padcat(a, b)
+result1 = padcat(d, c)
+result2 = padcat(a, b, c)
+print("Result of padcat(d, c):\n", result1)
+print("Result of padcat(a, b, c):\n", result2)
+    """
+    # Set the order for processing
+    if "ro" in order.lower():
+        order = "C"  # row-major order
+    else:
+        order = "F"  # column-major order
+
+    # Process input arrays based on their dimensions
+    processed_arrays = []
+    for arg in args:
+        arr = np.asarray(arg)
+        if arr.ndim == 1:
+            processed_arrays.append(arr)  # Keep 1D arrays as is
+        elif arr.ndim == 2:
+            if axis == 0:
+                # If concatenating along rows, split 2D arrays into 1D arrays row-wise
+                processed_arrays.extend(arr)
+            elif axis == 1:
+                # If concatenating along columns, split 2D arrays into 1D arrays column-wise
+                processed_arrays.extend(arr.T)
+            else:
+                raise ValueError("axis must be 0 or 1")
+        else:
+            raise ValueError("Input arrays must be 1D or 2D")
+
+    if axis == 0:
+        # Concatenate along rows
+        max_len = max(arr.size for arr in processed_arrays)
+        result = np.full((len(processed_arrays), max_len), fill_value)
+        for i, arr in enumerate(processed_arrays):
+            result[i, : arr.size] = arr
+    elif axis == 1:
+        # Concatenate along columns
+        max_len = max(arr.size for arr in processed_arrays)
+        result = np.full((max_len, len(processed_arrays)), fill_value)
+        for i, arr in enumerate(processed_arrays):
+            result[: arr.size, i] = arr
+    else:
+        raise ValueError("axis must be 0 or 1")
+
+    return result
+
+ 
+# ========== memory cleaner ==========
+import gc
+import os
+import sys
+import psutil
+import platform
+import ctypes
+import subprocess
+import warnings 
+import time
+
+class MemoryOptimizer:
+    def __init__(self, verbose: bool = True, aggressive_mode: bool = True):
+        self.verbose = verbose
+        self.aggressive_mode = aggressive_mode
+        self.system = platform.system()
+        self.process = psutil.Process(os.getpid())
+        self.start_time = time.time()
+        self.memory_history = []
+
+    def log(self, msg: str, level: str = "INFO"):
+        if self.verbose:
+            rss = self.process.memory_info().rss / (1024 ** 2)
+            elapsed = time.time() - self.start_time
+            print(f"[{level}][{elapsed:.2f}s][{rss:.1f}MB] {msg}")
+
+    def collect_garbage(self):
+        self.log("Performing deep garbage collection...")
+        stats = {}
+        before_mem = self.process.memory_info().rss
+        for gen in reversed(range(3)):
+            collected = gc.collect(gen)
+            self.log(f"GC Gen {gen}: Collected {collected}")
+        gc.garbage.clear()
+        after_mem = self.process.memory_info().rss
+        stats['freed_mb'] = (before_mem - after_mem) / (1024 ** 2)
+        return stats
+
+    def clear_frameworks(self):
+        result = {}
+        try:
+            import torch
+            if torch.cuda.is_available():
+                self.log("Clearing PyTorch cache...")
+                torch.cuda.empty_cache()
+                torch.cuda.ipc_collect()
+                result['pytorch'] = 'cleared'
+        except Exception as e:
+            self.log(f"PyTorch skipped: {e}", "WARNING")
+
+        try:
+            import tensorflow as tf
+            self.log("Clearing TensorFlow session...")
+            tf.keras.backend.clear_session()
+            result['tensorflow'] = 'cleared'
+        except Exception as e:
+            self.log(f"TensorFlow skipped: {e}", "WARNING")
+
+        try:
+            import cv2
+            self.log("Closing OpenCV windows...")
+            cv2.destroyAllWindows()
+            result['opencv'] = 'cleared'
+        except Exception:
+            pass
+
+        try:
+            import matplotlib.pyplot as plt
+            self.log("Closing matplotlib figures...")
+            plt.close('all')
+            result['matplotlib'] = 'cleared'
+        except Exception:
+            pass
+
+        return result
+
+    def clear_system_caches(self):
+        result = {}
+        self.log("Attempting full system cache clearance...")
+        try:
+            if self.system == "Linux":
+                subprocess.run(["sync"], check=True)
+                subprocess.run(["sudo", "sh", "-c", "echo 3 > /proc/sys/vm/drop_caches"], check=True)
+                result['linux'] = 'caches dropped'
+            elif self.system == "Darwin":
+                subprocess.run(["sudo", "purge"], check=True)
+                result['macos'] = 'purge run'
+            elif self.system == "Windows":
+                ctypes.windll.psapi.EmptyWorkingSet(-1)
+                if self.aggressive_mode:
+                    ctypes.windll.kernel32.SetProcessWorkingSetSizeEx(
+                        -1, ctypes.c_size_t(-1), ctypes.c_size_t(-1), ctypes.c_uint(0x1)
+                    )
+                result['windows'] = 'working set emptied'
+        except Exception as e:
+            self.log(f"System cache clearing failed: {e}", "ERROR")
+        return result
+
+    def profile(self) -> Dict[str, Any]:
+        mem = self.process.memory_info()
+        vm = psutil.virtual_memory()
+        profile = {
+            'rss_mb': mem.rss / (1024 ** 2),
+            'vms_mb': mem.vms / (1024 ** 2),
+            'used_gb': vm.used / (1024 ** 3),
+            'available_gb': vm.available / (1024 ** 3),
+            'percent': vm.percent,
+        }
+        self.memory_history.append(profile)
+        return profile
+
+    def optimize(self) -> Dict[str, Any]:
+        result = {}
+        result['before'] = self.profile()
+        result['gc'] = self.collect_garbage()
+        result['frameworks'] = self.clear_frameworks()
+        result['system'] = self.clear_system_caches()
+        result['after'] = self.profile()
+        saved = result['before']['rss_mb'] - result['after']['rss_mb']
+        result['saved_mb'] = saved
+        result['saved_percent'] = (saved / result['before']['rss_mb']) * 100 if result['before']['rss_mb'] else 0
+        self.log(f"Optimization complete: Saved {saved:.2f} MB ({result['saved_percent']:.1f}%)", "SUCCESS")
+        return result
+
+
+def cleaner(verbose: bool = True, aggressive: bool = True) -> Dict[str, Any]:
+    optimizer = MemoryOptimizer(verbose=verbose, aggressive_mode=aggressive)
+    return optimizer.optimize()