wappa 0.1.0__py3-none-any.whl

wappa/persistence/json/handlers/table_handler.py

@@ -0,0 +1,263 @@
+"""
+JSON Table handler - mirrors Redis table handler functionality.
+
+Provides table cache operations using JSON file storage.
+"""
+
+import logging
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel
+
+from ..storage_manager import storage_manager
+from .utils.key_factory import default_key_factory
+
+logger = logging.getLogger("JSONTable")
+
+
+class JSONTable:
+    """
+    JSON-based table cache handler.
+    
+    Mirrors RedisTable functionality using file-based JSON storage.
+    Maintains the same API for seamless cache backend switching.
+    """
+    
+    def __init__(self, tenant: str):
+        """
+        Initialize JSON table handler.
+        
+        Args:
+            tenant: Tenant identifier
+        """
+        if not tenant:
+            raise ValueError(f"Missing required parameter: tenant={tenant}")
+        
+        self.tenant = tenant
+        self.keys = default_key_factory
+    
+    def _key(self, table_name: str, pkid: str) -> str:
+        """Build table key using KeyFactory (same as Redis)."""
+        return self.keys.table(self.tenant, table_name, pkid)
+    
+    # ---- Public API matching RedisTable ----
+    async def get(
+        self,
+        table_name: str,
+        pkid: str,
+        models: type[BaseModel] | None = None,
+    ) -> dict[str, Any] | None:
+        """
+        Get table row data.
+        
+        Args:
+            table_name: Table name
+            pkid: Primary key ID
+            models: Optional BaseModel class for deserialization
+        
+        Returns:
+            Table row data or None if not found
+        """
+        key = self._key(table_name, pkid)
+        return await storage_manager.get("tables", self.tenant, None, key, models)
+    
+    async def upsert(
+        self,
+        table_name: str,
+        pkid: str,
+        data: dict[str, Any] | BaseModel,
+        ttl: int | None = None,
+    ) -> bool:
+        """
+        Create or update table row data.
+        
+        Args:
+            table_name: Table name
+            pkid: Primary key ID
+            data: Data to store
+            ttl: Time to live in seconds
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        key = self._key(table_name, pkid)
+        return await storage_manager.set("tables", self.tenant, None, key, data, ttl)
+    
+    async def delete(self, table_name: str, pkid: str) -> int:
+        """
+        Delete table row data.
+        
+        Args:
+            table_name: Table name
+            pkid: Primary key ID
+        
+        Returns:
+            1 if deleted, 0 if didn't exist
+        """
+        key = self._key(table_name, pkid)
+        success = await storage_manager.delete("tables", self.tenant, None, key)
+        return 1 if success else 0
+    
+    async def exists(self, table_name: str, pkid: str) -> bool:
+        """
+        Check if table row exists.
+        
+        Args:
+            table_name: Table name
+            pkid: Primary key ID
+        
+        Returns:
+            True if exists, False otherwise
+        """
+        key = self._key(table_name, pkid)
+        return await storage_manager.exists("tables", self.tenant, None, key)
+    
+    async def get_field(self, table_name: str, pkid: str, field: str) -> Any | None:
+        """
+        Get a specific field from table row.
+        
+        Args:
+            table_name: Table name
+            pkid: Primary key ID
+            field: Field name
+        
+        Returns:
+            Field value or None if not found
+        """
+        row_data = await self.get(table_name, pkid)
+        if row_data is None:
+            return None
+        
+        if isinstance(row_data, dict):
+            return row_data.get(field)
+        else:
+            # BaseModel instance
+            return getattr(row_data, field, None)
+    
+    async def update_field(
+        self,
+        table_name: str,
+        pkid: str,
+        field: str,
+        value: Any,
+        ttl: int | None = None,
+    ) -> bool:
+        """
+        Update a specific field in table row.
+        
+        Args:
+            table_name: Table name
+            pkid: Primary key ID
+            field: Field name
+            value: New value
+            ttl: Time to live in seconds
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        row_data = await self.get(table_name, pkid)
+        if row_data is None:
+            row_data = {}
+        
+        if isinstance(row_data, BaseModel):
+            row_data = row_data.model_dump()
+        
+        row_data[field] = value
+        return await self.upsert(table_name, pkid, row_data, ttl)
+    
+    async def increment_field(
+        self,
+        table_name: str,
+        pkid: str,
+        field: str,
+        increment: int = 1,
+        ttl: int | None = None,
+    ) -> int | None:
+        """
+        Atomically increment an integer field in table row.
+        
+        Args:
+            table_name: Table name
+            pkid: Primary key ID
+            field: Field name
+            increment: Amount to increment by
+            ttl: Time to live in seconds
+        
+        Returns:
+            New value after increment or None on error
+        """
+        row_data = await self.get(table_name, pkid)
+        if row_data is None:
+            row_data = {}
+        
+        if isinstance(row_data, BaseModel):
+            row_data = row_data.model_dump()
+        
+        current_value = row_data.get(field, 0)
+        if not isinstance(current_value, (int, float)):
+            logger.warning(f"Cannot increment non-numeric field '{field}': {current_value}")
+            return None
+        
+        new_value = int(current_value) + increment
+        row_data[field] = new_value
+        
+        success = await self.upsert(table_name, pkid, row_data, ttl)
+        return new_value if success else None
+    
+    async def append_to_list(
+        self,
+        table_name: str,
+        pkid: str,
+        field: str,
+        value: Any,
+        ttl: int | None = None,
+    ) -> bool:
+        """
+        Append value to a list field in table row.
+        
+        Args:
+            table_name: Table name
+            pkid: Primary key ID
+            field: Field name containing list
+            value: Value to append
+            ttl: Time to live in seconds
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        row_data = await self.get(table_name, pkid)
+        if row_data is None:
+            row_data = {}
+        
+        if isinstance(row_data, BaseModel):
+            row_data = row_data.model_dump()
+        
+        current_list = row_data.get(field, [])
+        if not isinstance(current_list, list):
+            current_list = []
+        
+        current_list.append(value)
+        row_data[field] = current_list
+        
+        return await self.upsert(table_name, pkid, row_data, ttl)
+    
+    async def get_ttl(self, key: str) -> int:
+        """
+        Get remaining time to live for table cache.
+        
+        Returns:
+            Remaining TTL in seconds, -1 if no expiry, -2 if doesn't exist
+        """
+        return await storage_manager.get_ttl("tables", self.tenant, None)
+    
+    async def renew_ttl(self, key: str, ttl: int) -> bool:
+        """
+        Renew time to live for table cache.
+        
+        Args:
+            ttl: New time to live in seconds
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        return await storage_manager.set_ttl("tables", self.tenant, None, ttl)

wappa/persistence/json/handlers/user_handler.py

@@ -0,0 +1,213 @@
+"""
+JSON User handler - mirrors Redis user handler functionality.
+
+Provides user-specific cache operations using JSON file storage.
+"""
+
+import logging
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field
+
+from ..storage_manager import storage_manager
+from .utils.key_factory import default_key_factory
+
+logger = logging.getLogger("JSONUser")
+
+
+class JSONUser:
+    """
+    JSON-based user cache handler.
+    
+    Mirrors RedisUser functionality using file-based JSON storage.
+    Maintains the same API for seamless cache backend switching.
+    """
+    
+    def __init__(self, tenant: str, user_id: str):
+        """
+        Initialize JSON user handler.
+        
+        Args:
+            tenant: Tenant identifier
+            user_id: User identifier
+        """
+        if not tenant or not user_id:
+            raise ValueError(f"Missing required parameters: tenant={tenant}, user_id={user_id}")
+        
+        self.tenant = tenant
+        self.user_id = user_id
+        self.keys = default_key_factory
+    
+    def _key(self) -> str:
+        """Build user key using KeyFactory (same as Redis)."""
+        return self.keys.user(self.tenant, self.user_id)
+    
+    # ---- Public API matching RedisUser ----
+    async def get(self, models: type[BaseModel] | None = None) -> dict[str, Any] | None:
+        """
+        Get full user data.
+        
+        Args:
+            models: Optional BaseModel class for deserialization
+        
+        Returns:
+            User data dictionary or BaseModel instance, None if not found
+        """
+        key = self._key()
+        return await storage_manager.get("users", self.tenant, self.user_id, key, models)
+    
+    async def upsert(self, data: dict[str, Any] | BaseModel, ttl: int | None = None) -> bool:
+        """
+        Create or update user data.
+        
+        Args:
+            data: User data to store
+            ttl: Time to live in seconds
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        key = self._key()
+        return await storage_manager.set("users", self.tenant, self.user_id, key, data, ttl)
+    
+    async def delete(self) -> int:
+        """
+        Delete user data.
+        
+        Returns:
+            1 if deleted, 0 if didn't exist
+        """
+        key = self._key()
+        success = await storage_manager.delete("users", self.tenant, self.user_id, key)
+        return 1 if success else 0
+    
+    async def exists(self) -> bool:
+        """
+        Check if user data exists.
+        
+        Returns:
+            True if exists, False otherwise
+        """
+        key = self._key()
+        return await storage_manager.exists("users", self.tenant, self.user_id, key)
+    
+    async def get_field(self, field: str) -> Any | None:
+        """
+        Get a specific field from user data.
+        
+        Args:
+            field: Field name
+        
+        Returns:
+            Field value or None if not found
+        """
+        user_data = await self.get()
+        if user_data is None:
+            return None
+        
+        if isinstance(user_data, dict):
+            return user_data.get(field)
+        else:
+            # BaseModel instance
+            return getattr(user_data, field, None)
+    
+    async def update_field(self, field: str, value: Any, ttl: int | None = None) -> bool:
+        """
+        Update a specific field in user data.
+        
+        Args:
+            field: Field name
+            value: New value
+            ttl: Time to live in seconds
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        user_data = await self.get()
+        if user_data is None:
+            user_data = {}
+        
+        if isinstance(user_data, BaseModel):
+            user_data = user_data.model_dump()
+        
+        user_data[field] = value
+        return await self.upsert(user_data, ttl)
+    
+    async def increment_field(self, field: str, increment: int = 1, ttl: int | None = None) -> int | None:
+        """
+        Atomically increment an integer field.
+        
+        Args:
+            field: Field name
+            increment: Amount to increment by
+            ttl: Time to live in seconds
+        
+        Returns:
+            New value after increment or None on error
+        """
+        user_data = await self.get()
+        if user_data is None:
+            user_data = {}
+        
+        if isinstance(user_data, BaseModel):
+            user_data = user_data.model_dump()
+        
+        current_value = user_data.get(field, 0)
+        if not isinstance(current_value, (int, float)):
+            logger.warning(f"Cannot increment non-numeric field '{field}': {current_value}")
+            return None
+        
+        new_value = int(current_value) + increment
+        user_data[field] = new_value
+        
+        success = await self.upsert(user_data, ttl)
+        return new_value if success else None
+    
+    async def append_to_list(self, field: str, value: Any, ttl: int | None = None) -> bool:
+        """
+        Append value to a list field.
+        
+        Args:
+            field: Field name containing list
+            value: Value to append
+            ttl: Time to live in seconds
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        user_data = await self.get()
+        if user_data is None:
+            user_data = {}
+        
+        if isinstance(user_data, BaseModel):
+            user_data = user_data.model_dump()
+        
+        current_list = user_data.get(field, [])
+        if not isinstance(current_list, list):
+            current_list = []
+        
+        current_list.append(value)
+        user_data[field] = current_list
+        
+        return await self.upsert(user_data, ttl)
+    
+    async def get_ttl(self, key: str) -> int:
+        """
+        Get remaining time to live.
+        
+        Returns:
+            Remaining TTL in seconds, -1 if no expiry, -2 if doesn't exist
+        """
+        return await storage_manager.get_ttl("users", self.tenant, self.user_id)
+    
+    async def renew_ttl(self, key: str, ttl: int) -> bool:
+        """
+        Renew time to live.
+        
+        Args:
+            ttl: New time to live in seconds
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        return await storage_manager.set_ttl("users", self.tenant, self.user_id, ttl)

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

@@ -0,0 +1 @@
+"""JSON cache utilities package."""

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

@@ -0,0 +1,153 @@
+"""
+File system operations for JSON cache.
+
+Handles cache directory creation, file I/O, and project root detection.
+"""
+
+import asyncio
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .serialization import from_json_string, to_json_string
+
+logger = logging.getLogger("JSONFileManager")
+
+
+class FileManager:
+    """Manages file operations for JSON cache."""
+    
+    def __init__(self):
+        self._cache_root: Optional[Path] = None
+        self._file_locks: Dict[str, asyncio.Lock] = {}
+    
+    def _get_file_lock(self, file_path: str) -> asyncio.Lock:
+        """Get or create a lock for a specific file path."""
+        if file_path not in self._file_locks:
+            self._file_locks[file_path] = asyncio.Lock()
+        return self._file_locks[file_path]
+    
+    def get_cache_root(self) -> Path:
+        """Get or detect the cache root directory."""
+        if self._cache_root is None:
+            self._cache_root = self._detect_project_root()
+        return self._cache_root
+    
+    def _detect_project_root(self) -> Path:
+        """
+        Detect project root by looking for main.py with Wappa.run().
+        
+        Searches from current working directory upwards.
+        Falls back to current directory if not found.
+        """
+        current_dir = Path.cwd()
+        
+        # Search upwards for main.py containing Wappa.run()
+        for directory in [current_dir] + list(current_dir.parents):
+            main_py = directory / "main.py"
+            if main_py.exists():
+                try:
+                    content = main_py.read_text(encoding='utf-8')
+                    if "Wappa" in content and (".run()" in content or "app.run()" in content):
+                        cache_dir = directory / "cache"
+                        logger.info(f"Detected project root: {directory}")
+                        return cache_dir
+                except (IOError, UnicodeDecodeError):
+                    continue
+        
+        # Fallback to current directory + cache
+        fallback_cache = current_dir / "cache"
+        logger.info(f"Project root not detected, using fallback: {fallback_cache}")
+        return fallback_cache
+    
+    def ensure_cache_directories(self) -> None:
+        """Create cache directory structure if it doesn't exist."""
+        cache_root = self.get_cache_root()
+        cache_root.mkdir(exist_ok=True)
+        
+        # Create subdirectories
+        (cache_root / "users").mkdir(exist_ok=True)
+        (cache_root / "tables").mkdir(exist_ok=True)
+        (cache_root / "states").mkdir(exist_ok=True)
+        
+        logger.debug(f"Cache directories ensured at: {cache_root}")
+    
+    def get_cache_file_path(self, cache_type: str, tenant_id: str, user_id: str = None) -> Path:
+        """
+        Get the file path for a cache file.
+        
+        Args:
+            cache_type: "users", "tables", or "states"
+            tenant_id: Tenant identifier
+            user_id: User identifier (required for users and states)
+        
+        Returns:
+            Path to cache file
+        """
+        cache_root = self.get_cache_root()
+        
+        if cache_type == "users":
+            if not user_id:
+                raise ValueError("user_id is required for users cache")
+            return cache_root / "users" / f"{tenant_id}_{user_id}.json"
+        elif cache_type == "tables":
+            return cache_root / "tables" / f"{tenant_id}_tables.json"
+        elif cache_type == "states":
+            if not user_id:
+                raise ValueError("user_id is required for states cache")
+            return cache_root / "states" / f"{tenant_id}_{user_id}_state.json"
+        else:
+            raise ValueError(f"Invalid cache_type: {cache_type}")
+    
+    async def read_file(self, file_path: Path) -> Dict[str, Any]:
+        """Read and parse JSON file with file locking."""
+        async with self._get_file_lock(str(file_path)):
+            if not file_path.exists():
+                return {}
+            
+            try:
+                content = await asyncio.to_thread(file_path.read_text, encoding='utf-8')
+                return from_json_string(content)
+            except (IOError, json.JSONDecodeError) as e:
+                logger.error(f"Failed to read file {file_path}: {e}")
+                return {}
+    
+    async def write_file(self, file_path: Path, data: Dict[str, Any]) -> bool:
+        """Write data to JSON file with file locking."""
+        async with self._get_file_lock(str(file_path)):
+            try:
+                # Ensure parent directory exists
+                file_path.parent.mkdir(parents=True, exist_ok=True)
+                
+                # Write to temporary file first, then rename (atomic operation)
+                temp_file = file_path.with_suffix(file_path.suffix + '.tmp')
+                content = to_json_string(data)
+                
+                await asyncio.to_thread(temp_file.write_text, content, encoding='utf-8')
+                await asyncio.to_thread(temp_file.replace, file_path)
+                
+                return True
+            except IOError as e:
+                logger.error(f"Failed to write file {file_path}: {e}")
+                return False
+    
+    async def delete_file(self, file_path: Path) -> bool:
+        """Delete file with file locking."""
+        async with self._get_file_lock(str(file_path)):
+            try:
+                if file_path.exists():
+                    await asyncio.to_thread(file_path.unlink)
+                return True
+            except IOError as e:
+                logger.error(f"Failed to delete file {file_path}: {e}")
+                return False
+    
+    async def file_exists(self, file_path: Path) -> bool:
+        """Check if file exists."""
+        return await asyncio.to_thread(file_path.exists)
+
+
+# Global file manager instance
+file_manager = FileManager()

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

@@ -0,0 +1,11 @@
+"""
+Key factory for JSON cache using Redis patterns.
+
+Reuses the existing KeyFactory from Redis to maintain consistency
+across all cache implementations.
+"""
+
+from ....redis.redis_handler.utils.key_factory import KeyFactory, default_key_factory
+
+# Export the same key factory used by Redis for consistency
+__all__ = ["KeyFactory", "default_key_factory"]