scitex 2.8.1__py3-none-any.whl → 2.10.0__py3-none-any.whl

scitex/logging/_errors.py

@@ -0,0 +1,508 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-21"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/logging/_errors.py
+
+"""Error classes for SciTeX.
+
+All SciTeX exceptions are defined here for unified error handling.
+Re-exported from scitex.logging for backwards compatibility.
+
+Usage:
+    from scitex.logging import SciTeXError, SaveError, LoadError
+    # or (backwards compatible)
+    from scitex.logging import SciTeXError, SaveError, LoadError
+"""
+
+from typing import Optional, Union
+
+
+# =============================================================================
+# Base Errors
+# =============================================================================
+
+
+class SciTeXError(Exception):
+    """Base Exception class for all SciTeX errors."""
+
+    def __init__(
+        self,
+        message: str,
+        context: Optional[dict] = None,
+        suggestion: Optional[str] = None,
+    ):
+        """Initialize SciTeX error with detailed information.
+
+        Parameters
+        ----------
+        message : str
+            The error message
+        context : dict, optional
+            Additional context information (e.g., file paths, variable values)
+        suggestion : str, optional
+            Suggested fix or action
+        """
+        self.message = message
+        self.context = context or {}
+        self.suggestion = suggestion
+
+        # Build the full error message
+        error_parts = [f"SciTeX Error: {message}"]
+
+        if context:
+            error_parts.append("\nContext:")
+            for key, value in context.items():
+                error_parts.append(f"  {key}: {value}")
+
+        if suggestion:
+            error_parts.append(f"\nSuggestion: {suggestion}")
+
+        super().__init__("\n".join(error_parts))
+
+
+# =============================================================================
+# Configuration Errors
+# =============================================================================
+
+
+class ConfigurationError(SciTeXError):
+    """Raised when there are issues with SciTeX configuration."""
+
+    pass
+
+
+class ConfigFileNotFoundError(ConfigurationError):
+    """Raised when a required configuration file is not found."""
+
+    def __init__(self, filepath: str):
+        super().__init__(
+            f"Configuration file not found: {filepath}",
+            context={"filepath": filepath},
+            suggestion="Ensure the configuration file exists in ./config/ directory",
+        )
+
+
+class ConfigKeyError(ConfigurationError):
+    """Raised when a required configuration key is missing."""
+
+    def __init__(self, key: str, available_keys: Optional[list] = None):
+        context = {"missing_key": key}
+        if available_keys:
+            context["available_keys"] = available_keys
+
+        super().__init__(
+            f"Configuration key '{key}' not found",
+            context=context,
+            suggestion=f"Add '{key}' to your configuration file or check for typos",
+        )
+
+
+# =============================================================================
+# IO Errors
+# =============================================================================
+
+
+class IOError(SciTeXError):
+    """Base class for input/output related errors."""
+
+    pass
+
+
+class FileFormatError(IOError):
+    """Raised when file format is not supported or incorrect."""
+
+    def __init__(
+        self,
+        filepath: str,
+        expected_format: Optional[str] = None,
+        actual_format: Optional[str] = None,
+    ):
+        context = {"filepath": filepath}
+        if expected_format:
+            context["expected_format"] = expected_format
+        if actual_format:
+            context["actual_format"] = actual_format
+
+        message = f"File format error for: {filepath}"
+        if expected_format and actual_format:
+            message += f" (expected: {expected_format}, got: {actual_format})"
+
+        super().__init__(
+            message,
+            context=context,
+            suggestion="Check the file extension and content format",
+        )
+
+
+class SaveError(IOError):
+    """Raised when saving data fails."""
+
+    def __init__(self, filepath: str, reason: str):
+        super().__init__(
+            f"Failed to save to {filepath}: {reason}",
+            context={"filepath": filepath, "reason": reason},
+            suggestion="Check file permissions and disk space",
+        )
+
+
+class LoadError(IOError):
+    """Raised when loading data fails."""
+
+    def __init__(self, filepath: str, reason: str):
+        super().__init__(
+            f"Failed to load from {filepath}: {reason}",
+            context={"filepath": filepath, "reason": reason},
+            suggestion="Verify the file exists and is not corrupted",
+        )
+
+
+# =============================================================================
+# Scholar Module Errors
+# =============================================================================
+
+
+class ScholarError(SciTeXError):
+    """Base class for scholar module errors."""
+
+    pass
+
+
+class SearchError(ScholarError):
+    """Raised when paper search fails."""
+
+    def __init__(self, query: str, source: str, reason: str):
+        super().__init__(
+            f"Search failed for query '{query}' on {source}",
+            context={"query": query, "source": source, "reason": reason},
+            suggestion="Check your internet connection and API keys",
+        )
+
+
+class EnrichmentError(ScholarError):
+    """Raised when paper enrichment fails."""
+
+    def __init__(self, paper_title: str, reason: str):
+        super().__init__(
+            f"Failed to enrich paper: {paper_title}",
+            context={"paper_title": paper_title, "reason": reason},
+            suggestion="Verify journal information is available",
+        )
+
+
+class PDFDownloadError(ScholarError):
+    """Raised when PDF download fails."""
+
+    def __init__(self, url: str, reason: str):
+        super().__init__(
+            f"Failed to download PDF from {url}",
+            context={"url": url, "reason": reason},
+            suggestion="Check if the paper is open access",
+        )
+
+
+class DOIResolutionError(ScholarError):
+    """Raised when DOI resolution fails."""
+
+    def __init__(self, doi: str, reason: str):
+        super().__init__(
+            f"Failed to resolve DOI: {doi}",
+            context={"doi": doi, "reason": reason},
+            suggestion="Verify the DOI is correct and try again",
+        )
+
+
+class PDFExtractionError(ScholarError):
+    """Raised when PDF text extraction fails."""
+
+    def __init__(self, filepath: str, reason: str):
+        super().__init__(
+            f"Failed to extract text from PDF: {filepath}",
+            context={"filepath": filepath, "reason": reason},
+            suggestion="Ensure the PDF is not corrupted or encrypted",
+        )
+
+
+class BibTeXEnrichmentError(ScholarError):
+    """Raised when BibTeX enrichment fails."""
+
+    def __init__(self, bibtex_file: str, reason: str):
+        super().__init__(
+            f"Failed to enrich BibTeX file: {bibtex_file}",
+            context={"bibtex_file": bibtex_file, "reason": reason},
+            suggestion="Check the BibTeX format and ensure all entries are valid",
+        )
+
+
+class TranslatorError(ScholarError):
+    """Raised when Zotero translator operations fail."""
+
+    def __init__(self, translator_name: str, reason: str):
+        super().__init__(
+            f"Translator error in {translator_name}: {reason}",
+            context={"translator": translator_name, "reason": reason},
+            suggestion="Check translator compatibility and JavaScript environment",
+        )
+
+
+class AuthenticationError(ScholarError):
+    """Raised when authentication fails."""
+
+    def __init__(self, provider: str, reason: str = ""):
+        super().__init__(
+            f"Authentication failed for {provider}: {reason}",
+            context={"provider": provider, "reason": reason},
+            suggestion="Check your credentials and authentication settings",
+        )
+
+
+# =============================================================================
+# Plotting Errors
+# =============================================================================
+
+
+class PlottingError(SciTeXError):
+    """Base class for plotting-related errors."""
+
+    pass
+
+
+class FigureNotFoundError(PlottingError):
+    """Raised when attempting to operate on a non-existent figure."""
+
+    def __init__(self, fig_id: Union[int, str]):
+        super().__init__(
+            f"Figure {fig_id} not found",
+            context={"figure_id": fig_id},
+            suggestion="Ensure the figure was created before attempting to save/modify it",
+        )
+
+
+class AxisError(PlottingError):
+    """Raised when there are issues with plot axes."""
+
+    def __init__(self, message: str, axis_info: Optional[dict] = None):
+        super().__init__(
+            message,
+            context={"axis_info": axis_info} if axis_info else None,
+            suggestion="Check axis indices and subplot configuration",
+        )
+
+
+# =============================================================================
+# Data Processing Errors
+# =============================================================================
+
+
+class DataError(SciTeXError):
+    """Base class for data processing errors."""
+
+    pass
+
+
+class ShapeError(DataError):
+    """Raised when data shapes are incompatible."""
+
+    def __init__(self, expected_shape: tuple, actual_shape: tuple, operation: str):
+        super().__init__(
+            f"Shape mismatch in {operation}",
+            context={
+                "expected_shape": expected_shape,
+                "actual_shape": actual_shape,
+                "operation": operation,
+            },
+            suggestion="Reshape or transpose your data to match expected dimensions",
+        )
+
+
+class DTypeError(DataError):
+    """Raised when data types are incompatible."""
+
+    def __init__(self, expected_dtype: str, actual_dtype: str, operation: str):
+        super().__init__(
+            f"Data type mismatch in {operation}",
+            context={
+                "expected_dtype": expected_dtype,
+                "actual_dtype": actual_dtype,
+                "operation": operation,
+            },
+            suggestion=f"Convert data to {expected_dtype} using appropriate casting",
+        )
+
+
+# =============================================================================
+# Path Errors
+# =============================================================================
+
+
+class PathError(SciTeXError):
+    """Base class for path-related errors."""
+
+    pass
+
+
+class InvalidPathError(PathError):
+    """Raised when a path is invalid or doesn't follow SciTeX conventions."""
+
+    def __init__(self, path: str, reason: str):
+        super().__init__(
+            f"Invalid path: {path}",
+            context={"path": path, "reason": reason},
+            suggestion="Use relative paths starting with './' or '../'",
+        )
+
+
+class PathNotFoundError(PathError):
+    """Raised when a required path doesn't exist."""
+
+    def __init__(self, path: str):
+        super().__init__(
+            f"Path not found: {path}",
+            context={"path": path},
+            suggestion="Check if the path exists and is accessible",
+        )
+
+
+# =============================================================================
+# Template Errors
+# =============================================================================
+
+
+class TemplateError(SciTeXError):
+    """Base class for template-related errors."""
+
+    pass
+
+
+class TemplateViolationError(TemplateError):
+    """Raised when SciTeX template is not followed."""
+
+    def __init__(self, filepath: str, violation: str):
+        super().__init__(
+            f"Template violation in {filepath}: {violation}",
+            context={"filepath": filepath, "violation": violation},
+            suggestion="Follow the SciTeX template structure as defined in IMPORTANT-SCITEX-02-file-template.md",
+        )
+
+
+# =============================================================================
+# Neural Network Errors
+# =============================================================================
+
+
+class NNError(SciTeXError):
+    """Base class for neural network module errors."""
+
+    pass
+
+
+class ModelError(NNError):
+    """Raised when there are issues with neural network models."""
+
+    def __init__(self, model_name: str, reason: str):
+        super().__init__(
+            f"Model error in {model_name}: {reason}",
+            context={"model_name": model_name, "reason": reason},
+        )
+
+
+# =============================================================================
+# Statistics Errors
+# =============================================================================
+
+
+class StatsError(SciTeXError):
+    """Base class for statistics module errors."""
+
+    pass
+
+
+class TestError(StatsError):
+    """Raised when statistical tests fail."""
+
+    def __init__(self, test_name: str, reason: str):
+        super().__init__(
+            f"Statistical test '{test_name}' failed: {reason}",
+            context={"test_name": test_name, "reason": reason},
+        )
+
+
+# =============================================================================
+# Validation Helpers
+# =============================================================================
+
+
+def check_path(path: str) -> None:
+    """Validate a path according to SciTeX conventions."""
+    if not isinstance(path, str):
+        raise InvalidPathError(str(path), "Path must be a string")
+
+    if not (path.startswith("./") or path.startswith("../")):
+        raise InvalidPathError(
+            path, "Path must be relative and start with './' or '../'"
+        )
+
+
+def check_file_exists(filepath: str) -> None:
+    """Check if a file exists."""
+    import os
+
+    if not os.path.exists(filepath):
+        raise PathNotFoundError(filepath)
+
+
+def check_shape_compatibility(shape1: tuple, shape2: tuple, operation: str) -> None:
+    """Check if two shapes are compatible for an operation."""
+    if shape1 != shape2:
+        raise ShapeError(shape1, shape2, operation)
+
+
+__all__ = [
+    # Base errors
+    "SciTeXError",
+    # Configuration
+    "ConfigurationError",
+    "ConfigFileNotFoundError",
+    "ConfigKeyError",
+    # IO
+    "IOError",
+    "FileFormatError",
+    "SaveError",
+    "LoadError",
+    # Scholar
+    "ScholarError",
+    "SearchError",
+    "EnrichmentError",
+    "PDFDownloadError",
+    "DOIResolutionError",
+    "PDFExtractionError",
+    "BibTeXEnrichmentError",
+    "TranslatorError",
+    "AuthenticationError",
+    # Plotting
+    "PlottingError",
+    "FigureNotFoundError",
+    "AxisError",
+    # Data
+    "DataError",
+    "ShapeError",
+    "DTypeError",
+    # Path
+    "PathError",
+    "InvalidPathError",
+    "PathNotFoundError",
+    # Template
+    "TemplateError",
+    "TemplateViolationError",
+    # Neural Network
+    "NNError",
+    "ModelError",
+    # Statistics
+    "StatsError",
+    "TestError",
+    # Validation helpers
+    "check_path",
+    "check_file_exists",
+    "check_shape_compatibility",
+]
+
+# EOF

scitex/logging/_formatters.py

@@ -21,6 +21,10 @@ import sys
 # SCITEX_LOG_FORMAT=debug python script.py
 LOG_FORMAT = os.getenv("SCITEX_LOG_FORMAT", "default")
 
+# Force color output even when stdout is not a TTY (e.g., when piping through tee)
+# SCITEX_FORCE_COLOR=1 python script.py | tee output.log
+FORCE_COLOR = os.getenv("SCITEX_FORCE_COLOR", "").lower() in ("1", "true", "yes")
+
 # Available format templates
 FORMAT_TEMPLATES = {
     "minimal": "%(levelname)s: %(message)s",
@@ -80,6 +84,14 @@ class SciTeXConsoleFormatter(logging.Formatter):
         self.indent_width = indent_width
 
     def format(self, record):
+        # Handle leading newlines: extract and preserve them
+        msg = str(record.msg) if record.msg else ""
+        leading_newlines = ""
+        while msg.startswith("\n"):
+            leading_newlines += "\n"
+            msg = msg[1:]
+        record.msg = msg
+
         # Apply indentation if specified in record
         indent_level = getattr(record, "indent", 0)
         if indent_level > 0:
@@ -89,12 +101,23 @@ class SciTeXConsoleFormatter(logging.Formatter):
         # Use parent formatter to apply template
         formatted = super().format(record)
 
-        # Check if we can use colors (stdout is a tty and not closed)
+        # Handle internal newlines: each line gets the level prefix
+        if "\n" in formatted:
+            lines = formatted.split("\n")
+            # First line already has prefix from parent formatter
+            # Add prefix to each continuation line
+            prefix = f"{record.levelname}: "
+            formatted = lines[0] + "\n" + "\n".join(
+                prefix + line if line.strip() else line
+                for line in lines[1:]
+            )
+
+        # Check if we can use colors (stdout is a tty and not closed, or forced)
         try:
-            use_colors = hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
+            use_colors = FORCE_COLOR or (hasattr(sys.stdout, "isatty") and sys.stdout.isatty())
         except ValueError:
             # stdout/stderr is closed
-            use_colors = False
+            use_colors = FORCE_COLOR
 
         if use_colors:
             # Check for custom color override
@@ -103,15 +126,15 @@ class SciTeXConsoleFormatter(logging.Formatter):
             if custom_color and custom_color in self.COLOR_NAMES:
                 # Use custom color
                 color = self.COLOR_NAMES[custom_color]
-                return f"{color}{formatted}{self.RESET}"
+                return f"{leading_newlines}{color}{formatted}{self.RESET}"
             else:
                 # Use default color for log level
                 levelname = record.levelname
                 if levelname in self.COLORS:
                     color = self.COLORS[levelname]
-                    return f"{color}{formatted}{self.RESET}"
+                    return f"{leading_newlines}{color}{formatted}{self.RESET}"
 
-        return formatted
+        return f"{leading_newlines}{formatted}"
 
 
 class SciTeXFileFormatter(logging.Formatter):
@@ -129,6 +152,7 @@ __all__ = [
     "SciTeXFileFormatter",
     "LOG_FORMAT",
     "FORMAT_TEMPLATES",
+    "FORCE_COLOR",
 ]
 
 # EOF