wappa 0.1.0__py3-none-any.whl

wappa/persistence/json/handlers/utils/serialization.py

@@ -0,0 +1,121 @@
+"""
+JSON serialization utilities with BaseModel support.
+
+Provides JSON-based serialization compatible with Redis patterns
+while optimizing for file storage.
+"""
+
+import json
+import logging
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel
+
+logger = logging.getLogger("JSONSerde")
+
+
+def _datetime_handler(obj: Any) -> str:
+    """Handle datetime objects during JSON serialization."""
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    raise TypeError(f"Object of type {type(obj)} is not JSON serializable")
+
+
+def _convert_iso_strings_to_datetime(obj: Any) -> Any:
+    """Recursively convert ISO datetime strings back to datetime objects."""
+    if isinstance(obj, str):
+        # Try to parse as ISO datetime
+        try:
+            # Check if it looks like an ISO datetime (basic heuristic)
+            if "T" in obj and len(obj) >= 19:  # YYYY-MM-DDTHH:MM:SS minimum
+                return datetime.fromisoformat(obj.replace("Z", "+00:00"))
+        except (ValueError, AttributeError):
+            pass
+        return obj
+    elif isinstance(obj, dict):
+        return {k: _convert_iso_strings_to_datetime(v) for k, v in obj.items()}
+    elif isinstance(obj, list):
+        return [_convert_iso_strings_to_datetime(item) for item in obj]
+    else:
+        return obj
+
+
+def serialize_for_json(obj: Any) -> Any:
+    """Serialize Python object for JSON storage."""
+    if obj is None:
+        return None
+    if isinstance(obj, BaseModel):
+        return obj.model_dump()
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    if isinstance(obj, dict):
+        return {k: serialize_for_json(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [serialize_for_json(item) for item in obj]
+    return obj
+
+
+def deserialize_from_json(data: Any, model: type[BaseModel] | None = None) -> Any:
+    """Deserialize data from JSON storage."""
+    if data is None:
+        return None
+    
+    # Convert datetime strings back to datetime objects
+    data = _convert_iso_strings_to_datetime(data)
+    
+    if model is not None:
+        return model.model_validate(data)
+    
+    return data
+
+
+def create_cache_file_data(data: dict[str, Any], ttl: int | None = None) -> dict[str, Any]:
+    """Create JSON cache file structure with metadata."""
+    now = datetime.now()
+    expires_at = None
+    if ttl:
+        expires_at = datetime.fromtimestamp(now.timestamp() + ttl)
+    
+    return {
+        "_metadata": {
+            "created_at": now.isoformat(),
+            "expires_at": expires_at.isoformat() if expires_at else None,
+            "version": "1.0"
+        },
+        "data": serialize_for_json(data)
+    }
+
+
+def extract_cache_file_data(file_data: dict[str, Any]) -> dict[str, Any] | None:
+    """Extract data from JSON cache file, checking expiration."""
+    if not isinstance(file_data, dict):
+        return None
+    
+    metadata = file_data.get("_metadata", {})
+    expires_at_str = metadata.get("expires_at")
+    
+    # Check expiration
+    if expires_at_str:
+        try:
+            expires_at = datetime.fromisoformat(expires_at_str)
+            if datetime.now() > expires_at:
+                return None  # Expired
+        except ValueError:
+            logger.warning(f"Invalid expires_at format: {expires_at_str}")
+    
+    return file_data.get("data", {})
+
+
+def to_json_string(data: Any) -> str:
+    """Convert data to JSON string."""
+    return json.dumps(data, ensure_ascii=False, indent=2, default=_datetime_handler)
+
+
+def from_json_string(json_str: str) -> Any:
+    """Convert JSON string to data."""
+    try:
+        return json.loads(json_str)
+    except json.JSONDecodeError as e:
+        logger.error(f"Failed to parse JSON: {e}")
+        raise

wappa/persistence/json/json_cache_factory.py

@@ -0,0 +1,76 @@
+"""
+JSON cache factory implementation for Wappa framework.
+
+Creates JSON-backed cache instances using file-based storage
+with ICache adapters for uniform interface.
+"""
+
+from ..domain.interfaces.cache_factory import ICacheFactory
+from ..domain.interfaces.cache_interface import ICache
+from .cache_adapters import (
+    JSONStateCacheAdapter,
+    JSONTableCacheAdapter,
+    JSONUserCacheAdapter,
+)
+
+
+class JSONCacheFactory(ICacheFactory):
+    """
+    Factory for creating JSON-backed cache instances.
+
+    Uses file-based JSON storage with proper file management:
+    - State cache: Uses states subdirectory
+    - User cache: Uses users subdirectory  
+    - Table cache: Uses tables subdirectory
+
+    All instances implement the ICache interface through adapters.
+
+    Context (tenant_id, user_id) is injected at construction time, eliminating
+    manual parameter passing.
+
+    Cache files are automatically created in {project_root}/cache/ directory structure.
+    """
+
+    def __init__(self, tenant_id: str, user_id: str):
+        """Initialize JSON cache factory with context injection."""
+        super().__init__(tenant_id, user_id)
+
+    def create_state_cache(self) -> ICache:
+        """
+        Create JSON state cache instance.
+
+        Uses context (tenant_id, user_id) injected at construction time.
+        Stores data in {project_root}/cache/states/ directory.
+
+        Returns:
+            ICache adapter wrapping JSONStateHandler
+        """
+        return JSONStateCacheAdapter(
+            tenant_id=self.tenant_id, user_id=self.user_id
+        )
+
+    def create_user_cache(self) -> ICache:
+        """
+        Create JSON user cache instance.
+
+        Uses context (tenant_id, user_id) injected at construction time.
+        Stores data in {project_root}/cache/users/ directory.
+
+        Returns:
+            ICache adapter wrapping JSONUser
+        """
+        return JSONUserCacheAdapter(
+            tenant_id=self.tenant_id, user_id=self.user_id
+        )
+
+    def create_table_cache(self) -> ICache:
+        """
+        Create JSON table cache instance.
+
+        Uses context (tenant_id) injected at construction time.
+        Stores data in {project_root}/cache/tables/ directory.
+
+        Returns:
+            ICache adapter wrapping JSONTable
+        """
+        return JSONTableCacheAdapter(tenant_id=self.tenant_id)

wappa/persistence/json/storage_manager.py

@@ -0,0 +1,285 @@
+"""
+JSON storage manager for coordinating cache operations.
+
+Provides high-level interface for JSON cache operations with TTL support,
+BaseModel serialization, and atomic file operations.
+"""
+
+import logging
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel
+
+from .handlers.utils.file_manager import file_manager
+from .handlers.utils.serialization import (
+    create_cache_file_data,
+    deserialize_from_json,
+    extract_cache_file_data,
+    serialize_for_json,
+)
+
+logger = logging.getLogger("JSONStorageManager")
+
+
+class JSONStorageManager:
+    """High-level JSON storage operations manager."""
+    
+    def __init__(self):
+        # Ensure cache directories exist on initialization
+        file_manager.ensure_cache_directories()
+    
+    async def get(
+        self, 
+        cache_type: str, 
+        tenant_id: str, 
+        user_id: Optional[str], 
+        key: str,
+        model: type[BaseModel] | None = None
+    ) -> Any:
+        """
+        Get value from JSON cache.
+        
+        Args:
+            cache_type: "users", "tables", or "states"
+            tenant_id: Tenant identifier
+            user_id: User identifier (required for users/states)
+            key: Cache key
+            model: Optional BaseModel for deserialization
+        
+        Returns:
+            Cached value or None if not found/expired
+        """
+        try:
+            file_path = file_manager.get_cache_file_path(cache_type, tenant_id, user_id)
+            file_data = await file_manager.read_file(file_path)
+            
+            if not file_data:
+                return None
+            
+            # Extract data and check expiration
+            cache_data = extract_cache_file_data(file_data)
+            if cache_data is None:
+                # Expired - delete the file
+                await file_manager.delete_file(file_path)
+                return None
+            
+            # Get specific key data
+            if key not in cache_data:
+                return None
+            
+            value_data = cache_data[key]
+            return deserialize_from_json(value_data, model)
+            
+        except Exception as e:
+            logger.error(f"Failed to get key '{key}' from {cache_type} cache: {e}")
+            return None
+    
+    async def set(
+        self,
+        cache_type: str,
+        tenant_id: str,
+        user_id: Optional[str],
+        key: str,
+        value: Any,
+        ttl: Optional[int] = None
+    ) -> bool:
+        """
+        Set value in JSON cache.
+        
+        Args:
+            cache_type: "users", "tables", or "states"
+            tenant_id: Tenant identifier
+            user_id: User identifier (required for users/states)
+            key: Cache key
+            value: Value to cache
+            ttl: Time to live in seconds
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            file_path = file_manager.get_cache_file_path(cache_type, tenant_id, user_id)
+            
+            # Read existing data
+            file_data = await file_manager.read_file(file_path)
+            cache_data = extract_cache_file_data(file_data) if file_data else {}
+            if cache_data is None:
+                cache_data = {}
+            
+            # Update key
+            cache_data[key] = serialize_for_json(value)
+            
+            # Create new file data with TTL
+            new_file_data = create_cache_file_data(cache_data, ttl)
+            
+            # Write file
+            return await file_manager.write_file(file_path, new_file_data)
+            
+        except Exception as e:
+            logger.error(f"Failed to set key '{key}' in {cache_type} cache: {e}")
+            return False
+    
+    async def delete(
+        self,
+        cache_type: str,
+        tenant_id: str,
+        user_id: Optional[str],
+        key: str
+    ) -> bool:
+        """
+        Delete key from JSON cache.
+        
+        Args:
+            cache_type: "users", "tables", or "states"
+            tenant_id: Tenant identifier
+            user_id: User identifier (required for users/states)
+            key: Cache key to delete
+        
+        Returns:
+            True if deleted or didn't exist, False on error
+        """
+        try:
+            file_path = file_manager.get_cache_file_path(cache_type, tenant_id, user_id)
+            
+            # Read existing data
+            file_data = await file_manager.read_file(file_path)
+            if not file_data:
+                return True  # Already doesn't exist
+            
+            cache_data = extract_cache_file_data(file_data)
+            if cache_data is None or key not in cache_data:
+                return True  # Already doesn't exist
+            
+            # Remove key
+            del cache_data[key]
+            
+            # If no keys left, delete the file
+            if not cache_data:
+                return await file_manager.delete_file(file_path)
+            
+            # Otherwise update file
+            new_file_data = create_cache_file_data(cache_data)
+            return await file_manager.write_file(file_path, new_file_data)
+            
+        except Exception as e:
+            logger.error(f"Failed to delete key '{key}' from {cache_type} cache: {e}")
+            return False
+    
+    async def exists(
+        self,
+        cache_type: str,
+        tenant_id: str,
+        user_id: Optional[str],
+        key: str
+    ) -> bool:
+        """
+        Check if key exists in JSON cache.
+        
+        Args:
+            cache_type: "users", "tables", or "states"
+            tenant_id: Tenant identifier
+            user_id: User identifier (required for users/states)
+            key: Cache key to check
+        
+        Returns:
+            True if exists and not expired, False otherwise
+        """
+        try:
+            file_path = file_manager.get_cache_file_path(cache_type, tenant_id, user_id)
+            file_data = await file_manager.read_file(file_path)
+            
+            if not file_data:
+                return False
+            
+            cache_data = extract_cache_file_data(file_data)
+            if cache_data is None:
+                # Expired - delete the file
+                await file_manager.delete_file(file_path)
+                return False
+            
+            return key in cache_data
+            
+        except Exception as e:
+            logger.error(f"Failed to check existence of key '{key}' in {cache_type} cache: {e}")
+            return False
+    
+    async def get_ttl(
+        self,
+        cache_type: str,
+        tenant_id: str,
+        user_id: Optional[str]
+    ) -> int:
+        """
+        Get remaining TTL for cache file.
+        
+        Returns:
+            Remaining TTL in seconds, -1 if no expiry, -2 if doesn't exist
+        """
+        try:
+            file_path = file_manager.get_cache_file_path(cache_type, tenant_id, user_id)
+            file_data = await file_manager.read_file(file_path)
+            
+            if not file_data:
+                return -2  # Doesn't exist
+            
+            metadata = file_data.get("_metadata", {})
+            expires_at_str = metadata.get("expires_at")
+            
+            if not expires_at_str:
+                return -1  # No expiry
+            
+            try:
+                expires_at = datetime.fromisoformat(expires_at_str)
+                now = datetime.now()
+                
+                if now >= expires_at:
+                    return -2  # Already expired
+                
+                return int((expires_at - now).total_seconds())
+                
+            except ValueError:
+                return -1  # Invalid expiry format, treat as no expiry
+                
+        except Exception as e:
+            logger.error(f"Failed to get TTL for {cache_type} cache: {e}")
+            return -2
+    
+    async def set_ttl(
+        self,
+        cache_type: str,
+        tenant_id: str,
+        user_id: Optional[str],
+        ttl: int
+    ) -> bool:
+        """
+        Set TTL for cache file.
+        
+        Args:
+            ttl: Time to live in seconds
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            file_path = file_manager.get_cache_file_path(cache_type, tenant_id, user_id)
+            file_data = await file_manager.read_file(file_path)
+            
+            if not file_data:
+                return False  # File doesn't exist
+            
+            cache_data = extract_cache_file_data(file_data)
+            if cache_data is None:
+                return False  # Already expired
+            
+            # Create new file data with updated TTL
+            new_file_data = create_cache_file_data(cache_data, ttl)
+            return await file_manager.write_file(file_path, new_file_data)
+            
+        except Exception as e:
+            logger.error(f"Failed to set TTL for {cache_type} cache: {e}")
+            return False
+
+
+# Global storage manager instance
+storage_manager = JSONStorageManager()

wappa/persistence/memory/__init__.py

@@ -0,0 +1,14 @@
+"""
+Memory-based cache implementation for Wappa framework.
+
+Provides high-speed in-memory cache storage with TTL support.
+Suitable for development, testing, and single-process deployments.
+
+Usage:
+    wappa = Wappa(cache="memory")
+    # Data will be stored in memory with automatic TTL cleanup
+"""
+
+from .memory_cache_factory import MemoryCacheFactory
+
+__all__ = ["MemoryCacheFactory"]