additory 0.1.0a4__py3-none-any.whl → 0.1.1a1__py3-none-any.whl

additory/core/logging.py

@@ -1,24 +1,230 @@
-def log_info(message: str):
-    # INFO logging commented out for v0.1.0 - will be re-enabled in v0.1.1
-    # print(f"[INFO] {message}")
-    pass
-
-def log_warning(message: str):
-    print(f"[WARNING] {message}")
-
-def log_error(message: str):
-    print(f"[ERROR] {message}")
-
-# Logging control functions for v0.1.1
-def enable_verbose_logging():
-    """Enable verbose INFO logging (for v0.1.1)"""
-    global _verbose_logging_enabled
-    _verbose_logging_enabled = True
-
-def disable_verbose_logging():
-    """Disable verbose INFO logging"""
-    global _verbose_logging_enabled
-    _verbose_logging_enabled = False
-
-# Global flag for verbose logging (for future use)
-_verbose_logging_enabled = False
+"""
+Transparent logging system for Additory operations.
+
+Provides clear, actionable messages about:
+- Information: Assumptions and defaults
+- Warnings: Why processing stopped
+- Errors: Where errors occurred
+
+Principle: "If it feels like magic, explain it!"
+"""
+
+from datetime import datetime
+from typing import Dict, List, Optional
+import json
+
+
+class Logger:
+    """
+    Centralized logger for all additory operations.
+    
+    Provides three levels of logging:
+    - info: Explain assumptions and defaults
+    - warning: Explain why processing stopped
+    - error: Show where error occurred
+    """
+    
+    def __init__(self, level: str = 'info'):
+        """
+        Initialize logger with level.
+        
+        Args:
+            level: Logging level ('info', 'warning', 'error', 'silent')
+        """
+        self.level = level
+        self.context: Dict = {}
+        self.messages: List[Dict] = []
+        self._validate_level(level)
+    
+    def _validate_level(self, level: str) -> None:
+        """Validate logging level."""
+        valid_levels = ['info', 'warning', 'error', 'silent']
+        if level not in valid_levels:
+            raise ValueError(f"Invalid log level '{level}'. Must be one of: {valid_levels}")
+    
+    def set_level(self, level: str) -> None:
+        """
+        Set logging level.
+        
+        Args:
+            level: New logging level ('info', 'warning', 'error', 'silent')
+        """
+        self._validate_level(level)
+        self.level = level
+    
+    def set_context(self, operation: str, details: Optional[Dict] = None) -> None:
+        """
+        Set current operation context.
+        
+        Args:
+            operation: Operation name ('to', 'transform', 'snapshot', 'synthetic', 'analyze')
+            details: Optional operation details
+        """
+        self.context = {
+            'operation': operation,
+            'details': details or {},
+            'timestamp': datetime.now().isoformat()
+        }
+    
+    def info(self, message: str, details: Optional[Dict] = None) -> None:
+        """
+        Log information message (assumptions, defaults).
+        
+        Args:
+            message: Information message
+            details: Optional additional details
+            
+        Example:
+            logger.info("Using 'fetch if unique' mode for column 'price'")
+            logger.info("Detected pandas DataFrame, converting to Polars")
+        """
+        if self.level == 'info':
+            self._log('info', message, details)
+    
+    def warning(self, message: str, details: Optional[Dict] = None) -> None:
+        """
+        Log warning message (why processing stopped).
+        
+        Args:
+            message: Warning message
+            details: Optional additional details
+            
+        Example:
+            logger.warning("Many-to-many relationship detected, cannot proceed")
+            logger.warning("Duplicate expression name 'bmi' found")
+        """
+        if self.level in ['info', 'warning']:
+            self._log('warning', message, details)
+    
+    def error(self, message: str, error_location: str, details: Optional[Dict] = None) -> None:
+        """
+        Log error message (where error occurred).
+        
+        Args:
+            message: Error message
+            error_location: Where error occurred ('df', 'expression', 'strategy', etc.)
+            details: Optional additional details
+            
+        Example:
+            logger.error("Column 'age' not found", error_location='df')
+            logger.error("Division by zero", error_location='expression')
+        """
+        if self.level != 'silent':
+            error_details = details or {}
+            error_details['error_location'] = error_location
+            self._log('error', message, error_details)
+    
+    def _log(self, level: str, message: str, details: Optional[Dict] = None) -> None:
+        """Internal method to log a message."""
+        log_entry = {
+            'level': level,
+            'message': message,
+            'context': self.context.copy(),
+            'details': details or {},
+            'timestamp': datetime.now().isoformat()
+        }
+        self.messages.append(log_entry)
+        
+        # Print formatted message
+        formatted = format_message(level, message, self.context, details or {})
+        print(formatted)
+    
+    def get_messages(self, level: Optional[str] = None) -> List[Dict]:
+        """
+        Get logged messages.
+        
+        Args:
+            level: Filter by level (None = all)
+            
+        Returns:
+            List of message dictionaries
+        """
+        if level is None:
+            return self.messages.copy()
+        return [msg for msg in self.messages if msg['level'] == level]
+    
+    def clear(self) -> None:
+        """Clear all logged messages."""
+        self.messages.clear()
+        self.context.clear()
+
+
+# Global logger instance
+_global_logger: Optional[Logger] = None
+
+
+def get_logger() -> Logger:
+    """
+    Get the global logger instance.
+    
+    Returns:
+        Global Logger instance
+        
+    Example:
+        logger = get_logger()
+        logger.info("Processing started")
+    """
+    global _global_logger
+    if _global_logger is None:
+        _global_logger = Logger()
+    return _global_logger
+
+
+def set_log_level(level: str) -> None:
+    """
+    Set global logging level.
+    
+    Args:
+        level: Logging level ('info', 'warning', 'error', 'silent')
+        
+    Example:
+        import additory
+        additory.add.set_log_level('warning')
+    """
+    logger = get_logger()
+    logger.set_level(level)
+
+
+def format_message(level: str, message: str, context: Dict, details: Dict) -> str:
+    """
+    Format log message for display.
+    
+    Args:
+        level: Message level
+        message: Message text
+        context: Operation context
+        details: Additional details
+        
+    Returns:
+        Formatted message string
+    """
+    # Level prefix with emoji
+    level_prefix = {
+        'info': 'ℹ️  INFO',
+        'warning': '⚠️  WARNING',
+        'error': '❌ ERROR'
+    }
+    
+    prefix = level_prefix.get(level, level.upper())
+    
+    # Build message
+    parts = [f"[{prefix}]"]
+    
+    # Add context if available
+    if context and 'operation' in context:
+        parts.append(f"[{context['operation']}]")
+    
+    # Add main message
+    parts.append(message)
+    
+    formatted = " ".join(parts)
+    
+    # Add details if available and not empty
+    if details and any(details.values()):
+        # Filter out None values and format
+        clean_details = {k: v for k, v in details.items() if v is not None}
+        if clean_details:
+            details_str = json.dumps(clean_details, indent=2)
+            formatted += f"\n  Details: {details_str}"
+    
+    return formatted