django-cfg 1.5.20__py3-none-any.whl → 1.5.31__py3-none-any.whl

django_cfg/apps/integrations/grpc/services/commands/examples/client.py

@@ -0,0 +1,272 @@
+"""
+Example: Wrapper Client Class
+
+This demonstrates Pattern 3: wrapping command functions in a convenient client class.
+
+The wrapper pattern provides:
+- Clean API: client.start() instead of start_client(client, ...)
+- Encapsulation: Commands bundled with client state
+- Convenience: Methods can access self.model, self.client_id automatically
+
+Usage:
+    from your_app.grpc.commands.client import CommandClient
+
+    # Create client
+    client = CommandClient(client_id="123", model=instance, grpc_port=50051)
+
+    # Use convenient methods
+    await client.start(reason="User request")
+    await client.update_config()
+    await client.stop(graceful=True)
+"""
+
+import logging
+from typing import Optional, List, Any
+
+from django_cfg.apps.integrations.grpc.services.commands.examples.base_client import (
+    ExampleCommandClient,
+)
+
+# Import command functions
+from . import start, stop, config
+
+logger = logging.getLogger(__name__)
+
+
+class CommandClient(ExampleCommandClient):
+    """
+    Wrapper client class that provides convenient methods for all commands.
+
+    This wraps the command functions (start.py, stop.py, config.py) into
+    class methods for a cleaner API.
+
+    Example:
+        # Cross-process mode (from REST API, signals, tasks)
+        from your_app.grpc.commands.client import CommandClient
+
+        client = CommandClient(
+            client_id="bot-123",
+            model=bot_instance,
+            grpc_port=50051
+        )
+        await client.start(reason="API request")
+
+        # Same-process mode (from management commands)
+        from your_app.grpc.services.commands.registry import get_streaming_service
+
+        service = get_streaming_service("bots")
+        client = CommandClient(
+            client_id="bot-123",
+            model=bot_instance,
+            streaming_service=service
+        )
+        await client.start()  # Much faster (same-process)
+    """
+
+    async def start(self, reason: Optional[str] = None) -> bool:
+        """
+        Start the client.
+
+        Args:
+            reason: Optional reason for starting
+
+        Returns:
+            True if command sent successfully
+
+        Example:
+            success = await client.start(reason="User requested start")
+        """
+        if not self.model:
+            logger.error(f"Cannot start {self.client_id}: model not provided")
+            return False
+
+        return await start.start_client(
+            client=self,
+            model=self.model,
+            reason=reason
+        )
+
+    async def stop(
+        self,
+        reason: Optional[str] = None,
+        graceful: bool = True
+    ) -> bool:
+        """
+        Stop the client.
+
+        Args:
+            reason: Optional reason for stopping
+            graceful: If True, allow client to finish current work
+
+        Returns:
+            True if command sent successfully
+
+        Example:
+            # Graceful stop
+            success = await client.stop(reason="Maintenance", graceful=True)
+
+            # Force stop
+            success = await client.stop(reason="Emergency", graceful=False)
+        """
+        if not self.model:
+            logger.error(f"Cannot stop {self.client_id}: model not provided")
+            return False
+
+        return await stop.stop_client(
+            client=self,
+            model=self.model,
+            reason=reason,
+            graceful=graceful
+        )
+
+    async def update_config(self, fields: Optional[List[str]] = None) -> bool:
+        """
+        Push config update to client.
+
+        Args:
+            fields: If specified, only update these fields (partial update)
+
+        Returns:
+            True if command sent successfully
+
+        Example:
+            # Full config update
+            success = await client.update_config()
+
+            # Partial update
+            success = await client.update_config(fields=['timeout', 'max_retries'])
+        """
+        if not self.model:
+            logger.error(f"Cannot update config for {self.client_id}: model not provided")
+            return False
+
+        return await config.update_config(
+            client=self,
+            model=self.model,
+            fields=fields
+        )
+
+    async def restart(
+        self,
+        reason: Optional[str] = None,
+        graceful: bool = True
+    ) -> bool:
+        """
+        Restart the client (stop then start).
+
+        Args:
+            reason: Optional reason for restart
+            graceful: If True, allow graceful stop
+
+        Returns:
+            True if both stop and start succeeded
+
+        Example:
+            success = await client.restart(reason="Config changed")
+        """
+        # Stop
+        stop_success = await self.stop(
+            reason=reason or "Restart",
+            graceful=graceful
+        )
+
+        if not stop_success:
+            logger.warning(f"Restart of {self.client_id} failed at stop phase")
+            return False
+
+        # Wait a moment for client to stop
+        import asyncio
+        await asyncio.sleep(1)
+
+        # Start
+        start_success = await self.start(
+            reason=reason or "Restart"
+        )
+
+        if start_success:
+            logger.info(f"✅ Restart of {self.client_id} complete")
+        else:
+            logger.error(f"❌ Restart of {self.client_id} failed at start phase")
+
+        return start_success
+
+
+# ============================================================================
+# Batch Operations
+# ============================================================================
+
+async def batch_start(
+    clients: List[CommandClient],
+    reason: Optional[str] = None
+) -> dict:
+    """
+    Start multiple clients in parallel.
+
+    Args:
+        clients: List of CommandClient instances
+        reason: Optional reason for starting
+
+    Returns:
+        Dict with 'success': count, 'failed': count
+
+    Example:
+        from your_app.grpc.services.commands.registry import get_streaming_service
+
+        service = get_streaming_service("bots")
+        client_ids = ["bot-1", "bot-2", "bot-3"]
+
+        clients = [
+            CommandClient(client_id=cid, model=await Bot.objects.aget(id=cid), streaming_service=service)
+            for cid in client_ids
+        ]
+
+        results = await batch_start(clients, reason="Batch start")
+        print(f"Started {results['success']}/{len(clients)} clients")
+    """
+    import asyncio
+
+    tasks = [client.start(reason=reason) for client in clients]
+    results = await asyncio.gather(*tasks, return_exceptions=True)
+
+    success_count = sum(1 for r in results if r is True)
+    failed_count = len(results) - success_count
+
+    logger.info(f"Batch start: {success_count} succeeded, {failed_count} failed")
+
+    return {'success': success_count, 'failed': failed_count}
+
+
+async def batch_stop(
+    clients: List[CommandClient],
+    reason: Optional[str] = None,
+    graceful: bool = True
+) -> dict:
+    """
+    Stop multiple clients in parallel.
+
+    Args:
+        clients: List of CommandClient instances
+        reason: Optional reason for stopping
+        graceful: If True, allow graceful shutdown
+
+    Returns:
+        Dict with 'success': count, 'failed': count
+    """
+    import asyncio
+
+    tasks = [client.stop(reason=reason, graceful=graceful) for client in clients]
+    results = await asyncio.gather(*tasks, return_exceptions=True)
+
+    success_count = sum(1 for r in results if r is True)
+    failed_count = len(results) - success_count
+
+    logger.info(f"Batch stop: {success_count} succeeded, {failed_count} failed")
+
+    return {'success': success_count, 'failed': failed_count}
+
+
+__all__ = [
+    'CommandClient',
+    'batch_start',
+    'batch_stop',
+]

django_cfg/apps/integrations/grpc/services/commands/examples/config.py

@@ -0,0 +1,177 @@
+"""
+Example: CONFIG UPDATE Command Implementation
+
+Demonstrates pushing configuration updates to connected clients.
+
+Key patterns:
+- JSONField updates (Django models)
+- Partial vs full config updates
+- Signal-triggered automatic config sync
+
+Usage:
+    from your_app.grpc.commands.config import update_config
+
+    # Full config update
+    success = await update_config(client, model=instance)
+
+    # Partial update
+    success = await update_config(client, model=instance, fields=['timeout', 'max_retries'])
+"""
+
+import logging
+from typing import Any, Optional, List
+
+logger = logging.getLogger(__name__)
+
+
+async def update_config(
+    client,  # ExampleCommandClient
+    model,   # HasConfig protocol
+    fields: Optional[List[str]] = None,
+) -> bool:
+    """
+    Send CONFIG_UPDATE command to client.
+
+    Pushes configuration from Django model to connected client.
+    Useful for:
+    - User updates config in admin/API
+    - Django signal automatically pushes to client
+    - Batch config updates across multiple clients
+
+    Args:
+        client: Command client instance
+        model: Django model with config JSONField
+        fields: If specified, only send these config fields (partial update)
+
+    Returns:
+        True if command sent successfully, False otherwise
+
+    Example:
+        # Auto-push on model save (using Django signals)
+        from django.db.models.signals import post_save
+        from django.dispatch import receiver
+        from asgiref.sync import async_to_sync
+
+        @receiver(post_save, sender=YourModel)
+        def on_config_changed(sender, instance, **kwargs):
+            from your_app.grpc.commands.config import update_config
+            from your_app.grpc.commands.base_client import YourCommandClient
+
+            client = YourCommandClient(
+                client_id=str(instance.id),
+                model=instance,
+                grpc_port=50051
+            )
+            async_to_sync(update_config)(client, model=instance)
+
+        # Manual update from API
+        async def update_config_view(request, pk):
+            instance = await YourModel.objects.aget(pk=pk)
+            # ... update instance.config ...
+            await instance.asave(update_fields=['config'])
+
+            client = YourCommandClient(client_id=str(pk), model=instance, grpc_port=50051)
+            success = await update_config(client, model=instance)
+            return JsonResponse({"success": success})
+    """
+    try:
+        # Get config from model
+        config = model.config
+
+        # If fields specified, create partial config
+        if fields:
+            config = {k: v for k, v in config.items() if k in fields}
+            logger.debug(f"Sending partial config update to {client.client_id}: {list(config.keys())}")
+        else:
+            logger.debug(f"Sending full config update to {client.client_id}")
+
+        # Create protobuf command
+        # Example:
+        # command = pb2.Command(
+        #     config_update=pb2.ConfigUpdateCommand(
+        #         config=json.dumps(config),
+        #         partial=fields is not None,
+        #         fields=fields or [],
+        #         timestamp=int(datetime.now().timestamp())
+        #     )
+        # )
+
+        logger.warning(
+            f"Example implementation: Create your CONFIG_UPDATE command protobuf message here."
+        )
+
+        # Send command
+        # success = await client._send_command(command)
+
+        # For this example:
+        # if success:
+        #     logger.info(f"✅ CONFIG_UPDATE sent to {client.client_id}")
+        # else:
+        #     logger.warning(f"⚠️  Client {client.client_id} not connected, config will sync on reconnect")
+
+        # return success
+
+        return False  # Placeholder
+
+    except Exception as e:
+        logger.error(
+            f"❌ Error sending CONFIG_UPDATE to {client.client_id}: {e}",
+            exc_info=True
+        )
+        return False
+
+
+async def batch_update_config(
+    clients: List[Any],  # List[ExampleCommandClient]
+    model: Any,  # HasConfig
+    fields: Optional[List[str]] = None,
+) -> dict:
+    """
+    Send config update to multiple clients.
+
+    Useful for:
+    - Updating config across all connected clients of same type
+    - Rolling out global config changes
+
+    Args:
+        clients: List of command client instances
+        model: Django model with config
+        fields: Optional list of fields for partial update
+
+    Returns:
+        Dict with 'success': count, 'failed': count
+
+    Example:
+        from your_app.grpc.services.commands.registry import get_streaming_service
+
+        # Get all connected clients
+        service = get_streaming_service("your_service")
+        client_ids = list(service.get_active_connections().keys())
+
+        # Create clients
+        clients = [
+            YourCommandClient(client_id=cid, streaming_service=service)
+            for cid in client_ids
+        ]
+
+        # Batch update
+        results = await batch_update_config(clients, global_config_model, fields=['timeout'])
+        print(f"Updated {results['success']} clients, {results['failed']} failed")
+    """
+    results = {'success': 0, 'failed': 0}
+
+    for client in clients:
+        success = await update_config(client, model, fields)
+        if success:
+            results['success'] += 1
+        else:
+            results['failed'] += 1
+
+    logger.info(
+        f"Batch config update complete: {results['success']} succeeded, {results['failed']} failed"
+    )
+
+    return results
+
+
+__all__ = ['update_config', 'batch_update_config']

django_cfg/apps/integrations/grpc/services/commands/examples/start.py

@@ -0,0 +1,125 @@
+"""
+Example: START Command Implementation
+
+This demonstrates the command decomposition pattern where each command
+is implemented as a standalone async function.
+
+Key patterns:
+- Type-safe model operations using Protocol
+- Django async ORM (asave with update_fields)
+- Protobuf command creation
+- Error handling and logging
+
+Usage:
+    from your_app.grpc.commands.start import start_client
+    from your_app.grpc.commands.base_client import YourCommandClient
+
+    # Create client
+    client = YourCommandClient(client_id="123", model=instance)
+
+    # Call command function
+    success = await start_client(client, model=instance, reason="User request")
+"""
+
+import logging
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+async def start_client(
+    client,  # ExampleCommandClient
+    model,   # HasStatus protocol
+    reason: Optional[str] = None,
+) -> bool:
+    """
+    Send START command to client.
+
+    This is a standalone command function that can be:
+    1. Called directly from management commands
+    2. Wrapped in a method on the client class
+    3. Used in REST API views
+    4. Triggered by Django signals
+
+    Args:
+        client: Command client instance
+        model: Django model with status field (HasStatus protocol)
+        reason: Optional reason for starting
+
+    Returns:
+        True if command sent successfully, False otherwise
+
+    Example:
+        # From REST API
+        from your_app.grpc.commands.start import start_client
+        from your_app.grpc.commands.base_client import YourCommandClient
+
+        async def start_view(request, pk):
+            instance = await YourModel.objects.aget(pk=pk)
+            client = YourCommandClient(client_id=str(pk), model=instance, grpc_port=50051)
+            success = await start_client(client, model=instance, reason="API request")
+            return JsonResponse({"success": success})
+
+        # From management command (same-process)
+        from your_app.grpc.services.registry import get_streaming_service
+
+        service = get_streaming_service("your_service")
+        client = YourCommandClient(client_id=str(pk), model=instance, streaming_service=service)
+        success = await start_client(client, model=instance)
+    """
+    try:
+        # Update model status to STARTING
+        model.status = "STARTING"
+        await model.asave(update_fields=['status'])
+        logger.info(f"Updated {client.client_id} status to STARTING")
+
+        # Create protobuf command
+        # IMPORTANT: Replace with your actual protobuf types
+        # Example:
+        # command = pb2.Command(
+        #     start=pb2.StartCommand(
+        #         reason=reason or "Manual start",
+        #         timestamp=int(datetime.now().timestamp())
+        #     )
+        # )
+
+        # For this example, we'll just log a warning
+        logger.warning(
+            f"Example implementation: Create your START command protobuf message here. "
+            f"See trading_bots/grpc/services/commands/start.py for reference."
+        )
+
+        # Send command via client (auto-detects same-process vs cross-process)
+        # success = await client._send_command(command)
+
+        # For this example, return placeholder
+        # if success:
+        #     logger.info(f"✅ START command sent to {client.client_id}")
+        #     # Optionally update status to RUNNING
+        #     model.status = "RUNNING"
+        #     await model.asave(update_fields=['status'])
+        # else:
+        #     logger.warning(f"⚠️  Client {client.client_id} not connected")
+        #     # Revert status
+        #     model.status = "STOPPED"
+        #     await model.asave(update_fields=['status'])
+
+        # return success
+
+        return False  # Placeholder
+
+    except Exception as e:
+        logger.error(
+            f"❌ Error sending START command to {client.client_id}: {e}",
+            exc_info=True
+        )
+        # Revert model status on error
+        try:
+            model.status = "ERROR"
+            await model.asave(update_fields=['status'])
+        except Exception:
+            pass
+        return False
+
+
+__all__ = ['start_client']

django_cfg/apps/integrations/grpc/services/commands/examples/stop.py

@@ -0,0 +1,101 @@
+"""
+Example: STOP Command Implementation
+
+Demonstrates stopping a client with graceful shutdown and status updates.
+
+Key patterns:
+- Status transition (RUNNING → STOPPING → STOPPED)
+- Optional reason tracking
+- Error recovery
+
+Usage:
+    from your_app.grpc.commands.stop import stop_client
+
+    success = await stop_client(client, model=instance, reason="Maintenance")
+"""
+
+import logging
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+async def stop_client(
+    client,  # ExampleCommandClient
+    model,   # HasStatus protocol
+    reason: Optional[str] = None,
+    graceful: bool = True,
+) -> bool:
+    """
+    Send STOP command to client.
+
+    Args:
+        client: Command client instance
+        model: Django model with status field
+        reason: Optional reason for stopping
+        graceful: If True, allow client to finish current work
+
+    Returns:
+        True if command sent successfully, False otherwise
+
+    Example:
+        # Graceful stop
+        success = await stop_client(client, model, reason="Scheduled maintenance", graceful=True)
+
+        # Force stop
+        success = await stop_client(client, model, reason="Emergency", graceful=False)
+    """
+    try:
+        # Update model status
+        current_status = model.status
+        model.status = "STOPPING"
+        await model.asave(update_fields=['status'])
+        logger.info(f"Updated {client.client_id} status to STOPPING")
+
+        # Create protobuf command
+        # Example:
+        # command = pb2.Command(
+        #     stop=pb2.StopCommand(
+        #         reason=reason or "Manual stop",
+        #         graceful=graceful,
+        #         timestamp=int(datetime.now().timestamp())
+        #     )
+        # )
+
+        logger.warning(
+            f"Example implementation: Create your STOP command protobuf message here."
+        )
+
+        # Send command
+        # success = await client._send_command(command)
+
+        # For this example:
+        # if success:
+        #     logger.info(f"✅ STOP command sent to {client.client_id}")
+        #     model.status = "STOPPED"
+        #     await model.asave(update_fields=['status'])
+        # else:
+        #     logger.warning(f"⚠️  Client {client.client_id} not connected")
+        #     # Revert to previous status
+        #     model.status = current_status
+        #     await model.asave(update_fields=['status'])
+
+        # return success
+
+        return False  # Placeholder
+
+    except Exception as e:
+        logger.error(
+            f"❌ Error sending STOP command to {client.client_id}: {e}",
+            exc_info=True
+        )
+        # Handle error
+        try:
+            model.status = "ERROR"
+            await model.asave(update_fields=['status'])
+        except Exception:
+            pass
+        return False
+
+
+__all__ = ['stop_client']