dragon-ml-toolbox 19.13.0__py3-none-any.whl → 20.0.0__py3-none-any.whl

ml_tools/path_manager/_path_tools.py

@@ -0,0 +1,346 @@
+from typing import Optional, Union, Literal
+from pathlib import Path
+import re
+import shutil
+
+from .._core import get_logger
+
+
+_LOGGER = get_logger("Path Ops")
+
+
+__all__ = [
+    "make_fullpath",
+    "sanitize_filename",
+    "list_csv_paths",
+    "list_files_by_extension",
+    "list_subdirectories",
+    "clean_directory",
+    "safe_move",
+]
+
+
+def make_fullpath(
+        input_path: Union[str, Path],
+        make: bool = False,
+        verbose: bool = False,
+        enforce: Optional[Literal["directory", "file"]] = None
+    ) -> Path:
+    """
+    Resolves a string or Path into an absolute Path, optionally creating it.
+
+    - If the path exists, it is returned.
+    - If the path does not exist and `make=True`, it will:
+        - Create the file if the path has a suffix
+        - Create the directory if it has no suffix
+    - If `make=False` and the path does not exist, an error is raised.
+    - If `enforce`, raises an error if the resolved path is not what was enforced.
+    - Optionally prints whether the resolved path is a file or directory.
+
+    Parameters:
+        input_path (str | Path): 
+            Path to resolve.
+        make (bool): 
+            If True, attempt to create file or directory.
+        verbose (bool): 
+            Print classification after resolution.
+        enforce ("directory" | "file" | None):
+            Raises an error if the resolved path is not what was enforced.
+
+    Returns:
+        Path: Resolved absolute path.
+
+    Raises:
+        ValueError: If the path doesn't exist and can't be created.
+        TypeError: If the final path does not match the `enforce` parameter.
+        
+    ## 🗒️ Note:
+    
+    Directories with dots will be treated as files.
+    
+    Files without extension will be treated as directories.
+    """
+    path = Path(input_path).expanduser()
+
+    is_file = path.suffix != ""
+
+    try:
+        resolved = path.resolve(strict=True)
+    except FileNotFoundError:
+        if not make:
+            _LOGGER.error(f"Path does not exist: '{path}'.")
+            raise FileNotFoundError()
+
+        try:
+            if is_file:
+                # Create parent directories first
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.touch(exist_ok=False)
+            else:
+                path.mkdir(parents=True, exist_ok=True)
+            resolved = path.resolve(strict=True)
+        except Exception:
+            _LOGGER.exception(f"Failed to create {'file' if is_file else 'directory'} '{path}'.")
+            raise IOError()
+    
+    if enforce == "file" and not resolved.is_file():
+        _LOGGER.error(f"Path was enforced as a file, but it is not: '{resolved}'")
+        raise TypeError()
+    
+    if enforce == "directory" and not resolved.is_dir():
+        _LOGGER.error(f"Path was enforced as a directory, but it is not: '{resolved}'")
+        raise TypeError()
+
+    if verbose:
+        if resolved.is_file():
+            print("📄 Path is a File")
+        elif resolved.is_dir():
+            print("📁 Path is a Directory")
+        else:
+            print("❓ Path exists but is neither file nor directory")
+
+    return resolved
+
+
+def sanitize_filename(filename: str) -> str:
+    """
+    Sanitizes the name by:
+    - Stripping leading/trailing whitespace.
+    - Replacing all internal whitespace characters with underscores.
+    - Removing or replacing characters invalid in filenames.
+
+    Args:
+        filename (str): Base filename.
+
+    Returns:
+        str: A sanitized string suitable to use as a filename.
+    """
+    # Strip leading/trailing whitespace
+    sanitized = filename.strip()
+    
+    # Replace all whitespace sequences (space, tab, etc.) with underscores
+    sanitized = re.sub(r'\s+', '_', sanitized)
+
+    # Conservative filter to keep filenames safe across platforms
+    sanitized = re.sub(r'[^\w\-.]', '', sanitized)
+    
+    # Check for empty string after sanitization
+    if not sanitized:
+        _LOGGER.error("The sanitized filename is empty. The original input may have contained only invalid characters.")
+        raise ValueError()
+
+    return sanitized
+
+
+def list_csv_paths(directory: Union[str, Path], verbose: bool = True, raise_on_empty: bool = True) -> dict[str, Path]:
+    """
+    Lists all `.csv` files in the specified directory and returns a mapping: filenames (without extensions) to their absolute paths.
+
+    Parameters:
+        directory (str | Path): Path to the directory containing `.csv` files.
+        verbose (bool): If True, prints found files.
+        raise_on_empty (bool): If True, raises IOError if no files are found.
+
+    Returns:
+        (dict[str, Path]): Dictionary mapping {filename: filepath}.
+    """
+    # wraps the more general function
+    return list_files_by_extension(directory=directory, extension="csv", verbose=verbose, raise_on_empty=raise_on_empty)
+
+
+def list_files_by_extension(
+    directory: Union[str, Path], 
+    extension: str, 
+    verbose: bool = True,
+    raise_on_empty: bool = True
+) -> dict[str, Path]:
+    """
+    Lists all files with the specified extension in the given directory and returns a mapping: 
+    filenames (without extensions) to their absolute paths.
+
+    Parameters:
+        directory (str | Path): Path to the directory to search in.
+        extension (str): File extension to search for (e.g., 'json', 'txt').
+        verbose (bool): If True, logs the files found.
+        raise_on_empty (bool): If True, raises IOError if no matching files are found.
+
+    Returns:
+        (dict[str, Path]): Dictionary mapping {filename: filepath}. Returns empty dict if none found and raise_on_empty is False.
+    """
+    dir_path = make_fullpath(directory, enforce="directory")
+    
+    # Normalize the extension (remove leading dot if present)
+    normalized_ext = extension.lstrip(".").lower()
+    pattern = f"*.{normalized_ext}"
+    
+    matched_paths = list(dir_path.glob(pattern))
+    
+    if not matched_paths:
+        msg = f"No '.{normalized_ext}' files found in directory: {dir_path}."
+        if raise_on_empty:
+            _LOGGER.error(msg)
+            raise IOError()
+        else:
+            if verbose:
+                _LOGGER.warning(msg)
+            return {}
+
+    name_path_dict = {p.stem: p for p in matched_paths}
+    
+    if verbose:
+        _LOGGER.info(f"📂 '{normalized_ext.upper()}' files found:")
+        for name in name_path_dict:
+            print(f"\t{name}")
+    
+    return name_path_dict
+
+
+def list_subdirectories(
+    root_dir: Union[str, Path], 
+    verbose: bool = True, 
+    raise_on_empty: bool = True
+) -> dict[str, Path]:
+    """
+    Scans a directory and returns a dictionary of its immediate subdirectories.
+
+    Args:
+        root_dir (str | Path): The path to the directory to scan.
+        verbose (bool): If True, prints the number of directories found. 
+        raise_on_empty (bool): If True, raises IOError if no subdirectories are found.
+
+    Returns:
+        dict[str, Path]: A dictionary mapping subdirectory names (str) to their full Path objects.
+    """
+    root_path = make_fullpath(root_dir, enforce="directory")
+    
+    directories = [p.resolve() for p in root_path.iterdir() if p.is_dir()]
+    
+    if len(directories) < 1:
+        msg = f"No subdirectories found inside '{root_path}'"
+        if raise_on_empty:
+            _LOGGER.error(msg)
+            raise IOError()
+        else:
+            if verbose:
+                _LOGGER.warning(msg)
+            return {}
+    
+    if verbose:
+        count = len(directories)
+        # Use pluralization for better readability
+        plural = 'ies' if count != 1 else 'y'
+        print(f"Found {count} subdirector{plural} in '{root_path.name}'.")
+    
+    # Create a dictionary where the key is the directory's name (a string)
+    # and the value is the full Path object.
+    dir_map = {p.name: p for p in directories}
+    
+    return dir_map
+
+
+def clean_directory(directory: Union[str, Path], verbose: bool = False) -> None:
+    """
+    ⚠️  DANGER: DESTRUCTIVE OPERATION ⚠️
+
+    Deletes all files and subdirectories inside the specified directory. It is designed to empty a folder, not delete the folder itself.
+
+    Safety: It skips hidden files and directories (those starting with a period '.'). This works for macOS/Linux hidden files and dot-config folders on Windows.
+
+    Args:
+        directory (str | Path): The directory path to clean.
+        verbose (bool): If True, prints the name of each top-level item deleted.
+    """
+    target_dir = make_fullpath(directory, enforce="directory")
+
+    if verbose:
+        _LOGGER.warning(f"Starting cleanup of directory: {target_dir}")
+
+    for item in target_dir.iterdir():
+        # Safety Check: Skip hidden files/dirs
+        if item.name.startswith("."):
+            continue
+
+        try:
+            if item.is_file() or item.is_symlink():
+                item.unlink()
+                if verbose:
+                    print(f"    🗑️  Deleted file: {item.name}")
+            elif item.is_dir():
+                shutil.rmtree(item)
+                if verbose:
+                    print(f"    🗑️  Deleted directory: {item.name}")
+        except Exception as e:
+            _LOGGER.warning(f"Failed to delete item '{item.name}': {e}")
+            continue
+
+
+def safe_move(
+    source: Union[str, Path], 
+    final_destination: Union[str, Path], 
+    rename: Optional[str] = None, 
+    overwrite: bool = False
+) -> Path:
+    """
+    Moves a file or directory to a destination directory with safety checks.
+
+    Features:
+    - Supports optional renaming (sanitized automatically).
+    - PRESERVES file extensions during renaming (cannot be modified).
+    - Prevents accidental overwrites unless explicit.
+
+    Args:
+        source (str | Path): The file or directory to move.
+        final_destination (str | Path): The destination DIRECTORY where the item will be moved. It will be created if it does not exist.
+        rename (Optional[str]): If provided, the moved item will be renamed to this. Note: For files, the extension is strictly preserved.
+        overwrite (bool): If True, overwrites the destination path if it exists.
+    
+    Returns:
+        Path: The new absolute path of the moved item.
+    """
+    # 1. Validation and Setup
+    src_path = make_fullpath(source, make=False)
+
+    # Ensure destination directory exists
+    dest_dir_path = make_fullpath(final_destination, make=True, enforce="directory")
+
+    # 2. Determine Target Name
+    if rename:
+        sanitized_name = sanitize_filename(rename)
+        if src_path.is_file():
+            # Strict Extension Preservation
+            final_name = f"{sanitized_name}{src_path.suffix}"
+        else:
+            final_name = sanitized_name
+    else:
+        final_name = src_path.name
+
+    final_path = dest_dir_path / final_name
+
+    # 3. Safety Checks (Collision Detection)
+    if final_path.exists():
+        if not overwrite:
+            _LOGGER.error(f"Destination already exists: '{final_path}'. Use overwrite=True to force.")
+            raise FileExistsError()
+        
+        # Smart Overwrite Handling
+        if final_path.is_dir():
+            if src_path.is_file():
+                _LOGGER.error(f"Cannot overwrite directory '{final_path}' with file '{src_path}'")
+                raise IsADirectoryError()
+            # If overwriting a directory, we must remove the old one first to avoid nesting/errors
+            shutil.rmtree(final_path)
+        else:
+            # Destination is a file
+            if src_path.is_dir():
+                _LOGGER.error(f"Cannot overwrite file '{final_path}' with directory '{src_path}'")
+                raise FileExistsError()
+            final_path.unlink()
+
+    # 4. Perform Move
+    try:
+        shutil.move(str(src_path), str(final_path))
+        return final_path
+    except Exception as e:
+        _LOGGER.exception(f"Failed to move '{src_path}' to '{final_path}'")
+        raise e
+

ml_tools/plot_fonts/__init__.py

@@ -0,0 +1,8 @@
+from ._plot_fonts import configure_cjk_fonts
+
+from ._imprimir import info
+
+
+__all__ = [
+    "configure_cjk_fonts"
+]

ml_tools/plot_fonts/_imprimir.py

@@ -0,0 +1,8 @@
+from .._core import _imprimir_disponibles
+
+_GRUPOS = [
+    "configure_cjk_fonts"
+]
+
+def info():
+    _imprimir_disponibles(_GRUPOS)

ml_tools/{_core → plot_fonts}/_plot_fonts.py

@@ -2,8 +2,8 @@ import matplotlib.pyplot as plt
 from matplotlib import font_manager as fm
 import platform
 
-from ._script_info import _script_info
-from ._logger import get_logger
+from .._core import get_logger
+
 
 _LOGGER = get_logger("Plot Fonts")
 
@@ -62,6 +62,3 @@ def configure_cjk_fonts(verbose: bool = True) -> None:
         if verbose:
             _LOGGER.warning(f"No suitable Simplified Chinese fonts found for {system}. Text may not render correctly.")
 
-
-def info():
-    _script_info(__all__)

ml_tools/schema/__init__.py

@@ -0,0 +1,15 @@
+from ._feature_schema import FeatureSchema
+
+from ._gui_schema import (
+    create_guischema_template, 
+    make_multibinary_groups
+)
+
+from ._imprimir import info
+
+
+__all__ = [
+    "FeatureSchema",
+    "create_guischema_template",
+    "make_multibinary_groups",
+]

ml_tools/schema/_feature_schema.py

@@ -0,0 +1,223 @@
+from typing import NamedTuple, Optional, Union, Any
+from pathlib import Path
+import json
+
+from ..IO_tools import save_list_strings
+
+from .._core import get_logger
+from ..path_manager import make_fullpath
+from ..keys._keys import SchemaKeys, DatasetKeys, PytorchModelArchitectureKeys
+
+from .._core._schema_load_ops import prepare_schema_from_json
+
+
+_LOGGER = get_logger("FeatureSchema")
+
+
+__all__ = [
+    "FeatureSchema",
+]
+
+
+class FeatureSchema(NamedTuple):
+    """Holds the final, definitive schema for the model pipeline."""
+    
+    # The final, ordered list of all feature names
+    feature_names: tuple[str, ...]
+    
+    # List of all continuous feature names
+    continuous_feature_names: tuple[str, ...]
+    
+    # List of all categorical feature names
+    categorical_feature_names: tuple[str, ...]
+    
+    # Map of {column_index: cardinality} for categorical features
+    categorical_index_map: Optional[dict[int, int]]
+    
+    # Map string-to-int category values (e.g., {'color': {'red': 0, 'blue': 1}})
+    categorical_mappings: Optional[dict[str, dict[str, int]]]
+    
+    def to_json(self, directory: Union[str, Path], verbose: bool = True) -> None:
+        """
+        Saves the schema as 'FeatureSchema.json' to the provided directory. 
+        
+        Handles conversion of Tuple->List and IntKeys->StrKeys automatically.
+        """
+        # validate path
+        dir_path = make_fullpath(directory, enforce="directory")
+        file_path = dir_path / SchemaKeys.SCHEMA_FILENAME
+        
+        try:
+            # Convert named tuple to dict
+            data = self._asdict()
+            
+            # Write to disk
+            with open(file_path, 'w', encoding='utf-8') as f:
+                json.dump(data, f, indent=4)
+                
+            if verbose:
+                _LOGGER.info(f"FeatureSchema saved to '{dir_path.name}/{SchemaKeys.SCHEMA_FILENAME}'")
+                
+        except (IOError, TypeError) as e:
+            _LOGGER.error(f"Failed to save FeatureSchema to JSON: {e}")
+            raise e
+        
+    @classmethod
+    def from_json(cls, directory: Union[str, Path], verbose: bool = True) -> 'FeatureSchema':
+        """
+        Loads a 'FeatureSchema.json' from the provided directory.
+        
+        Restores Tuples from Lists and Integer Keys from Strings.
+        """
+        # validate directory
+        dir_path = make_fullpath(directory, enforce="directory")
+        file_path = dir_path / SchemaKeys.SCHEMA_FILENAME
+        
+        if not file_path.exists():
+            _LOGGER.error(f"FeatureSchema file not found at '{directory}'")
+            raise FileNotFoundError()
+        
+        try:
+            with open(file_path, 'r', encoding='utf-8') as f:
+                data: dict[str, Any] = json.load(f)
+            
+            # Logic delegated to shared helper
+            schema_kwargs = prepare_schema_from_json(data)
+            schema = cls(**schema_kwargs)
+
+            if verbose:
+                _LOGGER.info(f"FeatureSchema loaded from '{dir_path.name}'")
+
+            return schema
+
+        except (IOError, ValueError, KeyError) as e:
+            _LOGGER.error(f"Failed to load FeatureSchema from '{dir_path}': {e}")
+            raise e
+    
+    @classmethod
+    def from_model_architecture(cls, file_or_dir: Union[str, Path], verbose: bool = True) -> 'FeatureSchema':
+        """
+        Extracts and loads the FeatureSchema embedded within a model's 'architecture.json' file.
+
+        Args:
+            file_or_dir: Path to the JSON file or the directory containing 'architecture.json'.
+            verbose: If True, prints a confirmation message upon loading.
+        
+        Raises:
+            KeyError: If the architecture file does not contain a FeatureSchema configuration.
+        """
+        user_path = make_fullpath(file_or_dir)
+        
+        # 1. Resolve Path
+        if user_path.is_dir():
+            json_filename = PytorchModelArchitectureKeys.SAVENAME + ".json"
+            target_path = make_fullpath(user_path / json_filename, enforce="file")
+        elif user_path.is_file():
+            target_path = user_path
+        else:
+            _LOGGER.error(f"Invalid path: '{file_or_dir}'")
+            raise IOError()
+
+        # 2. Load Architecture JSON
+        try:
+            with open(target_path, 'r', encoding='utf-8') as f:
+                arch_data: dict[str, Any] = json.load(f)
+        except (IOError, json.JSONDecodeError) as e:
+            _LOGGER.error(f"Failed to load architecture file from '{target_path}': {e}")
+            raise e
+
+        # 3. Validate and Extract Schema Dict
+        config = arch_data.get(PytorchModelArchitectureKeys.CONFIG, {})
+        
+        if SchemaKeys.SCHEMA_DICT not in config:
+            error_msg = f"The model architecture at '{target_path.name}' does not contain a '{SchemaKeys.SCHEMA_DICT}' key. This model might not use a FeatureSchema."
+            _LOGGER.error(error_msg)
+            raise KeyError()
+
+        data = config[SchemaKeys.SCHEMA_DICT]
+
+        # 4. Reconstruct Schema (Restore Types)
+        try:
+            schema_kwargs = prepare_schema_from_json(data)
+            schema = cls(**schema_kwargs)
+
+            if verbose:
+                _LOGGER.info(f"FeatureSchema extracted from architecture '{target_path.name}'")
+
+            return schema
+
+        except (ValueError, KeyError) as e:
+            _LOGGER.error(f"Failed to parse FeatureSchema from architecture file: {e}")
+            raise e
+
+    def _save_helper(self, artifact: tuple[str, ...], directory: Union[str,Path], filename: str, verbose: bool):
+        to_save = list(artifact)
+        
+        # empty check
+        if not to_save:
+            _LOGGER.warning(f"Skipping save for '{filename}': The feature list is empty.")
+            return
+        
+        save_list_strings(list_strings=to_save,
+                          directory=directory,
+                          filename=filename,
+                          verbose=verbose)
+
+    def save_all_features(self, directory: Union[str,Path], verbose: bool=True):
+        """
+        Saves all feature names to a text file.
+
+        Args:
+            directory: The directory where the file will be saved.
+            verbose: If True, prints a confirmation message upon saving.
+        """
+        self._save_helper(artifact=self.feature_names,
+                          directory=directory,
+                          filename=DatasetKeys.FEATURE_NAMES,
+                          verbose=verbose)
+        
+    def save_continuous_features(self, directory: Union[str,Path], verbose: bool=True):
+        """
+        Saves continuous feature names to a text file.
+
+        Args:
+            directory: The directory where the file will be saved.
+            verbose: If True, prints a confirmation message upon saving.
+        """
+        self._save_helper(artifact=self.continuous_feature_names,
+                          directory=directory,
+                          filename=DatasetKeys.CONTINUOUS_NAMES,
+                          verbose=verbose)
+    
+    def save_categorical_features(self, directory: Union[str,Path], verbose: bool=True):
+        """
+        Saves categorical feature names to a text file.
+
+        Args:
+            directory: The directory where the file will be saved.
+            verbose: If True, prints a confirmation message upon saving.
+        """
+        self._save_helper(artifact=self.categorical_feature_names,
+                          directory=directory,
+                          filename=DatasetKeys.CATEGORICAL_NAMES,
+                          verbose=verbose)
+        
+    def save_artifacts(self, directory: Union[str,Path]):
+        """
+        Saves feature names, categorical feature names, continuous feature names to separate text files.
+        """
+        self.save_all_features(directory=directory, verbose=True)
+        self.save_continuous_features(directory=directory, verbose=True)
+        self.save_categorical_features(directory=directory, verbose=True)
+        
+    def __repr__(self) -> str:
+        """Returns a concise representation of the schema's contents."""
+        total = len(self.feature_names)
+        cont = len(self.continuous_feature_names)
+        cat = len(self.categorical_feature_names)
+        index_map = self.categorical_index_map is not None
+        cat_map = self.categorical_mappings is not None
+        return (
+            f"FeatureSchema(total={total}, continuous={cont}, categorical={cat}, index_map={index_map}, categorical_map={cat_map})"
+        )
+