wappa 0.1.6__py3-none-any.whl → 0.1.8__py3-none-any.whl

wappa/core/__init__.py

@@ -1,6 +1,89 @@
-"""Core module for Wappa framework."""
+"""
+Wappa Core Framework Components
 
-from .events import WappaEventHandler
+Provides access to core framework functionality including configuration,
+logging, events, plugins, and factory system.
+
+Clean Architecture: Core application logic and framework components.
+"""
+
+# Configuration & Settings
+from .config.settings import settings
+
+# Logging System  
+from .logging import get_logger, get_app_logger, setup_app_logging
+
+# Event System
+from .events import (
+    WappaEventHandler,
+    WappaEventDispatcher, 
+    DefaultMessageHandler,
+    DefaultStatusHandler,
+    DefaultErrorHandler,
+    DefaultHandlerFactory,
+    MessageLogStrategy,
+    StatusLogStrategy, 
+    ErrorLogStrategy,
+    WebhookURLFactory,
+    WebhookEndpointType,
+    webhook_url_factory,
+)
+
+# Factory System
+from .factory import WappaBuilder, WappaPlugin
+
+# Plugin System
+from .plugins import (
+    WappaCorePlugin,
+    AuthPlugin,
+    CORSPlugin,
+    DatabasePlugin,
+    RedisPlugin,
+    RateLimitPlugin,
+    CustomMiddlewarePlugin,
+    WebhookPlugin,
+)
+
+# Core Application
 from .wappa_app import Wappa
 
-__all__ = ["Wappa", "WappaEventHandler"]
+__all__ = [
+    # Configuration
+    "settings",
+    
+    # Logging
+    "get_logger", 
+    "get_app_logger",
+    "setup_app_logging",
+    
+    # Event System
+    "WappaEventHandler",
+    "WappaEventDispatcher",
+    "DefaultMessageHandler", 
+    "DefaultStatusHandler",
+    "DefaultErrorHandler",
+    "DefaultHandlerFactory",
+    "MessageLogStrategy",
+    "StatusLogStrategy",
+    "ErrorLogStrategy",
+    "WebhookURLFactory",
+    "WebhookEndpointType", 
+    "webhook_url_factory",
+    
+    # Factory System
+    "WappaBuilder",
+    "WappaPlugin", 
+    
+    # Plugin System
+    "WappaCorePlugin",
+    "AuthPlugin",
+    "CORSPlugin", 
+    "DatabasePlugin",
+    "RedisPlugin",
+    "RateLimitPlugin",
+    "CustomMiddlewarePlugin",
+    "WebhookPlugin",
+    
+    # Core Application
+    "Wappa",
+]

wappa/core/config/settings.py

@@ -5,6 +5,7 @@ Simple, reliable environment variable configuration focused on core WhatsApp fun
 """
 
 import os
+import sys
 import tomllib
 from pathlib import Path
 
@@ -41,6 +42,34 @@ def _get_version_from_pyproject() -> str:
     return "0.1.0"
 
 
+def _is_cli_context() -> bool:
+    """
+    Detect if we're running in CLI context (help, init, examples) vs server context (dev, prod).
+    
+    Returns:
+        True if running CLI commands that don't need WhatsApp credentials
+    """
+    # Check command line arguments
+    if len(sys.argv) > 1:
+        # Direct CLI commands that don't need credentials
+        cli_only_commands = {"--help", "-h", "init", "examples"}
+        
+        # Check for help flag or CLI-only commands
+        for arg in sys.argv[1:]:
+            if arg in cli_only_commands:
+                return True
+        
+        # Check if we're running wappa command directly (not through uvicorn)
+        if any("wappa" in arg for arg in sys.argv):
+            # If no server commands (dev/prod) are present, assume CLI context
+            server_commands = {"dev", "prod"}
+            has_server_command = any(cmd in sys.argv for cmd in server_commands)
+            if not has_server_command:
+                return True
+    
+    return False
+
+
 class Settings:
     """Application settings with environment-based configuration."""
 
@@ -98,9 +127,12 @@ class Settings:
         # Development/Production detection
         self.environment: str = os.getenv("ENVIRONMENT", "DEV")
 
-        # Apply validation
+        # Apply validation (skip WhatsApp validation for CLI-only commands)
         self._validate_settings()
-        self._validate_whatsapp_credentials()
+        
+        # Only validate WhatsApp credentials for server operations
+        if not _is_cli_context():
+            self._validate_whatsapp_credentials()
 
     def _validate_settings(self):
         """Validate settings values."""

wappa/core/plugins/wappa_core_plugin.py

@@ -149,9 +149,19 @@ class WappaCorePlugin:
             app.state.wappa_cache_type = self.cache_type.value
             logger.debug(f"💾 Set app.state.wappa_cache_type = {self.cache_type.value}")
 
-            # Initialize HTTP session for connection pooling (correct scope for app lifecycle)
-            app.state.http_session = aiohttp.ClientSession()
-            logger.debug("🌐 HTTP session initialized for connection pooling")
+            # Create persistent HTTP session with optimized connection pooling
+            logger.info("🌐 Creating persistent HTTP session...")
+            connector = aiohttp.TCPConnector(
+                limit=100,                    # Max connections
+                keepalive_timeout=30,         # Keep alive timeout
+                enable_cleanup_closed=True    # Auto cleanup closed connections
+            )
+            session = aiohttp.ClientSession(
+                connector=connector,
+                timeout=aiohttp.ClientTimeout(total=30)
+            )
+            app.state.http_session = session
+            logger.info("✅ Persistent HTTP session created - connections: 100, keepalive: 30s")
 
             # Log available endpoints
             base_url = (
@@ -198,10 +208,10 @@ class WappaCorePlugin:
         logger.info("🛑 Starting Wappa core shutdown...")
 
         try:
-            # Close HTTP session if it exists
+            # Close HTTP session and connector if it exists
             if hasattr(app.state, "http_session"):
                 await app.state.http_session.close()
-                logger.debug("🌐 HTTP session closed")
+                logger.info("🌐 Persistent HTTP session closed cleanly")
 
             # Clear cache type from app state
             if hasattr(app.state, "wappa_cache_type"):

wappa/database/__init__.py

@@ -1,8 +1,17 @@
 """
-Wappa Database Module
+Wappa Database Components
 
-This module provides database abstraction and adapters for SQLModel/SQLAlchemy
-async connections. It supports multiple database engines with a unified interface.
+Provides database abstraction and adapters for SQLModel/SQLAlchemy async 
+connections. Supports multiple database engines with a unified interface.
+
+Clean Architecture: Infrastructure layer database adapters.
+
+Usage:
+    # Base adapter
+    from wappa.database import DatabaseAdapter
+    
+    # Specific database adapters
+    from wappa.database import PostgreSQLAdapter, MySQLAdapter, SQLiteAdapter
 """
 
 from .adapter import DatabaseAdapter
@@ -11,8 +20,11 @@ from .adapters.postgresql_adapter import PostgreSQLAdapter
 from .adapters.sqlite_adapter import SQLiteAdapter
 
 __all__ = [
+    # Base Adapter
     "DatabaseAdapter",
+    
+    # Database Adapters (Clean Architecture: Infrastructure implementations)
     "PostgreSQLAdapter",
+    "MySQLAdapter", 
     "SQLiteAdapter",
-    "MySQLAdapter",
 ]

wappa/domain/interfaces/media_interface.py

@@ -14,8 +14,9 @@ and WhatsApp Cloud API 2025 specifications for the 4 core endpoints:
 
 from abc import ABC, abstractmethod
 from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
 from pathlib import Path
-from typing import BinaryIO
+from typing import BinaryIO, AsyncContextManager
 
 from wappa.domain.models.media_result import (
     MediaDeleteResult,
@@ -197,6 +198,9 @@ class IMediaHandler(ABC):
         media_id: str,
         destination_path: str | Path | None = None,
         sender_id: str | None = None,
+        use_tempfile: bool = False,
+        temp_suffix: str | None = None,
+        auto_cleanup: bool = True,
     ) -> MediaDownloadResult:
         """
         Download media by ID.
@@ -206,19 +210,69 @@ class IMediaHandler(ABC):
 
         Args:
             media_id: Platform-specific media identifier
-            destination_path: Optional path to save file
+            destination_path: Optional path to save file (ignored if use_tempfile=True)
             sender_id: Optional sender ID for filename generation
+            use_tempfile: If True, creates a temporary file with automatic cleanup
+            temp_suffix: Custom suffix for temporary file (e.g., '.mp3', '.jpg')
+            auto_cleanup: If True, temp files are cleaned up automatically
 
         Returns:
             MediaDownloadResult with file data and metadata
 
         Note:
             If destination_path provided, saves file to disk.
-            If not provided, returns file data in memory.
+            If use_tempfile=True, creates temporary file that can be auto-cleaned.
+            If neither provided, returns file data in memory.
             Handles URL expiration by re-fetching URL if needed.
         """
         pass
 
+    @abstractmethod
+    async def download_media_tempfile(
+        self,
+        media_id: str,
+        temp_suffix: str | None = None,
+        sender_id: str | None = None,
+    ) -> AsyncContextManager[MediaDownloadResult]:
+        """
+        Download media to a temporary file with automatic cleanup.
+
+        Convenience method that provides a context manager for temporary file handling.
+        The temporary file is automatically deleted when the context exits.
+
+        Args:
+            media_id: Platform-specific media identifier
+            temp_suffix: Custom suffix for temporary file (e.g., '.mp3', '.jpg')
+            sender_id: Optional sender ID for logging/debugging
+
+        Returns:
+            Async context manager yielding MediaDownloadResult with temp file path
+
+        Example:
+            async with handler.download_media_tempfile(media_id, '.mp3') as result:
+                if result.success:
+                    # Use result.file_path - file auto-deleted on exit
+                    process_audio(result.file_path)
+        """
+        pass
+
+    @abstractmethod
+    async def get_media_as_bytes(
+        self, media_id: str
+    ) -> MediaDownloadResult:
+        """
+        Download media as bytes without creating any files.
+
+        Memory-only download for processing that doesn't require file system access.
+
+        Args:
+            media_id: Platform-specific media identifier
+
+        Returns:
+            MediaDownloadResult with file_data bytes (file_path will be None)
+        """
+        pass
+
     @abstractmethod
     async def stream_media(
         self, media_id: str, chunk_size: int = 8192

wappa/domain/models/media_result.py

@@ -6,7 +6,10 @@ messaging platforms, providing consistent response structures while
 maintaining compatibility with platform-specific response formats.
 """
 
+import os
 from datetime import datetime
+from pathlib import Path
+from typing import AsyncContextManager, Optional
 
 from pydantic import BaseModel, Field
 
@@ -71,6 +74,7 @@ class MediaDownloadResult(BaseModel):
 
     Standard response model for media download operations.
     Compatible with existing handle_media.py download patterns.
+    Supports context manager for automatic temporary file cleanup.
     """
 
     success: bool
@@ -84,12 +88,51 @@ class MediaDownloadResult(BaseModel):
     error_code: str | None = None
     downloaded_at: datetime = Field(default_factory=datetime.utcnow)
     tenant_id: str | None = None
+    _is_temp_file: bool = False
+    _cleanup_on_exit: bool = False
 
     class Config:
         use_enum_values = True
         # Allow bytes in file_data field
         arbitrary_types_allowed = True
 
+    def __enter__(self):
+        """Synchronous context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Synchronous context manager exit with cleanup."""
+        self._cleanup_temp_file()
+
+    async def __aenter__(self):
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit with cleanup."""
+        self._cleanup_temp_file()
+
+    def _cleanup_temp_file(self):
+        """Clean up temporary file if configured for auto-cleanup."""
+        if self._cleanup_on_exit and self._is_temp_file and self.file_path:
+            try:
+                file_path = Path(self.file_path)
+                if file_path.exists():
+                    file_path.unlink()
+            except Exception:
+                # Silently ignore cleanup errors - temp files will be cleaned by OS eventually
+                pass
+
+    def mark_as_temp_file(self, cleanup_on_exit: bool = True):
+        """Mark this result as containing a temporary file for cleanup.
+        
+        Args:
+            cleanup_on_exit: Whether to automatically delete the temp file when context exits
+        """
+        self._is_temp_file = True
+        self._cleanup_on_exit = cleanup_on_exit
+        return self
+
 
 class MediaDeleteResult(BaseModel):
     """Result of a media delete operation.

wappa/messaging/__init__.py

@@ -1,7 +1,57 @@
-"""Messaging interfaces and implementations for Wappa framework."""
+"""
+Wappa Messaging Components
 
+Provides access to messaging interfaces and platform-specific implementations
+including WhatsApp client, messenger, and specialized handlers.
+
+Clean Architecture: Application services and infrastructure implementations.
+
+Usage (User Request: Quick access to WhatsApp messaging components):
+    # Core messaging interface
+    from wappa.messaging import IMessenger
+    
+    # WhatsApp client and messenger
+    from wappa.messaging.whatsapp import WhatsAppClient, WhatsAppMessenger
+    
+    # WhatsApp specialized handlers  
+    from wappa.messaging.whatsapp import (
+        WhatsAppMediaHandler,
+        WhatsAppInteractiveHandler,
+        WhatsAppTemplateHandler,
+        WhatsAppSpecializedHandler
+    )
+"""
+
+# Core Messaging Interface
 from wappa.domain.interfaces.messaging_interface import IMessenger
 
-from .whatsapp.messenger.whatsapp_messenger import WhatsAppMessenger
+# WhatsApp Client & Messenger (User Request: Quick access)
+from .whatsapp.client import WhatsAppClient, WhatsAppUrlBuilder, WhatsAppFormDataBuilder
+from .whatsapp.messenger import WhatsAppMessenger
+
+# WhatsApp Specialized Handlers (User Request: Quick access)
+from .whatsapp.handlers import (
+    WhatsAppMediaHandler,
+    WhatsAppInteractiveHandler, 
+    WhatsAppTemplateHandler,
+    WhatsAppSpecializedHandler,
+)
 
-__all__ = ["IMessenger", "WhatsAppMessenger"]
+__all__ = [
+    # Core Interface
+    "IMessenger",
+    
+    # WhatsApp Client & Utilities
+    "WhatsAppClient",
+    "WhatsAppUrlBuilder",
+    "WhatsAppFormDataBuilder", 
+    
+    # WhatsApp Messenger
+    "WhatsAppMessenger",
+    
+    # WhatsApp Handlers (User Request: Clean access to all handlers)
+    "WhatsAppMediaHandler",
+    "WhatsAppInteractiveHandler",
+    "WhatsAppTemplateHandler", 
+    "WhatsAppSpecializedHandler",
+]

wappa/messaging/whatsapp/handlers/whatsapp_media_handler.py

@@ -6,10 +6,13 @@ to follow SOLID principles with dependency injection and proper separation of co
 """
 
 import mimetypes
+import os
+import tempfile
 import time
 from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
 from pathlib import Path
-from typing import Any, BinaryIO
+from typing import Any, BinaryIO, AsyncContextManager
 
 from wappa.core.logging.logger import get_logger
 from wappa.domain.interfaces.media_interface import IMediaHandler
@@ -319,12 +322,23 @@ class WhatsAppMediaHandler(IMediaHandler):
         media_id: str,
         destination_path: str | Path | None = None,
         sender_id: str | None = None,
+        use_tempfile: bool = False,
+        temp_suffix: str | None = None,
+        auto_cleanup: bool = True,
     ) -> MediaDownloadResult:
         """
         Download WhatsApp media using its media ID.
 
         Based on existing WhatsAppServiceMedia.download_media() method.
         Implements workflow: GET /MEDIA_ID -> GET /MEDIA_URL
+        
+        Args:
+            media_id: Platform-specific media identifier
+            destination_path: Optional path to save file (ignored if use_tempfile=True)
+            sender_id: Optional sender ID for filename generation
+            use_tempfile: If True, creates a temporary file with automatic cleanup
+            temp_suffix: Custom suffix for temporary file (e.g., '.mp3', '.jpg')
+            auto_cleanup: If True, temp files are cleaned up automatically
         """
         try:
             # Get media info first
@@ -395,9 +409,35 @@ class WhatsAppMediaHandler(IMediaHandler):
                             )
                         data.extend(chunk)
 
-                # Save to file if destination_path provided
+                # Save to file if destination_path provided or tempfile requested
                 final_path = None
-                if destination_path:
+                is_temp_file = False
+                
+                if use_tempfile:
+                    # Create temporary file
+                    extension_map = self._get_extension_map()
+                    extension = temp_suffix or extension_map.get(response_content_type, "")
+                    
+                    # Create named temporary file
+                    temp_fd, temp_path = tempfile.mkstemp(suffix=extension, prefix="wappa_media_")
+                    try:
+                        with os.fdopen(temp_fd, 'wb') as temp_file:
+                            temp_file.write(data)
+                        final_path = Path(temp_path)
+                        is_temp_file = True
+                        self.logger.info(
+                            f"Media downloaded to temp file {final_path} ({downloaded_size} bytes)"
+                        )
+                    except Exception:
+                        # Clean up on error
+                        try:
+                            os.unlink(temp_path)
+                        except Exception:
+                            pass
+                        raise
+                        
+                elif destination_path:
+                    # Original destination path logic
                     extension_map = self._get_extension_map()
                     extension = extension_map.get(response_content_type, "")
                     media_type_base = response_content_type.split("/")[0]
@@ -415,7 +455,8 @@ class WhatsAppMediaHandler(IMediaHandler):
                         f"Media successfully downloaded to {final_path} ({downloaded_size} bytes)"
                     )
 
-                return MediaDownloadResult(
+                # Create result with temp file handling
+                result = MediaDownloadResult(
                     success=True,
                     file_data=bytes(data),
                     file_path=str(final_path) if final_path else None,
@@ -425,6 +466,12 @@ class WhatsAppMediaHandler(IMediaHandler):
                     platform=PlatformType.WHATSAPP,
                     tenant_id=self._tenant_id,
                 )
+                
+                # Mark as temp file if needed
+                if is_temp_file:
+                    result.mark_as_temp_file(cleanup_on_exit=auto_cleanup)
+                    
+                return result
 
             finally:
                 # Ensure response is closed
@@ -440,6 +487,67 @@ class WhatsAppMediaHandler(IMediaHandler):
                 tenant_id=self._tenant_id,
             )
 
+    @asynccontextmanager
+    async def download_media_tempfile(
+        self,
+        media_id: str,
+        temp_suffix: str | None = None,
+        sender_id: str | None = None,
+    ) -> AsyncContextManager[MediaDownloadResult]:
+        """
+        Download media to a temporary file with automatic cleanup.
+
+        Convenience method that provides a context manager for temporary file handling.
+        The temporary file is automatically deleted when the context exits.
+
+        Args:
+            media_id: Platform-specific media identifier
+            temp_suffix: Custom suffix for temporary file (e.g., '.mp3', '.jpg')
+            sender_id: Optional sender ID for logging/debugging
+
+        Returns:
+            Async context manager yielding MediaDownloadResult with temp file path
+
+        Example:
+            async with handler.download_media_tempfile(media_id, '.mp3') as result:
+                if result.success:
+                    # Use result.file_path - file auto-deleted on exit
+                    process_audio(result.file_path)
+        """
+        result = await self.download_media(
+            media_id=media_id,
+            use_tempfile=True,
+            temp_suffix=temp_suffix,
+            sender_id=sender_id,
+            auto_cleanup=True
+        )
+        
+        try:
+            yield result
+        finally:
+            # Context manager cleanup handled by MediaDownloadResult
+            result._cleanup_temp_file()
+
+    async def get_media_as_bytes(
+        self, media_id: str
+    ) -> MediaDownloadResult:
+        """
+        Download media as bytes without creating any files.
+
+        Memory-only download for processing that doesn't require file system access.
+
+        Args:
+            media_id: Platform-specific media identifier
+
+        Returns:
+            MediaDownloadResult with file_data bytes (file_path will be None)
+        """
+        return await self.download_media(
+            media_id=media_id,
+            destination_path=None,
+            use_tempfile=False
+        )
+
     async def stream_media(
         self, media_id: str, chunk_size: int = 8192
     ) -> AsyncIterator[bytes]: