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

additory/common/resolver.py

@@ -1,567 +0,0 @@
-"""
-Pattern Resolution with Fallback Logic
-
-Implements the fallback resolution hierarchy for pattern lookup:
-1. User namespace patterns (if enabled, based on priority)
-2. Imported .list files (non-global)
-3. global.list (built-in)
-4. Imported .properties files (non-global)
-5. global.properties (built-in)
-6. Error if not found
-
-User namespace priority options:
-- "highest": Check user namespace first (before everything)
-- "before_imports": Check user namespace before imports (default)
-- "after_imports": Check user namespace after imports
-- "lowest": Check user namespace last (after everything)
-
-Usage:
-    from additory.common.resolver import resolve_pattern, PreferMode
-    
-    # Without user namespace
-    result = resolve_pattern(
-        pattern_name="first_names",
-        imports=["global", "finance"],
-        prefer_mode=PreferMode.DEFAULT,
-        base_path="reference/schema_definitions"
-    )
-    
-    # With user namespace
-    from additory.common.resolver import PatternResolver
-    
-    resolver = PatternResolver(
-        base_path="reference/schema_definitions",
-        enable_user_namespace=True,
-        user_namespace_priority="before_imports"
-    )
-    
-    result = resolver.resolve("my_custom_pattern", ["global"])
-    
-    if result.found:
-        print(f"Found in: {result.source}")
-        print(f"Type: {result.pattern_type}")
-        print(f"Value: {result.value}")
-"""
-
-from typing import Union, List, Optional, Dict
-from pathlib import Path
-from dataclasses import dataclass
-from enum import Enum
-import logging
-
-from .lists import load_list_file, get_list_values, ListFileError
-from .patterns import load_properties_file, get_pattern, PatternFileError
-
-
-# Configure logging
-logger = logging.getLogger(__name__)
-
-
-class PreferMode(Enum):
-    """Pattern resolution preference modes."""
-    DEFAULT = "default"          # Lists first, regex fallback
-    LIST_ONLY = "list_only"      # Lists only, error if not found
-    REGEX_ONLY = "regex_only"    # Regex only, error if not found
-    USER_ONLY = "user_only"      # User namespace only (Phase II)
-    BUILTIN_ONLY = "builtin_only"  # Built-in patterns only (no user namespace)
-
-
-@dataclass
-class PatternResolutionResult:
-    """Result of pattern resolution."""
-    found: bool
-    value: Optional[Union[List[str], str]] = None
-    pattern_type: Optional[str] = None  # "list" or "regex"
-    source: Optional[str] = None  # File where pattern was found
-    fallback_used: bool = False
-    error_message: Optional[str] = None
-
-
-class PatternResolver:
-    """
-    Resolves patterns with fallback logic.
-    
-    Implements the fallback hierarchy:
-    1. User namespace patterns (if enabled)
-    2. Imported .list files (non-global)
-    3. global.list
-    4. Imported .properties files (non-global)
-    5. global.properties
-    """
-    
-    def __init__(
-        self,
-        base_path: str = "reference/schema_definitions",
-        enable_user_namespace: bool = False,
-        user_namespace_priority: str = "before_imports",
-        user_namespace_manager=None
-    ):
-        """
-        Initialize resolver.
-        
-        Args:
-            base_path: Base directory for .list and .properties files
-            enable_user_namespace: Enable user namespace resolution
-            user_namespace_priority: User namespace priority
-                - "before_imports": Check user namespace before imports
-                - "after_imports": Check user namespace after imports
-                - "highest": Check user namespace first (before everything)
-                - "lowest": Check user namespace last (after everything)
-            user_namespace_manager: Optional UserNamespaceManager instance
-        """
-        self.base_path = Path(base_path)
-        self.enable_user_namespace = enable_user_namespace
-        self.user_namespace_priority = user_namespace_priority
-        self._list_cache: Dict[str, Dict[str, List[str]]] = {}
-        self._pattern_cache: Dict[str, Dict[str, str]] = {}
-        self._user_namespace_manager = user_namespace_manager
-        
-        # Initialize user namespace if enabled and not provided
-        if self.enable_user_namespace and self._user_namespace_manager is None:
-            try:
-                from additory.core.user_namespace import get_user_namespace_manager
-                self._user_namespace_manager = get_user_namespace_manager()
-                if self._user_namespace_manager.is_initialized():
-                    logger.info("User namespace enabled and initialized")
-                else:
-                    logger.warning("User namespace enabled but not initialized")
-            except ImportError:
-                logger.warning("User namespace module not available")
-                self.enable_user_namespace = False
-    
-    def _load_list_file_cached(self, filename: str) -> Optional[Dict[str, List[str]]]:
-        """Load .list file with caching."""
-        if filename in self._list_cache:
-            return self._list_cache[filename]
-        
-        filepath = self.base_path / filename
-        
-        try:
-            lists = load_list_file(str(filepath))
-            self._list_cache[filename] = lists
-            return lists
-        except ListFileError as e:
-            logger.debug(f"Failed to load {filename}: {e}")
-            return None
-    
-    def _load_properties_file_cached(self, filename: str) -> Optional[Dict[str, str]]:
-        """Load .properties file with caching."""
-        if filename in self._pattern_cache:
-            return self._pattern_cache[filename]
-        
-        filepath = self.base_path / filename
-        
-        try:
-            patterns = load_properties_file(str(filepath))
-            self._pattern_cache[filename] = patterns
-            return patterns
-        except PatternFileError as e:
-            logger.debug(f"Failed to load {filename}: {e}")
-            return None
-    
-    def resolve_from_lists(
-        self,
-        pattern_name: str,
-        imports: List[str]
-    ) -> PatternResolutionResult:
-        """
-        Resolve pattern from .list files.
-        
-        Priority:
-        1. Imported .list files (non-global)
-        2. global.list
-        """
-        # Check imported .list files (non-global)
-        for import_name in imports:
-            if import_name == "global":
-                continue  # Skip global, check it last
-            
-            filename = f"{import_name}.list"
-            lists = self._load_list_file_cached(filename)
-            
-            if lists:
-                values = get_list_values(pattern_name, lists)
-                if values:
-                    logger.info(f"✓ Found '{pattern_name}' in {filename}")
-                    return PatternResolutionResult(
-                        found=True,
-                        value=values,
-                        pattern_type="list",
-                        source=filename,
-                        fallback_used=False
-                    )
-        
-        # Check global.list (fallback)
-        lists = self._load_list_file_cached("global.list")
-        if lists:
-            values = get_list_values(pattern_name, lists)
-            if values:
-                logger.info(f"✓ Found '{pattern_name}' in global.list (fallback)")
-                return PatternResolutionResult(
-                    found=True,
-                    value=values,
-                    pattern_type="list",
-                    source="global.list",
-                    fallback_used=True
-                )
-        
-        return PatternResolutionResult(found=False)
-    
-    def resolve_from_patterns(
-        self,
-        pattern_name: str,
-        imports: List[str]
-    ) -> PatternResolutionResult:
-        """
-        Resolve pattern from .properties files.
-        
-        Priority:
-        1. Imported .properties files (non-global)
-        2. global.properties
-        """
-        # Check imported .properties files (non-global)
-        for import_name in imports:
-            if import_name == "global":
-                continue  # Skip global, check it last
-            
-            filename = f"{import_name}.properties"
-            patterns = self._load_properties_file_cached(filename)
-            
-            if patterns:
-                pattern = get_pattern(pattern_name, patterns)
-                if pattern:
-                    logger.info(f"✓ Found '{pattern_name}' in {filename}")
-                    return PatternResolutionResult(
-                        found=True,
-                        value=pattern,
-                        pattern_type="regex",
-                        source=filename,
-                        fallback_used=False
-                    )
-        
-        # Check global.properties (fallback)
-        patterns = self._load_properties_file_cached("global.properties")
-        if patterns:
-            pattern = get_pattern(pattern_name, patterns)
-            if pattern:
-                logger.info(f"✓ Found '{pattern_name}' in global.properties (fallback)")
-                return PatternResolutionResult(
-                    found=True,
-                    value=pattern,
-                    pattern_type="regex",
-                    source="global.properties",
-                    fallback_used=True
-                )
-        
-        return PatternResolutionResult(found=False)
-    
-    def resolve(
-        self,
-        pattern_name: str,
-        imports: List[str],
-        prefer_mode: PreferMode = PreferMode.DEFAULT
-    ) -> PatternResolutionResult:
-        """
-        Resolve pattern with fallback logic including user namespace.
-        
-        Resolution hierarchy (with user namespace enabled):
-        1. User namespace (if priority = "highest" or "before_imports")
-        2. Imported .list files (non-global)
-        3. global.list
-        4. User namespace (if priority = "after_imports")
-        5. Imported .properties files (non-global)
-        6. global.properties
-        7. User namespace (if priority = "lowest")
-        
-        Args:
-            pattern_name: Name of pattern to resolve
-            imports: List of imports from TOML (e.g., ["global", "finance"])
-            prefer_mode: Resolution preference mode
-            
-        Returns:
-            PatternResolutionResult with resolution details
-        """
-        logger.info(f"Resolving pattern '{pattern_name}' with mode {prefer_mode.value}")
-        
-        # Mode: user_only
-        if prefer_mode == PreferMode.USER_ONLY:
-            result = self.resolve_from_user_namespace(pattern_name)
-            if not result.found:
-                result.error_message = f"Pattern '{pattern_name}' not found in user namespace"
-            return result
-        
-        # Mode: builtin_only (disable user namespace for this resolution)
-        elif prefer_mode == PreferMode.BUILTIN_ONLY:
-            # Temporarily disable user namespace
-            original_enable = self.enable_user_namespace
-            self.enable_user_namespace = False
-            
-            try:
-                # Use default resolution without user namespace
-                result = self._resolve_builtin(pattern_name, imports)
-                return result
-            finally:
-                self.enable_user_namespace = original_enable
-        
-        # Mode: list_only
-        elif prefer_mode == PreferMode.LIST_ONLY:
-            result = self._resolve_with_user_namespace(
-                pattern_name, imports, lists_only=True
-            )
-            if not result.found:
-                result.error_message = f"Pattern '{pattern_name}' not found in any .list file"
-            return result
-        
-        # Mode: regex_only
-        elif prefer_mode == PreferMode.REGEX_ONLY:
-            result = self._resolve_with_user_namespace(
-                pattern_name, imports, regex_only=True
-            )
-            if not result.found:
-                result.error_message = f"Pattern '{pattern_name}' not found in any .properties file"
-            return result
-        
-        # Mode: default (lists first, regex fallback, with user namespace)
-        else:
-            result = self._resolve_with_user_namespace(pattern_name, imports)
-            
-            if not result.found:
-                result.error_message = (
-                    f"Pattern '{pattern_name}' not found in any .list or .properties file"
-                )
-            
-            return result
-    
-    def _resolve_builtin(
-        self,
-        pattern_name: str,
-        imports: List[str]
-    ) -> PatternResolutionResult:
-        """
-        Resolve pattern from built-in patterns only (no user namespace).
-        
-        Used for BUILTIN_ONLY mode.
-        """
-        # Try lists first
-        result = self.resolve_from_lists(pattern_name, imports)
-        if result.found:
-            return result
-        
-        # Fallback to regex
-        logger.warning(f"'{pattern_name}' not found in any .list file, trying .properties")
-        result = self.resolve_from_patterns(pattern_name, imports)
-        
-        if result.found:
-            result.fallback_used = True
-        
-        return result
-    
-    def _resolve_with_user_namespace(
-        self,
-        pattern_name: str,
-        imports: List[str],
-        lists_only: bool = False,
-        regex_only: bool = False
-    ) -> PatternResolutionResult:
-        """
-        Resolve pattern with user namespace support.
-        
-        Implements the full resolution hierarchy based on user_namespace_priority.
-        """
-        # Priority: highest (check user namespace first)
-        if self.enable_user_namespace and self.user_namespace_priority == "highest":
-            result = self.resolve_from_user_namespace(pattern_name)
-            if result.found:
-                return result
-        
-        # Priority: before_imports (check user namespace before imports)
-        if self.enable_user_namespace and self.user_namespace_priority == "before_imports":
-            result = self.resolve_from_user_namespace(pattern_name)
-            if result.found:
-                return result
-        
-        # Check lists (unless regex_only)
-        if not regex_only:
-            result = self.resolve_from_lists(pattern_name, imports)
-            if result.found:
-                return result
-        
-        # Priority: after_imports (check user namespace after imports, before global)
-        if self.enable_user_namespace and self.user_namespace_priority == "after_imports":
-            result = self.resolve_from_user_namespace(pattern_name)
-            if result.found:
-                result.fallback_used = True
-                return result
-        
-        # Check regex patterns (unless lists_only)
-        if not lists_only:
-            logger.warning(f"'{pattern_name}' not found in any .list file, trying .properties")
-            result = self.resolve_from_patterns(pattern_name, imports)
-            if result.found:
-                result.fallback_used = True
-                return result
-        
-        # Priority: lowest (check user namespace last)
-        if self.enable_user_namespace and self.user_namespace_priority == "lowest":
-            result = self.resolve_from_user_namespace(pattern_name)
-            if result.found:
-                result.fallback_used = True
-                return result
-        
-        # Not found anywhere
-        return PatternResolutionResult(found=False)
-    
-    def clear_cache(self):
-        """Clear cached files (useful for testing)."""
-        self._list_cache.clear()
-        self._pattern_cache.clear()
-        if self._user_namespace_manager:
-            self._user_namespace_manager.clear_cache()
-    
-    def resolve_from_user_namespace(
-        self,
-        pattern_name: str
-    ) -> PatternResolutionResult:
-        """
-        Resolve pattern from user namespace.
-        
-        Checks user .list and .properties files.
-        """
-        if not self.enable_user_namespace or not self._user_namespace_manager:
-            return PatternResolutionResult(found=False)
-        
-        try:
-            # Get all user patterns
-            user_lists, user_properties = self._user_namespace_manager.get_all_user_patterns()
-            
-            # Check user lists first
-            if pattern_name in user_lists:
-                logger.info(f"✓ Found '{pattern_name}' in user namespace (list)")
-                return PatternResolutionResult(
-                    found=True,
-                    value=user_lists[pattern_name],
-                    pattern_type="list",
-                    source="user:namespace",
-                    fallback_used=False
-                )
-            
-            # Check user properties
-            if pattern_name in user_properties:
-                logger.info(f"✓ Found '{pattern_name}' in user namespace (regex)")
-                return PatternResolutionResult(
-                    found=True,
-                    value=user_properties[pattern_name],
-                    pattern_type="regex",
-                    source="user:namespace",
-                    fallback_used=False
-                )
-        
-        except Exception as e:
-            logger.warning(f"Error resolving from user namespace: {e}")
-        
-        return PatternResolutionResult(found=False)
-
-
-# Global resolver instance
-_resolver = None
-
-
-def get_resolver(
-    base_path: str = "reference/schema_definitions",
-    enable_user_namespace: bool = False,
-    user_namespace_priority: str = "before_imports"
-) -> PatternResolver:
-    """
-    Get or create global resolver instance.
-    
-    Args:
-        base_path: Base directory for pattern files
-        enable_user_namespace: Enable user namespace resolution
-        user_namespace_priority: User namespace priority
-        
-    Returns:
-        PatternResolver instance
-    """
-    global _resolver
-    if _resolver is None:
-        _resolver = PatternResolver(
-            base_path,
-            enable_user_namespace,
-            user_namespace_priority
-        )
-    return _resolver
-
-
-def resolve_pattern(
-    pattern_name: str,
-    imports: List[str],
-    prefer_mode: PreferMode = PreferMode.DEFAULT,
-    base_path: str = "reference/schema_definitions",
-    enable_user_namespace: bool = False,
-    user_namespace_priority: str = "before_imports"
-) -> PatternResolutionResult:
-    """
-    Resolve pattern with fallback logic (convenience function).
-    
-    Args:
-        pattern_name: Name of pattern to resolve
-        imports: List of imports from TOML
-        prefer_mode: Resolution preference mode
-        base_path: Base directory for pattern files
-        enable_user_namespace: Enable user namespace resolution
-        user_namespace_priority: User namespace priority
-        
-    Returns:
-        PatternResolutionResult
-        
-    Example:
-        >>> result = resolve_pattern("first_names", ["global"], PreferMode.DEFAULT)
-        >>> if result.found:
-        ...     print(f"Found in {result.source}: {result.value[:3]}")
-        Found in global.list: ['Arjun', 'Vikram', 'Samuel']
-        
-        >>> # With user namespace
-        >>> result = resolve_pattern(
-        ...     "my_custom_pattern",
-        ...     ["global"],
-        ...     enable_user_namespace=True
-        ... )
-        >>> if result.found:
-        ...     print(f"Found in {result.source}")
-        Found in user:namespace
-    """
-    resolver = get_resolver(base_path, enable_user_namespace, user_namespace_priority)
-    return resolver.resolve(pattern_name, imports, prefer_mode)
-
-
-def resolve_with_logging(
-    pattern_name: str,
-    imports: List[str],
-    prefer_mode: PreferMode = PreferMode.DEFAULT,
-    base_path: str = "reference/schema_definitions"
-) -> PatternResolutionResult:
-    """
-    Resolve pattern with detailed logging (convenience function).
-    
-    Same as resolve_pattern but with INFO-level logging enabled.
-    """
-    # Temporarily set logging level to INFO
-    original_level = logger.level
-    logger.setLevel(logging.INFO)
-    
-    try:
-        result = resolve_pattern(pattern_name, imports, prefer_mode, base_path)
-        
-        # Log result
-        if result.found:
-            logger.info(f"Resolution successful:")
-            logger.info(f"  Pattern: {pattern_name}")
-            logger.info(f"  Source: {result.source}")
-            logger.info(f"  Type: {result.pattern_type}")
-            logger.info(f"  Fallback used: {result.fallback_used}")
-        else:
-            logger.error(f"Resolution failed: {result.error_message}")
-        
-        return result
-    finally:
-        logger.setLevel(original_level)