scitex 2.16.2__py3-none-any.whl → 2.17.3__py3-none-any.whl

scitex/session/_decorator.py

@@ -1,8 +1,9 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+# Timestamp: "2026-02-01 08:38:19 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/session/_decorator.py
+
 # Timestamp: "2025-11-05"
-# File: /home/ywatanabe/proj/scitex-code/src/scitex/session/_decorator.py
-# ----------------------------------------
 """Session decorator for scitex.
 
 Provides @stx.session decorator that automatically:
@@ -16,10 +17,12 @@ import functools
 import inspect
 import argparse
 from pathlib import Path
-from typing import Callable, Any, get_type_hints
+from typing import Callable
+from typing import Any, get_type_hints
 import sys as sys_module
 
-from ._lifecycle import start, close
+from ._lifecycle import start
+from ._lifecycle import close
 from scitex.logging import getLogger
 from . import INJECTED  # Use local INJECTED from session module
 
@@ -79,7 +82,7 @@ def session(
             # - CONFIG: Session configuration dict
             # - plt: Matplotlib pyplot (configured for session)
             # - COLORS: Custom Colors
-            # - rng: RandomStateManager (fixes seeds, creates named generators)
+            # - rngg: RandomStateManager (fixes seeds, creates named generators)
             logger.info(f"Session ID: {CONFIG['ID']}")
             logger.info(f"Output directory: {CONFIG['SDIR_RUN']}")
             # ... training code ...
@@ -100,8 +103,8 @@ def session(
         - CONFIG (dict): Session configuration with ID, SDIR, paths, etc.
         - plt (module): matplotlib.pyplot configured with session settings
         - COLORS (CustomColors): Custom Colors for consistent plotting
-        - rng (RandomStateManager): Manages reproducibility by fixing global seeds
-                                             and creating named generators via rng("name")
+        - rngg (RandomStateManager): Manages reproducibility by fixing global seeds
+                                             and creating named generators via rngg("name")
     """
 
     def decorator(func: Callable) -> Callable:
@@ -157,13 +160,17 @@ def _run_with_session(
 
     # Clean up INJECTED sentinels from args before passing to session
     cleaned_args = argparse.Namespace(
-        **{k: v for k, v in vars(args).items() if not isinstance(v, type(INJECTED))}
+        **{
+            k: v
+            for k, v in vars(args).items()
+            if not isinstance(v, type(INJECTED))
+        }
     )
 
     # Start session
     import matplotlib.pyplot as plt
 
-    CONFIG, stdout, stderr, plt, COLORS, rng = start(
+    CONFIG, stdout, stderr, plt, COLORS, rngg = start(
         sys=sys_module,
         plt=plt,
         args=cleaned_args,
@@ -182,21 +189,33 @@ def _run_with_session(
     func_globals["CONFIG"] = CONFIG
     func_globals["plt"] = plt
     func_globals["COLORS"] = COLORS
-    func_globals["rng"] = rng
+    func_globals["rngg"] = rngg
     func_globals["logger"] = script_logger
 
     # Log injected globals for user awareness (only in verbose mode)
     if verbose:
         _decorator_logger.info("=" * 60)
-        _decorator_logger.info("Injected Global Variables (available in your function):")
+        _decorator_logger.info(
+            "Injected Global Variables (available in your function):"
+        )
         _decorator_logger.info("  • CONFIG - Session configuration dict")
         _decorator_logger.info(f"      - CONFIG['ID']: {CONFIG['ID']}")
-        _decorator_logger.info(f"      - CONFIG['SDIR_RUN']: {CONFIG['SDIR_RUN']}")
+        _decorator_logger.info(
+            f"      - CONFIG['SDIR_RUN']: {CONFIG['SDIR_RUN']}"
+        )
         _decorator_logger.info(f"      - CONFIG['PID']: {CONFIG['PID']}")
-        _decorator_logger.info("  • plt - matplotlib.pyplot (configured for session)")
-        _decorator_logger.info("  • COLORS - CustomColors (for consistent plotting)")
-        _decorator_logger.info("  • rng - RandomStateManager (for reproducibility)")
-        _decorator_logger.info("  • logger - SciTeX logger (configured for your script)")
+        _decorator_logger.info(
+            "  • plt - matplotlib.pyplot (configured for session)"
+        )
+        _decorator_logger.info(
+            "  • COLORS - CustomColors (for consistent plotting)"
+        )
+        _decorator_logger.info(
+            "  • rngg - RandomStateManager (for reproducibility)"
+        )
+        _decorator_logger.info(
+            "  • logger - SciTeX logger (configured for your script)"
+        )
         _decorator_logger.info("=" * 60)
 
     # Run function
@@ -216,7 +235,7 @@ def _run_with_session(
             "CONFIG": CONFIG,
             "plt": plt,
             "COLORS": COLORS,
-            "rng": rng,
+            "rngg": rngg,
             "logger": script_logger,
         }
 
@@ -238,8 +257,12 @@ def _run_with_session(
 
         # Log injected arguments summary (only in verbose mode)
         if verbose:
-            args_summary = {k: type(v).__name__ for k, v in filtered_kwargs.items()}
-            _decorator_logger.info(f"Running {func.__name__} with injected parameters:")
+            args_summary = {
+                k: type(v).__name__ for k, v in filtered_kwargs.items()
+            }
+            _decorator_logger.info(
+                f"Running {func.__name__} with injected parameters:"
+            )
             _decorator_logger.info(args_summary, pprint=True, indent=2)
 
         # Execute function
@@ -252,7 +275,9 @@ def _run_with_session(
             exit_status = 0
 
     except Exception as e:
-        _decorator_logger.error(f"Error in {func.__name__}: {e}", exc_info=True)
+        _decorator_logger.error(
+            f"Error in {func.__name__}: {e}", exc_info=True
+        )
         exit_status = 1
         raise
 
@@ -359,15 +384,11 @@ def _create_parser(func: Callable) -> argparse.ArgumentParser:
                     # If we can't load the YAML files, just show error
                     config_status = "        CONFIG from YAML files:\n        (unable to load at help-time, will be available at runtime)"
             else:
-                config_status = (
-                    "        CONFIG from YAML files:\n        (no .yaml files found)"
-                )
+                config_status = "        CONFIG from YAML files:\n        (no .yaml files found)"
         else:
             config_status = "        CONFIG from YAML files:\n        (./config/ directory not found)"
     except:
-        config_status = (
-            "        CONFIG from YAML files:\n        (unable to check at help-time)"
-        )
+        config_status = "        CONFIG from YAML files:\n        (unable to check at help-time)"
 
     # Get available color keys
     try:
@@ -380,7 +401,9 @@ def _create_parser(func: Callable) -> argparse.ArgumentParser:
         color_keys = ", ".join(f"'{k}'" for k in sorted_keys)
     except Exception as e:
         # Fallback if configure_mpl fails
-        color_keys = "'blue', 'red', 'green', 'yellow', 'purple', 'orange', ..."
+        color_keys = (
+            "'blue', 'red', 'green', 'yellow', 'purple', 'orange', ..."
+        )
 
     # Create parser with epilog documenting injected globals with actual values
     epilog = f"""
@@ -419,7 +442,7 @@ Global Variables Injected by @session Decorator:
             plt.plot(x, y, color=COLORS.blue)
             plt.plot(x, y, color=COLORS['blue'])
 
-    rng (RandomStateManager)
+    rngg (RandomStateManager)
         Manages reproducible randomness
 
     logger (SciTeXLogger)
@@ -545,9 +568,11 @@ def _add_argument(
         choices_str = f", choices: {choices}" if choices else ""
         kwargs = {
             "type": param_type,
-            "help": f"(default: {default}{choices_str})"
-            if has_default
-            else f"(required{choices_str})",
+            "help": (
+                f"(default: {default}{choices_str})"
+                if has_default
+                else f"(required{choices_str})"
+            ),
         }
 
         if choices:
@@ -596,7 +621,7 @@ def run(func: Callable, parse_args: Callable = None, **session_kwargs) -> Any:
     # Start session
     import matplotlib.pyplot as plt
 
-    CONFIG, stdout, stderr, plt, COLORS, rng = start(
+    CONFIG, stdout, stderr, plt, COLORS, rngg = start(
         sys=sys_module,
         plt=plt,
         args=args,
@@ -627,5 +652,4 @@ def run(func: Callable, parse_args: Callable = None, **session_kwargs) -> Any:
 
     return exit_status
 
-
 # EOF

scitex/session/_lifecycle/__init__.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-02-01 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/session/_lifecycle/__init__.py
+"""Session lifecycle management - refactored subpackage.
+
+This package contains the split modules from the original _lifecycle.py:
+- _start.py: Session start function
+- _close.py: Session close and running2finished functions
+- _config.py: Configuration setup
+- _matplotlib.py: Matplotlib configuration
+- _utils.py: Utility functions
+"""
+
+from ._close import close, running2finished
+from ._start import start
+
+__all__ = [
+    "start",
+    "close",
+    "running2finished",
+]
+
+# EOF

scitex/session/_lifecycle/_close.py

@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-02-01 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/session/_lifecycle/_close.py
+"""Session close functions."""
+
+from __future__ import annotations
+
+import os
+import os as _os
+import shutil
+import time
+from glob import glob as _glob
+from pathlib import Path
+
+from scitex.logging import getLogger
+from scitex.utils._notify import notify as scitex_utils_notify
+
+from .._manager import get_global_session_manager
+from ._config import save_configs
+from ._utils import args_to_str, escape_ansi_from_log_files, process_timestamp
+
+logger = getLogger(__name__)
+
+
+def running2finished(CONFIG, exit_status=None, remove_src_dir=True, max_wait=60):
+    """Move session from RUNNING to FINISHED directory.
+
+    Parameters
+    ----------
+    CONFIG : dict
+        Session configuration dictionary
+    exit_status : int, optional
+        Exit status code (0=success, 1=error, None=finished)
+    remove_src_dir : bool, default=True
+        Whether to remove source directory after copy
+    max_wait : int, default=60
+        Maximum seconds to wait for copy operation
+
+    Returns
+    -------
+    dict
+        Updated configuration with new SDIR
+    """
+    if exit_status == 0:
+        dest_dir = str(CONFIG["SDIR_RUN"]).replace("RUNNING/", "FINISHED_SUCCESS/")
+    elif exit_status == 1:
+        dest_dir = str(CONFIG["SDIR_RUN"]).replace("RUNNING/", "FINISHED_ERROR/")
+    else:
+        dest_dir = str(CONFIG["SDIR_RUN"]).replace("RUNNING/", "FINISHED/")
+
+    src_dir = str(CONFIG["SDIR_RUN"])
+    _os.makedirs(dest_dir, exist_ok=True)
+    try:
+        # Copy files individually
+        for item in _os.listdir(src_dir):
+            s = _os.path.join(src_dir, item)
+            d = _os.path.join(dest_dir, item)
+            if _os.path.isdir(s):
+                shutil.copytree(s, d)
+            else:
+                shutil.copy2(s, d)
+
+        start_time = time.time()
+        while not _os.path.exists(dest_dir) and time.time() - start_time < max_wait:
+            time.sleep(0.1)
+        if _os.path.exists(dest_dir):
+            print()
+            logger.success(
+                f"Congratulations! The script completed: {dest_dir}",
+            )
+
+            if remove_src_dir:
+                shutil.rmtree(src_dir)
+
+            # Cleanup RUNNING when empty
+            running_base = os.path.dirname(src_dir.rstrip("/"))
+            if os.path.basename(running_base) == "RUNNING":
+                try:
+                    os.rmdir(running_base)
+                except OSError:
+                    pass
+
+        else:
+            print(f"Copy operation timed out after {max_wait} seconds")
+
+        CONFIG["SDIR_RUN"] = Path(dest_dir)
+    except Exception as e:
+        print(e)
+
+    finally:
+        return CONFIG
+
+
+def close(CONFIG, message=":)", notify=False, verbose=True, exit_status=None):
+    """Close experiment session and finalize logging.
+
+    Parameters
+    ----------
+    CONFIG : DotDict
+        Configuration dictionary from start()
+    message : str, default=':)'
+        Completion message
+    notify : bool, default=False
+        Whether to send notification
+    verbose : bool, default=True
+        Whether to print verbose output
+    exit_status : int, optional
+        Exit status code (0=success, 1=error, None=finished)
+    """
+    # Stop verification tracking first
+    _stop_verification(exit_status)
+
+    sys = None
+    try:
+        CONFIG.EXIT_STATUS = exit_status
+        CONFIG = CONFIG.to_dict()
+        CONFIG = process_timestamp(CONFIG, verbose=verbose)
+        sys = CONFIG.pop("_sys", None)
+
+        # CRITICAL: Close matplotlib BEFORE closing streams to prevent segfault
+        _cleanup_matplotlib(verbose)
+
+        save_configs(CONFIG)
+
+        # RUNNING to FINISHED
+        CONFIG = running2finished(CONFIG, exit_status=exit_status)
+
+        # ANSI code escape
+        log_files = _glob(str(CONFIG["SDIR_RUN"]) + "logs/*.log")
+        escape_ansi_from_log_files(log_files)
+
+        if CONFIG.get("ARGS"):
+            message += f"\n{args_to_str(CONFIG.get('ARGS'))}"
+
+        if notify:
+            try:
+                message = (
+                    "[DEBUG]\n" + str(message)
+                    if CONFIG.get("DEBUG", False)
+                    else str(message)
+                )
+                scitex_utils_notify(
+                    message=message,
+                    ID=CONFIG["ID"],
+                    file=CONFIG.get("FILE"),
+                    attachment_paths=log_files,
+                    verbose=verbose,
+                )
+            except Exception as e:
+                print(e)
+
+        # Close session
+        session_manager = get_global_session_manager()
+        session_manager.close_session(CONFIG["ID"])
+
+    finally:
+        # Only close if they're custom file objects (Tee objects)
+        if sys:
+            _close_streams(sys)
+
+
+def _cleanup_matplotlib(verbose: bool) -> None:
+    """Clean up matplotlib resources."""
+    try:
+        import gc
+
+        import matplotlib
+        import matplotlib.pyplot as plt
+
+        # Close all figures
+        plt.close("all")
+
+        # CRITICAL: Unregister matplotlib's atexit handlers to prevent segfault
+        try:
+            if hasattr(matplotlib, "_pylab_helpers"):
+                matplotlib._pylab_helpers.Gcf.destroy_all()
+
+            if hasattr(plt, "get_fignums"):
+                for fignum in plt.get_fignums():
+                    plt.close(fignum)
+
+        except Exception:
+            pass
+
+        # Force garbage collection
+        gc.collect()
+
+        if verbose:
+            logger.info("Matplotlib cleanup completed")
+
+    except Exception as e:
+        if verbose:
+            logger.warning(f"Could not close matplotlib: {e}")
+
+
+def _close_streams(sys) -> None:
+    """Close tee-wrapped streams."""
+    try:
+        # First, flush all outputs
+        if hasattr(sys, "stdout") and hasattr(sys.stdout, "flush"):
+            sys.stdout.flush()
+        if hasattr(sys, "stderr") and hasattr(sys.stderr, "flush"):
+            sys.stderr.flush()
+
+        # Then close Tee objects
+        if hasattr(sys, "stdout") and hasattr(sys.stdout, "_log_file"):
+            sys.stdout.close()
+        if hasattr(sys, "stderr") and hasattr(sys.stderr, "_log_file"):
+            sys.stderr.close()
+    except Exception:
+        pass
+
+
+def _stop_verification(exit_status: int) -> None:
+    """Stop verification tracking for this session."""
+    try:
+        from scitex.verify import on_session_close
+
+        status = "success" if exit_status == 0 else "failed"
+        on_session_close(status=status, exit_code=exit_status or 0)
+    except Exception:
+        pass
+
+
+# EOF

scitex/session/_lifecycle/_config.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-02-01 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/session/_lifecycle/_config.py
+"""Configuration setup for session lifecycle."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict
+
+from scitex.logging import getLogger
+
+logger = getLogger(__name__)
+
+
+def setup_configs(
+    IS_DEBUG: bool,
+    ID: str,
+    PID: int,
+    file: str,
+    sdir: str,
+    relative_sdir: str,
+    verbose: bool,
+) -> Dict[str, Any]:
+    """Setup configuration dictionary with basic parameters.
+
+    Parameters
+    ----------
+    IS_DEBUG : bool
+        Debug mode flag
+    ID : str
+        Unique identifier
+    PID : int
+        Process ID
+    file : str
+        File path
+    sdir : str
+        Save directory path
+    relative_sdir : str
+        Relative save directory path
+    verbose : bool
+        Verbosity flag
+
+    Returns
+    -------
+    dict
+        Configuration dictionary
+    """
+    # Calculate SDIR_OUT (base output directory)
+    # sdir format: /path/to/script_out/RUNNING/ID/
+    sdir_path = Path(sdir) if sdir else None
+    if sdir_path:
+        # Remove /RUNNING/ID/ to get base output dir
+        parts = sdir_path.parts
+        if "RUNNING" in parts:
+            running_idx = parts.index("RUNNING")
+            sdir_out = Path(*parts[:running_idx])
+        else:
+            sdir_out = sdir_path.parent
+    else:
+        sdir_out = None
+
+    # Load YAML configs from ./config/*.yaml
+    from scitex.io._load_configs import load_configs
+
+    CONFIGS = load_configs(IS_DEBUG).to_dict()
+
+    # Add session-specific config with clean structure (Path objects only)
+    CONFIGS.update(
+        {
+            "ID": ID,
+            "PID": PID,
+            "START_DATETIME": datetime.now(),
+            "FILE": Path(file) if file else None,
+            "SDIR_OUT": sdir_out,
+            "SDIR_RUN": sdir_path,
+        }
+    )
+    return CONFIGS
+
+
+def save_configs(CONFIG) -> None:
+    """Save configuration to files.
+
+    Note: track=False prevents verification tracking of CONFIG files,
+    which would cause false "missing" errors since these files are saved
+    in RUNNING/ but then moved to FINISHED_SUCCESS/.
+    """
+    from scitex.io._save import save as scitex_io_save
+
+    # Convert to dict with all keys (including private ones) for saving
+    config_dict = (
+        CONFIG.to_dict(include_private=True) if hasattr(CONFIG, "to_dict") else CONFIG
+    )
+
+    # track=False: Don't track internal config files in verification DB
+    scitex_io_save(
+        config_dict,
+        str(CONFIG["SDIR_RUN"] / "CONFIGS/CONFIG.pkl"),
+        verbose=False,
+        track=False,
+    )
+    scitex_io_save(
+        config_dict,
+        str(CONFIG["SDIR_RUN"] / "CONFIGS/CONFIG.yaml"),
+        verbose=False,
+        track=False,
+    )
+
+
+# EOF

scitex/session/_lifecycle/_matplotlib.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-02-01 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/session/_lifecycle/_matplotlib.py
+"""Matplotlib configuration for session lifecycle."""
+
+from __future__ import annotations
+
+import os
+import platform
+import sys
+from typing import Any, Dict, Optional, Tuple
+
+import matplotlib
+
+from scitex.logging import getLogger
+
+logger = getLogger(__name__)
+
+# Detect headless/WSL environments
+is_headless = False
+try:
+    # Check for WSL
+    if "microsoft" in platform.uname().release.lower() or "WSL" in os.environ.get(
+        "WSL_DISTRO_NAME", ""
+    ):
+        is_headless = True
+    # Check for no X11 display
+    elif not os.environ.get("DISPLAY"):
+        is_headless = True
+except Exception:
+    # Fallback: if on Linux without DISPLAY, assume headless
+    if sys.platform.startswith("linux") and not os.environ.get("DISPLAY"):
+        is_headless = True
+
+if is_headless:
+    matplotlib.use("Agg")
+
+
+from scitex.plt.utils._configure_mpl import configure_mpl
+
+
+def setup_matplotlib(
+    plt=None, agg: bool = False, **mpl_kwargs: Any
+) -> Tuple[Any, Optional[Dict[str, Any]]]:
+    """Configure matplotlib settings.
+
+    Parameters
+    ----------
+    plt : module
+        Matplotlib.pyplot module (will be replaced with scitex.plt)
+    agg : bool
+        Whether to use Agg backend
+    **mpl_kwargs : dict
+        Additional matplotlib configuration parameters
+
+    Returns
+    -------
+    tuple
+        (plt, COLORS) - Configured scitex.plt module and color cycle
+    """
+    if plt is not None:
+        plt.close("all")
+        _, COLORS = configure_mpl(plt, **mpl_kwargs)
+        COLORS["gray"] = COLORS["grey"]
+
+        # Note: Backend is now set early in module initialization
+        # to avoid tkinter threading issues in headless/WSL environments.
+        # The 'agg' parameter is kept for backwards compatibility but has
+        # no effect since backend must be set before pyplot import.
+        if agg and not is_headless:
+            logger.warning(
+                "agg=True specified but backend was already set to Agg "
+                "during module initialization for headless environment"
+            )
+
+        # Replace matplotlib.pyplot with scitex.plt to get wrapped functions
+        import scitex.plt as stx_plt
+
+        return stx_plt, COLORS
+    return plt, None
+
+
+# EOF