wappa 0.1.5__py3-none-any.whl → 0.1.7__py3-none-any.whl

wappa/cli/main.py

@@ -5,40 +5,192 @@ Provides clean command-line interface for development and production workflows.
 """
 
 import os
+import shutil
 import subprocess
 import sys
 from pathlib import Path
 
 import typer
+from rich.console import Console
+from rich.table import Table
 
 app = typer.Typer(help="Wappa WhatsApp Business Framework CLI")
+console = Console()
+
+# Example projects metadata
+EXAMPLES = {
+    "init": {
+        "name": "Basic Project",
+        "description": "Minimal Wappa project with basic message handling",
+        "features": ["Message handling", "Mark as read", "Basic response"],
+        "complexity": "🟢 Beginner",
+    },
+    "simple_echo_example": {
+        "name": "Simple Echo Bot",
+        "description": "Echoes all incoming messages with acknowledgment",
+        "features": ["Message echo", "Media handling", "Clean architecture"],
+        "complexity": "🟢 Beginner",
+    },
+    "json_cache_example": {
+        "name": "JSON Cache Demo",
+        "description": "File-based caching with user management and state handling",
+        "features": ["JSON caching", "User management", "State handling", "Statistics"],
+        "complexity": "🟡 Intermediate",
+    },
+    "redis_cache_example": {
+        "name": "Redis Cache Demo",
+        "description": "Redis-powered caching with advanced state management",
+        "features": [
+            "Redis caching",
+            "Advanced state",
+            "Performance monitoring",
+            "Cache statistics",
+        ],
+        "complexity": "🟡 Intermediate",
+    },
+    "openai_transcript": {
+        "name": "OpenAI Transcription",
+        "description": "Voice message transcription using OpenAI Whisper API",
+        "features": ["Audio processing", "OpenAI integration", "Voice transcription"],
+        "complexity": "🟡 Intermediate",
+    },
+    "wappa_full_example": {
+        "name": "Full-Featured Bot",
+        "description": "Complete WhatsApp bot with all features and deployment configs",
+        "features": [
+            "All message types",
+            "Media handling",
+            "Interactive components",
+            "Docker deployment",
+        ],
+        "complexity": "🔴 Advanced",
+    },
+}
+
+
+def _get_template_content(template_name: str) -> str:
+    """
+    Load template content from the templates directory.
+
+    Args:
+        template_name: Name of the template file (e.g., 'main.py.template')
+
+    Returns:
+        Template content as string
+    """
+    template_dir = Path(__file__).parent / "templates"
+    template_path = template_dir / template_name
+
+    if not template_path.exists():
+        typer.echo(f"❌ Template not found: {template_name}", err=True)
+        raise typer.Exit(1)
+
+    return template_path.read_text()
+
+
+def _initialize_project(directory: str) -> None:
+    """
+    Initialize a new Wappa project in the specified directory.
+
+    Args:
+        directory: Target directory for project initialization
+    """
+    project_path = Path(directory).resolve()
+
+    # Check if directory exists, create if it doesn't
+    if directory != "." and not project_path.exists():
+        try:
+            project_path.mkdir(parents=True, exist_ok=True)
+            typer.echo(f"📁 Created directory: {project_path}")
+        except Exception as e:
+            typer.echo(f"❌ Failed to create directory {project_path}: {e}", err=True)
+            raise typer.Exit(1)
+
+    # Check if directory is empty (except for hidden files and common files like pyproject.toml)
+    existing_files = [
+        f
+        for f in project_path.iterdir()
+        if not f.name.startswith(".")
+        and f.name not in ["pyproject.toml", "uv.lock", "README.md"]
+    ]
+
+    if existing_files:
+        typer.echo(f"⚠️  Directory {project_path} is not empty:", err=True)
+        typer.echo(f"   Found: {[f.name for f in existing_files]}", err=True)
+
+        if not typer.confirm("Continue anyway?"):
+            typer.echo("❌ Project initialization cancelled")
+            raise typer.Exit(1)
+
+    typer.echo(f"🚀 Initializing Wappa project in: {project_path}")
+
+    try:
+        # Create directory structure
+        (project_path / "app").mkdir(exist_ok=True)
+        (project_path / "scores").mkdir(exist_ok=True)
+
+        typer.echo("📁 Created directory structure")
+
+        # Create files from templates
+        templates_to_create = {
+            "app/__init__.py": "__init__.py.template",
+            "app/main.py": "main.py.template",
+            "app/master_event.py": "master_event.py.template",
+            "scores/__init__.py": "__init__.py.template",
+            ".gitignore": "gitignore.template",
+            ".env": "env.template",
+        }
+
+        for file_path, template_name in templates_to_create.items():
+            full_path = project_path / file_path
+            template_content = _get_template_content(template_name)
+
+            full_path.write_text(template_content)
+            typer.echo(f"📝 Created: {file_path}")
+
+        typer.echo()
+        typer.echo("✅ Wappa project initialized successfully!")
+        typer.echo()
+        typer.echo("📋 Next steps:")
+        typer.echo("1. Add your WhatsApp credentials to .env file")
+        typer.echo("2. Install dependencies: uv sync")
+        typer.echo("3. Start development: uv run wappa dev app/main.py")
+        typer.echo()
+        typer.echo("🔧 Required environment variables (.env file):")
+        typer.echo("   WP_ACCESS_TOKEN=your_access_token")
+        typer.echo("   WP_PHONE_ID=your_phone_id")
+        typer.echo("   WP_BID=your_business_id")
+
+    except Exception as e:
+        typer.echo(f"❌ Failed to initialize project: {e}", err=True)
+        raise typer.Exit(1)
 
 
 def _resolve_module_name(file_path: str) -> tuple[str, Path]:
     """
     Convert a file path to a Python module name and working directory.
-    
+
     Handles both flat and nested project structures:
         main.py -> ("main", Path("."))
         app/main.py -> ("app.main", Path("."))  # Use dotted import from project root
         examples/redis_demo/main.py -> ("examples.redis_demo.main", Path("."))
-    
+
     Returns:
         tuple[str, Path]: (module_name, working_directory)
     """
     # Convert to Path object for better handling
     path = Path(file_path)
-    
+
     # Always use current directory as working dir and create dotted module name
     working_dir = Path(".")
-    
+
     # Convert path to dotted module name (remove .py extension)
     if path.suffix == ".py":
         path = path.with_suffix("")
-    
+
     # Convert path separators to dots for Python import
     module_name = str(path).replace(os.path.sep, ".")
-    
+
     return module_name, working_dir
 
 
@@ -83,7 +235,7 @@ def dev(
         str(port),
     ]
 
-    typer.echo(f"🚀 Starting Wappa development server...")
+    typer.echo("🚀 Starting Wappa development server...")
     typer.echo(f"📡 Import: {working_dir / module_name}:{app_var}.asgi")
     typer.echo(f"🌐 Server: http://{host}:{port}")
     typer.echo(f"📝 Docs: http://{host}:{port}/docs")
@@ -114,7 +266,7 @@ def dev(
 
 
 @app.command()
-def run(
+def prod(
     file_path: str = typer.Argument(
         ..., help="Path to your Python file (e.g., main.py)"
     ),
@@ -131,8 +283,8 @@ def run(
     Run production server (no auto-reload).
 
     Examples:
-        wappa run main.py
-        wappa run main.py --workers 4 --port 8080
+        wappa prod main.py
+        wappa prod main.py --workers 4 --port 8080
     """
     # Validate file exists
     if not Path(file_path).exists():
@@ -157,7 +309,7 @@ def run(
         str(workers),
     ]
 
-    typer.echo(f"🚀 Starting Wappa production server...")
+    typer.echo("🚀 Starting Wappa production server...")
     typer.echo(f"📡 Import: {working_dir / module_name}:{app_var}.asgi")
     typer.echo(f"🌐 Server: http://{host}:{port}")
     typer.echo(f"👥 Workers: {workers}")
@@ -183,23 +335,195 @@ def run(
 
 @app.command()
 def init(
-    project_name: str = typer.Argument(..., help="Project name"),
-    template: str = typer.Option(
-        "basic", "--template", "-t", help="Project template (basic, redis)"
+    directory: str = typer.Argument(
+        ".", help="Directory to initialize (default: current directory)"
     ),
 ):
     """
-    Initialize a new Wappa project (coming soon).
+    Initialize a new Wappa project.
+
+    Creates a basic Wappa project structure with:
+    - app/ directory with main.py and master_event.py
+    - scores/ directory (empty)
+    - .gitignore file
+    - .env template file
 
     Examples:
-        wappa init my-whatsapp-bot
-        wappa init my-bot --template redis
+        wappa init            # Initialize in current directory
+        wappa init my-bot     # Initialize in ./my-bot/ directory
     """
-    typer.echo("🚧 Project initialization coming soon!")
-    typer.echo(f"Project: {project_name}")
-    typer.echo(f"Template: {template}")
-    typer.echo()
-    typer.echo("For now, check out the examples directory for project templates.")
+    _initialize_project(directory)
+
+
+@app.command()
+def examples(
+    directory: str = typer.Argument(
+        ".", help="Directory to copy example to (default: current directory)"
+    ),
+):
+    """
+    Browse and copy Wappa example projects.
+
+    Interactive menu to select from various example projects:
+    - Basic project template
+    - Echo bot example
+    - JSON cache demo
+    - Redis cache demo
+    - OpenAI transcription
+    - Full-featured bot
+
+    Examples:
+        wappa examples           # Show examples menu
+        wappa examples my-bot    # Copy to ./my-bot/ directory
+    """
+    _show_examples_menu(directory)
+
+
+def _show_examples_menu(target_directory: str) -> None:
+    """
+    Display interactive examples menu and handle selection.
+
+    Args:
+        target_directory: Directory to copy the selected example to
+    """
+    console.print("\n🚀 [bold blue]Wappa Example Projects[/bold blue]")
+    console.print("Choose an example to copy to your project:\n")
+
+    # Create examples table
+    table = Table(show_header=True, header_style="bold cyan")
+    table.add_column("#", style="dim", width=3)
+    table.add_column("Name", style="bold")
+    table.add_column("Description", style="white")
+    table.add_column("Complexity", style="green")
+    table.add_column("Key Features", style="yellow")
+
+    example_keys = list(EXAMPLES.keys())
+    for i, (key, example) in enumerate(EXAMPLES.items(), 1):
+        features_text = ", ".join(example["features"][:3])  # Show first 3 features
+        if len(example["features"]) > 3:
+            features_text += "..."
+
+        table.add_row(
+            str(i),
+            example["name"],
+            example["description"],
+            example["complexity"],
+            features_text,
+        )
+
+    console.print(table)
+    console.print("\n")
+
+    # Get user selection
+    while True:
+        try:
+            choice = typer.prompt("Enter your choice (1-6) or 'q' to quit")
+
+            if choice.lower() == "q":
+                console.print("👋 Goodbye!")
+                raise typer.Exit(0)
+
+            choice_num = int(choice)
+            if 1 <= choice_num <= len(example_keys):
+                selected_key = example_keys[choice_num - 1]
+                selected_example = EXAMPLES[selected_key]
+
+                console.print(f"\n✨ Selected: [bold]{selected_example['name']}[/bold]")
+                console.print(f"📝 Description: {selected_example['description']}")
+                console.print(f"🎯 Features: {', '.join(selected_example['features'])}")
+                console.print(f"📊 Complexity: {selected_example['complexity']}")
+
+                if typer.confirm(f"\nCopy this example to '{target_directory}'?"):
+                    _copy_example(selected_key, target_directory)
+                    break
+                else:
+                    console.print("Selection cancelled. Choose another example:\n")
+                    continue
+
+            else:
+                console.print(
+                    f"❌ Invalid choice. Please enter a number between 1 and {len(example_keys)}"
+                )
+
+        except ValueError:
+            console.print("❌ Invalid input. Please enter a number or 'q' to quit")
+        except KeyboardInterrupt:
+            console.print("\n👋 Goodbye!")
+            raise typer.Exit(0)
+
+
+def _copy_example(example_key: str, target_directory: str) -> None:
+    """
+    Copy selected example to target directory.
+
+    Args:
+        example_key: Key of the example to copy
+        target_directory: Directory to copy to
+    """
+    examples_dir = Path(__file__).parent / "examples"
+    source_path = examples_dir / example_key
+    target_path = Path(target_directory).resolve()
+
+    if not source_path.exists():
+        console.print(f"❌ Example '{example_key}' not found in {examples_dir}")
+        raise typer.Exit(1)
+
+    try:
+        # Create target directory if it doesn't exist
+        if target_directory != "." and not target_path.exists():
+            target_path.mkdir(parents=True, exist_ok=True)
+            console.print(f"📁 Created directory: {target_path}")
+
+        # Check if target directory is empty (except for standard files)
+        if target_path.exists():
+            existing_files = [
+                f
+                for f in target_path.iterdir()
+                if not f.name.startswith(".")
+                and f.name not in ["pyproject.toml", "uv.lock", "README.md"]
+            ]
+
+            if existing_files:
+                console.print(f"⚠️  Directory {target_path} is not empty:")
+                console.print(f"   Found: {[f.name for f in existing_files]}")
+
+                if not typer.confirm("Continue anyway?"):
+                    console.print("❌ Example copy cancelled")
+                    raise typer.Exit(0)
+
+        console.print(f"🚀 Copying {EXAMPLES[example_key]['name']} to {target_path}")
+
+        # Copy all files from the example
+        for item in source_path.iterdir():
+            if item.is_file():
+                shutil.copy2(item, target_path / item.name)
+                console.print(f"📝 Copied: {item.name}")
+            elif item.is_dir():
+                shutil.copytree(item, target_path / item.name, dirs_exist_ok=True)
+                console.print(f"📁 Copied: {item.name}/")
+
+        console.print("\n✅ Example copied successfully!")
+        console.print("\n📋 Next steps:")
+        console.print("1. Navigate to the project directory")
+        console.print("2. Install dependencies: uv sync")
+        console.print("3. Add your WhatsApp credentials to .env file (if not present)")
+        console.print("4. Start development: uv run wappa dev app/main.py")
+
+        # Show example-specific instructions
+        if example_key == "redis_cache_example":
+            console.print("\n🔧 Redis-specific setup:")
+            console.print("   - Install and start Redis server")
+            console.print("   - Add REDIS_URL to .env file")
+        elif example_key == "openai_transcript":
+            console.print("\n🔧 OpenAI-specific setup:")
+            console.print("   - Add OPENAI_API_KEY to .env file")
+            console.print("   - Ensure audio file handling is configured")
+
+        console.print("\n📖 Check the README.md for detailed setup instructions")
+
+    except Exception as e:
+        console.print(f"❌ Failed to copy example: {e}")
+        raise typer.Exit(1)
 
 
 if __name__ == "__main__":

wappa/cli/templates/env.template

@@ -0,0 +1,37 @@
+# WhatsApp Business API Configuration
+
+# General Configuration
+PORT=8000
+TIME_ZONE=America/Bogota
+
+# DEBUG or INFO or WARNING or ERROR or CRITICAL
+LOG_LEVEL=INFO
+LOG_DIR=./logs
+
+## Environment DEV or PROD
+ENVIRONMENT=DEV  
+
+# WhatsApp Graph API
+BASE_URL=https://graph.facebook.com/
+API_VERSION=v23.0
+
+# Get these values from your WhatsApp Business API setup
+
+# WhatsApp Access Token (required)
+WP_ACCESS_TOKEN=
+
+# WhatsApp Phone Number ID (required) 
+WP_PHONE_ID=
+
+# WhatsApp Business ID (required)
+WP_BID=
+
+# Webhook Configuration
+WHATSAPP_WEBHOOK_VERIFY_TOKEN=
+
+# Redis Configuration (Optional - uncomment to enable Redis persistence)
+REDIS_URL=redis://localhost:6379/
+REDIS_MAX_CONNECTIONS=64
+
+# Optional: AI Tools
+OPENAI_API_KEY=

wappa/cli/templates/gitignore.template

@@ -0,0 +1,165 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be added to the global gitignore or merged into this project gitignore.  For a PyCharm
+#  project, it is recommended to exclude everything except .idea/modules.xml and
+#  .idea/*.iml files. A  simple way to do this is with the IDEA_IGNORE=1 environment variable.
+.idea/
+
+# Wappa-specific
+logs/
+cache/
+*.log

wappa/cli/templates/main.py.template

@@ -0,0 +1,8 @@
+from wappa import Wappa
+from .master_event import MasterEventHandler
+
+app = Wappa()
+app.set_event_handler(MasterEventHandler())
+
+if __name__ == "__main__":
+    app.run()

wappa/cli/templates/master_event.py.template

@@ -0,0 +1,8 @@
+from wappa import WappaEventHandler
+from wappa.webhooks import IncomingMessageWebhook
+
+class MasterEventHandler(WappaEventHandler):
+    
+    async def process_message(self, webhook: IncomingMessageWebhook):
+        await self.messenger.mark_as_read(webhook.message.message_id, webhook.user.user_id)
+        await self.messenger.send_text("Wappa App ready", webhook.user.user_id)