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

additory/core/user_namespace.py

@@ -1,751 +0,0 @@
-"""
-User Namespace Manager for Additory
-
-This module provides functionality for managing user-defined patterns and configurations
-in the ~/.additory/ directory. It allows users to create custom pattern files that can
-be used alongside built-in patterns.
-
-Author: Additory Team
-Date: 2026-01-24
-"""
-
-import os
-import json
-from pathlib import Path
-from typing import Dict, List, Optional, Any, Tuple
-from datetime import datetime
-import logging
-
-try:
-    import tomli as toml
-    import tomli_w as toml_w
-except ImportError:
-    import toml
-    # For writing, we'll use toml.dump which works for both
-    toml_w = toml
-
-from additory.common.lists import load_list_file, parse_list_file
-from additory.common.patterns import load_properties_file, parse_properties_file
-
-logger = logging.getLogger(__name__)
-
-
-class UserNamespaceError(Exception):
-    """Base exception for user namespace errors."""
-    pass
-
-
-class ConfigError(UserNamespaceError):
-    """Exception raised for configuration errors."""
-    pass
-
-
-class InitializationError(UserNamespaceError):
-    """Exception raised for initialization errors."""
-    pass
-
-
-class UserNamespaceManager:
-    """
-    Manages user namespace for custom patterns and configurations.
-    
-    The user namespace allows users to define custom patterns in ~/.additory/
-    that can be used alongside built-in patterns.
-    
-    Directory structure:
-        ~/.additory/
-        ├── config.toml
-        ├── patterns/
-        │   ├── *.list
-        │   └── *.properties
-        ├── schemas/
-        │   └── *.toml
-        └── cache/
-            └── resolution_cache.json
-    
-    Example:
-        >>> manager = UserNamespaceManager()
-        >>> if not manager.is_initialized():
-        ...     manager.initialize()
-        >>> config = manager.load_config()
-        >>> user_lists = manager.load_user_lists()
-    """
-    
-    DEFAULT_BASE_DIR = Path.home() / ".additory"
-    CONFIG_FILENAME = "config.toml"
-    
-    DEFAULT_CONFIG = {
-        "additory": {
-            "version": "1.0",
-            "created": None,  # Will be set during initialization
-        },
-        "patterns": {
-            "user_patterns_dir": "~/.additory/patterns",
-            "user_schemas_dir": "~/.additory/schemas",
-            "user_expressions_dir": "~/.additory/expressions",  # NEW
-            "auto_discover": True,
-            "watch_for_changes": False,
-        },
-        "cache": {
-            "enable_cache": True,
-            "cache_dir": "~/.additory/cache",
-            "cache_ttl": 3600,  # 1 hour
-            "max_cache_size": 100,  # MB
-        },
-        "resolution": {
-            "default_prefer_mode": "default",
-            "enable_user_namespace": True,
-            "user_namespace_priority": "before_imports",
-            "user_expression_priority": "user_first",  # NEW
-        },
-        "validation": {
-            "strict_mode": False,
-            "warn_on_unused_patterns": True,
-            "warn_on_duplicate_patterns": True,
-            "validate_on_load": False,
-        },
-        "logging": {
-            "log_level": "INFO",
-            "log_resolution_path": True,
-            "log_cache_hits": False,
-        },
-    }
-    
-    def __init__(self, base_dir: Optional[Path] = None):
-        """
-        Initialize the user namespace manager.
-        
-        Args:
-            base_dir: Base directory for user namespace (default: ~/.additory)
-        """
-        self.base_dir = Path(base_dir) if base_dir else self.DEFAULT_BASE_DIR
-        self.config_path = self.base_dir / self.CONFIG_FILENAME
-        self._config: Optional[Dict[str, Any]] = None
-        self._user_lists_cache: Optional[Dict[str, Dict[str, List[str]]]] = None
-        self._user_properties_cache: Optional[Dict[str, Dict[str, str]]] = None
-    
-    def is_initialized(self) -> bool:
-        """
-        Check if user namespace is initialized.
-        
-        Returns:
-            True if initialized, False otherwise
-        """
-        return (
-            self.base_dir.exists() and
-            self.config_path.exists() and
-            (self.base_dir / "patterns").exists()
-        )
-    
-    def initialize(self, force: bool = False) -> None:
-        """
-        Initialize user namespace directory structure.
-        
-        Creates the directory structure and default config file.
-        
-        Args:
-            force: If True, reinitialize even if already initialized
-            
-        Raises:
-            InitializationError: If initialization fails
-        """
-        if self.is_initialized() and not force:
-            logger.info(f"User namespace already initialized at {self.base_dir}")
-            return
-        
-        try:
-            # Create directory structure
-            self.base_dir.mkdir(parents=True, exist_ok=True)
-            (self.base_dir / "patterns").mkdir(exist_ok=True)
-            (self.base_dir / "schemas").mkdir(exist_ok=True)
-            (self.base_dir / "expressions").mkdir(exist_ok=True)  # NEW
-            (self.base_dir / "cache").mkdir(exist_ok=True)
-            
-            # Create default config
-            config = self.DEFAULT_CONFIG.copy()
-            config["additory"]["created"] = datetime.now().isoformat()
-            
-            # Update paths to use base_dir
-            config["patterns"]["user_patterns_dir"] = str(self.base_dir / "patterns")
-            config["patterns"]["user_schemas_dir"] = str(self.base_dir / "schemas")
-            config["patterns"]["user_expressions_dir"] = str(self.base_dir / "expressions")  # NEW
-            config["cache"]["cache_dir"] = str(self.base_dir / "cache")
-            
-            self._save_config(config)
-            
-            # Clear cached config if reinitializing
-            if force:
-                self._config = None
-            
-            # Create README files
-            self._create_readme_files()
-            
-            # Create example files
-            self._create_example_files()
-            
-            logger.info(f"User namespace initialized at {self.base_dir}")
-            
-        except Exception as e:
-            raise InitializationError(f"Failed to initialize user namespace: {e}")
-    
-    def load_config(self, reload: bool = False) -> Dict[str, Any]:
-        """
-        Load user configuration.
-        
-        Args:
-            reload: If True, reload config from disk
-            
-        Returns:
-            Configuration dictionary
-            
-        Raises:
-            ConfigError: If config cannot be loaded
-        """
-        if self._config is not None and not reload:
-            return self._config
-        
-        if not self.config_path.exists():
-            raise ConfigError(f"Config file not found: {self.config_path}")
-        
-        try:
-            with open(self.config_path, "r") as f:
-                self._config = toml.load(f)
-            return self._config
-        except Exception as e:
-            raise ConfigError(f"Failed to load config: {e}")
-    
-    def get_config(self, key: str, default: Any = None) -> Any:
-        """
-        Get configuration value by key.
-        
-        Args:
-            key: Configuration key (dot-separated, e.g., "cache.enable_cache")
-            default: Default value if key not found
-            
-        Returns:
-            Configuration value
-        """
-        config = self.load_config()
-        keys = key.split(".")
-        value = config
-        
-        for k in keys:
-            if isinstance(value, dict) and k in value:
-                value = value[k]
-            else:
-                return default
-        
-        return value
-    
-    def set_config(self, key: str, value: Any) -> None:
-        """
-        Set configuration value by key.
-        
-        Args:
-            key: Configuration key (dot-separated)
-            value: Value to set
-        """
-        config = self.load_config()
-        keys = key.split(".")
-        current = config
-        
-        for k in keys[:-1]:
-            if k not in current:
-                current[k] = {}
-            current = current[k]
-        
-        current[keys[-1]] = value
-        self._config = config
-    
-    def save_config(self) -> None:
-        """
-        Save configuration to disk.
-        
-        Raises:
-            ConfigError: If config cannot be saved
-        """
-        if self._config is None:
-            raise ConfigError("No config loaded to save")
-        
-        self._save_config(self._config)
-    
-    def _save_config(self, config: Dict[str, Any]) -> None:
-        """Internal method to save config."""
-        try:
-            with open(self.config_path, "w") as f:
-                toml_w.dump(config, f)
-        except Exception as e:
-            raise ConfigError(f"Failed to save config: {e}")
-    
-    def get_patterns_dir(self) -> Path:
-        """Get user patterns directory path."""
-        patterns_dir = self.get_config("patterns.user_patterns_dir")
-        path = Path(patterns_dir).expanduser()
-        # If path is relative to base_dir, resolve it
-        if not path.is_absolute():
-            path = self.base_dir / path
-        return path
-    
-    def get_schemas_dir(self) -> Path:
-        """Get user schemas directory path."""
-        schemas_dir = self.get_config("patterns.user_schemas_dir")
-        path = Path(schemas_dir).expanduser()
-        # If path is relative to base_dir, resolve it
-        if not path.is_absolute():
-            path = self.base_dir / path
-        return path
-    
-    def get_expressions_dir(self) -> Path:
-        """Get user expressions directory path."""
-        expressions_dir = self.get_config("patterns.user_expressions_dir")
-        path = Path(expressions_dir).expanduser()
-        # If path is relative to base_dir, resolve it
-        if not path.is_absolute():
-            path = self.base_dir / path
-        return path
-    
-    def get_cache_dir(self) -> Path:
-        """Get cache directory path."""
-        cache_dir = self.get_config("cache.cache_dir")
-        path = Path(cache_dir).expanduser()
-        # If path is relative to base_dir, resolve it
-        if not path.is_absolute():
-            path = self.base_dir / path
-        return path
-    
-    def discover_list_files(self) -> List[Path]:
-        """
-        Discover all .list files in user patterns directory.
-        
-        Returns:
-            List of .list file paths
-        """
-        patterns_dir = self.get_patterns_dir()
-        if not patterns_dir.exists():
-            return []
-        
-        return list(patterns_dir.glob("*.list"))
-    
-    def discover_properties_files(self) -> List[Path]:
-        """
-        Discover all .properties files in user patterns directory.
-        
-        Returns:
-            List of .properties file paths
-        """
-        patterns_dir = self.get_patterns_dir()
-        if not patterns_dir.exists():
-            return []
-        
-        return list(patterns_dir.glob("*.properties"))
-    
-    def load_user_lists(self, reload: bool = False) -> Dict[str, Dict[str, List[str]]]:
-        """
-        Load all user .list files.
-        
-        Args:
-            reload: If True, reload from disk
-            
-        Returns:
-            Dictionary mapping file names to list data
-            Format: {"filename": {"list_name": ["value1", "value2", ...]}}
-        """
-        if self._user_lists_cache is not None and not reload:
-            return self._user_lists_cache
-        
-        user_lists = {}
-        list_files = self.discover_list_files()
-        
-        for list_file in list_files:
-            try:
-                lists_data = load_list_file(str(list_file))
-                # Only add if we got valid data
-                if lists_data:
-                    filename = list_file.stem  # Without extension
-                    user_lists[filename] = lists_data
-                    logger.debug(f"Loaded user list file: {list_file}")
-            except Exception as e:
-                logger.warning(f"Failed to load user list file {list_file}: {e}")
-        
-        self._user_lists_cache = user_lists
-        return user_lists
-    
-    def load_user_properties(self, reload: bool = False) -> Dict[str, Dict[str, str]]:
-        """
-        Load all user .properties files.
-        
-        Args:
-            reload: If True, reload from disk
-            
-        Returns:
-            Dictionary mapping file names to properties data
-            Format: {"filename": {"pattern_name": "regex_pattern"}}
-        """
-        if self._user_properties_cache is not None and not reload:
-            return self._user_properties_cache
-        
-        user_properties = {}
-        properties_files = self.discover_properties_files()
-        
-        for properties_file in properties_files:
-            try:
-                properties_data = load_properties_file(str(properties_file))
-                filename = properties_file.stem  # Without extension
-                user_properties[filename] = properties_data
-                logger.debug(f"Loaded user properties file: {properties_file}")
-            except Exception as e:
-                logger.warning(f"Failed to load user properties file {properties_file}: {e}")
-        
-        self._user_properties_cache = user_properties
-        return user_properties
-    
-    def get_all_user_patterns(self) -> Tuple[Dict[str, List[str]], Dict[str, str]]:
-        """
-        Get all user patterns (lists and properties combined).
-        
-        Returns:
-            Tuple of (all_lists, all_properties)
-            - all_lists: {"pattern_name": ["value1", "value2", ...]}
-            - all_properties: {"pattern_name": "regex_pattern"}
-        """
-        user_lists = self.load_user_lists()
-        user_properties = self.load_user_properties()
-        
-        # Flatten lists
-        all_lists = {}
-        for filename, lists_data in user_lists.items():
-            all_lists.update(lists_data)
-        
-        # Flatten properties
-        all_properties = {}
-        for filename, properties_data in user_properties.items():
-            all_properties.update(properties_data)
-        
-        return all_lists, all_properties
-    
-    def clear_cache(self) -> None:
-        """Clear cached user patterns."""
-        self._user_lists_cache = None
-        self._user_properties_cache = None
-        logger.debug("User patterns cache cleared")
-    
-    def discover_expression_files(self) -> List[Path]:
-        """
-        Discover all .add files in user expressions directory.
-        
-        Returns:
-            List of .add file paths
-        """
-        expressions_dir = self.get_expressions_dir()
-        if not expressions_dir.exists():
-            return []
-        
-        return list(expressions_dir.glob("*.add"))
-    
-    def get_expression_manifest_path(self) -> Path:
-        """
-        Get path to user expression manifest file.
-        
-        Returns:
-            Path to manifest.json
-        """
-        return self.get_expressions_dir() / "manifest.json"
-    
-    def load_expression_manifest(self) -> Optional[Dict[str, Any]]:
-        """
-        Load user expression manifest.
-        
-        Returns:
-            Manifest dictionary or None if not found
-        """
-        manifest_path = self.get_expression_manifest_path()
-        
-        if not manifest_path.exists():
-            logger.debug(f"Expression manifest not found: {manifest_path}")
-            return None
-        
-        try:
-            import json
-            with open(manifest_path, "r") as f:
-                return json.load(f)
-        except Exception as e:
-            logger.warning(f"Failed to load expression manifest: {e}")
-            return None
-    
-    def get_user_expressions(self) -> Dict[str, str]:
-        """
-        Get all user expressions from manifest.
-        
-        Returns:
-            Dictionary mapping expression names to file paths
-            Format: {"expression_name": "/path/to/expression.add"}
-        """
-        manifest = self.load_expression_manifest()
-        
-        if not manifest:
-            return {}
-        
-        expressions_dir = self.get_expressions_dir()
-        user_expressions = {}
-        
-        # Support both old and new manifest formats
-        if "versions" in manifest:
-            # New format (v2.0)
-            for version, version_data in manifest.get("versions", {}).items():
-                for expr_name, expr_file in version_data.get("expressions", {}).items():
-                    expr_path = expressions_dir / expr_file
-                    if expr_path.exists():
-                        user_expressions[expr_name] = str(expr_path)
-        elif "expressions" in manifest:
-            # Old format (v1.0)
-            for expr_name, expr_file in manifest.get("expressions", {}).items():
-                expr_path = expressions_dir / expr_file
-                if expr_path.exists():
-                    user_expressions[expr_name] = str(expr_path)
-        
-        return user_expressions
-    
-    def _create_readme_files(self) -> None:
-        """Create README files in subdirectories."""
-        # Patterns README
-        patterns_readme = self.base_dir / "patterns" / "README.md"
-        patterns_readme.write_text("""# User Patterns
-
-This directory contains your custom pattern files.
-
-## File Types
-
-- **`.list` files**: Value lists (TOML format)
-- **`.properties` files**: Regex patterns (key-value format)
-
-## Example .list file
-
-```toml
-[lists]
-my_values = Value1, Value2, Value3
-my_other_values = A, B, C
-```
-
-## Example .properties file
-
-```properties
-my_pattern = PATTERN\\d{4}
-my_other_pattern = [A-Z]{3}-\\d{3}
-```
-
-## Usage
-
-These patterns can be referenced in your TOML schemas:
-
-```toml
-[generation]
-imports = ["global", "my_company"]
-
-[schema]
-field1 = "my_values"
-field2 = "my_pattern"
-```
-""")
-        
-        # Schemas README
-        schemas_readme = self.base_dir / "schemas" / "README.md"
-        schemas_readme.write_text("""# User Schemas
-
-This directory contains your custom TOML schema files.
-
-## Example Schema
-
-```toml
-[generation]
-imports = ["global"]
-
-[schema]
-field1 = "pattern_name"
-field2 = ["Value1", "Value2"]
-field3 = "REGEX\\d+"
-
-[metadata]
-name = "My Schema"
-version = "1.0"
-```
-""")
-        
-        # Expressions README
-        expressions_readme = self.base_dir / "expressions" / "README.md"
-        expressions_readme.write_text("""# User Expressions
-
-This directory contains your custom expression files (.add format).
-
-## File Format
-
-Expression files use YAML format with the following structure:
-
-```yaml
-formula:
-  name: my_calc
-  version: 0.1
-  description: My custom calculation
-  expression: |
-    (value1 + value2) / 2
-
-sample:
-  clean:
-    value1: [10, 20, 30]
-    value2: [5, 10, 15]
-    expected_result: [7.5, 15.0, 22.5]
-```
-
-## Manifest File
-
-Create a `manifest.json` file to register your expressions:
-
-```json
-{
-  "expressions": [
-    {
-      "name": "my_calc",
-      "version": "0.1",
-      "file": "my_calc_0.1.add",
-      "description": "My custom calculation"
-    }
-  ]
-}
-```
-
-## Usage
-
-Reference your expressions in augment or synthetic operations:
-
-```python
-from additory.augment import augment
-
-df_result = augment(
-    df,
-    expressions={"result": "my_calc"},
-    enable_user_namespace=True
-)
-```
-""")
-        
-        # Cache README
-        cache_readme = self.base_dir / "cache" / "README.md"
-        cache_readme.write_text("""# Cache Directory
-
-This directory contains cached pattern resolution data.
-
-Cache files are automatically managed and can be safely deleted.
-""")
-    
-    def _create_example_files(self) -> None:
-        """Create example pattern files."""
-        # Example .list file
-        example_list = self.base_dir / "patterns" / "example.list"
-        example_list.write_text("""# Example .list file
-# This file demonstrates the .list format for value lists
-
-[lists]
-# Simple value list
-example_statuses = Active, Inactive, Pending, Completed
-
-# Another example
-example_priorities = Low, Medium, High, Critical
-
-# You can add more lists here
-# my_custom_list = Value1, Value2, Value3
-""")
-        
-        # Example .properties file
-        example_properties = self.base_dir / "patterns" / "example.properties"
-        example_properties.write_text("""# Example .properties file
-# This file demonstrates the .properties format for regex patterns
-
-# Simple pattern
-example_id = EX\\d{6}
-
-# Email pattern
-example_email = [a-zA-Z0-9._%+-]+@example\\.com
-
-# You can add more patterns here
-# my_custom_pattern = PATTERN\\d+
-""")
-        
-        # Example expression file
-        example_expression = self.base_dir / "expressions" / "example_calc_0.1.add"
-        example_expression.write_text("""formula:
-  name: example_calc
-  version: 0.1
-  stability: alpha
-  type: cols
-  description: Example calculation - average of two values
-  author: user
-  tags:
-    - example
-    - calculation
-  expression: |
-    (value1 + value2) / 2
-  validation:
-    required_columns:
-      - value1
-      - value2
-    output_type: float64
-
-sample:
-  clean:
-    value1: [10, 20, 30, 40]
-    value2: [5, 10, 15, 20]
-    expected_result: [7.5, 15.0, 22.5, 30.0]
-
-documentation:
-  formula_explanation: |
-    This example calculates the average of two values.
-    It's a simple demonstration of the expression format.
-  examples:
-    - description: Average of 10 and 5
-      input:
-        value1: 10
-        value2: 5
-      output: 7.5
-""")
-        
-        # Example manifest file
-        example_manifest = self.base_dir / "expressions" / "manifest.json"
-        example_manifest.write_text("""{
-  "metadata": {
-    "name": "user-expressions",
-    "description": "User-defined expressions",
-    "maintainer": "user"
-  },
-  "versions": {
-    "0.1": {
-      "stability": "alpha",
-      "requires_engine": ">=0.1.0",
-      "expressions": {
-        "example_calc": "example_calc_0.1.add"
-      }
-    }
-  },
-  "manifest_version": "2.0"
-}
-""")
-
-
-# Singleton instance
-_user_namespace_manager: Optional[UserNamespaceManager] = None
-
-
-def get_user_namespace_manager(base_dir: Optional[Path] = None) -> UserNamespaceManager:
-    """
-    Get singleton user namespace manager instance.
-    
-    Args:
-        base_dir: Base directory for user namespace (default: ~/.additory)
-        
-    Returns:
-        UserNamespaceManager instance
-    """
-    global _user_namespace_manager
-    
-    if _user_namespace_manager is None:
-        _user_namespace_manager = UserNamespaceManager(base_dir)
-    
-    return _user_namespace_manager