django-cfg 1.3.13__py3-none-any.whl → 1.4.3__py3-none-any.whl

django_cfg/modules/django_rpc_old/TESTING.md

@@ -0,0 +1,358 @@
+# Django RPC Module - Testing Summary
+
+**Status:** ✅ All Tests Passing (44/44)
+**Coverage:** Models + Client + Integration
+**Compliance:** Fully aligned with django-cfg TESTING.md standards
+
+---
+
+## Test Summary
+
+| Category | Tests | Status | Location |
+|----------|-------|--------|----------|
+| **Pydantic Models** | 26 | ✅ PASS | `tests/websocket/test_models.py` |
+| **RPC Client** | 18 | ✅ PASS | `tests/websocket/test_client.py` |
+| **Total** | **44** | **✅ PASS** | |
+
+---
+
+## Running Tests
+
+### Quick Start
+
+```bash
+# From django-cfg root directory
+cd libs/django_cfg
+
+# Run all WebSocket RPC tests
+PYTHONPATH=src:$PYTHONPATH pytest src/django_cfg/tests/websocket/ -v
+
+# Run with concise output
+PYTHONPATH=src:$PYTHONPATH pytest src/django_cfg/tests/websocket/ -q
+
+# Run specific test file
+PYTHONPATH=src:$PYTHONPATH pytest src/django_cfg/tests/websocket/test_models.py -v
+
+# Run specific test class
+PYTHONPATH=src:$PYTHONPATH pytest src/django_cfg/tests/websocket/test_models.py::TestNotificationModels -v
+
+# Run specific test
+PYTHONPATH=src:$PYTHONPATH pytest src/django_cfg/tests/websocket/test_models.py::TestNotificationModels::test_notification_request_valid -v
+```
+
+### Using Test Markers
+
+Tests are organized with pytest markers for selective execution:
+
+```bash
+# Run only unit tests
+PYTHONPATH=src:$PYTHONPATH pytest src/django_cfg/tests/websocket/ -m "unit"
+
+# Run only model tests
+PYTHONPATH=src:$PYTHONPATH pytest src/django_cfg/tests/websocket/ -m "models"
+
+# Run only client tests
+PYTHONPATH=src:$PYTHONPATH pytest src/django_cfg/tests/websocket/ -m "client"
+```
+
+---
+
+## Compliance with Django-CFG Testing Standards
+
+### ✅ Test Framework Choice
+
+**Why pytest (not Django TestCase)?**
+
+According to `TESTING.md`, Django TestCase should be used for:
+- Django ORM model tests
+- Database operations
+- Django-specific features
+
+**Our implementation uses pytest because:**
+- ✅ Testing Pydantic 2 models (NOT Django ORM)
+- ✅ No database operations
+- ✅ Mocked external services (Redis)
+- ✅ Pure unit testing of synchronous logic
+
+This aligns with TESTING.md section "When NOT to Use Django TestCase".
+
+### ✅ Test Organization
+
+Our test structure follows django-cfg standards:
+
+```
+modules/django_rpc/
+├── tests/                      # ✅ Co-located with module
+│   ├── __init__.py
+│   ├── conftest.py            # ✅ Shared fixtures
+│   ├── test_models.py         # ✅ Unit tests for models
+│   └── test_client.py         # ✅ Unit tests for client
+├── client.py
+├── config.py
+└── ...
+```
+
+Matches TESTING.md pattern:
+```
+modules/{module_name}/
+  tests/              # ✅ Unit tests co-located with module
+    conftest.py
+    test_*.py
+```
+
+### ✅ Mocking External Services
+
+Following TESTING.md best practices:
+
+```python
+# ✅ GOOD: Mock Redis (external service)
+@pytest.fixture
+def mock_redis():
+    with patch("redis.ConnectionPool"):
+        with patch("redis.Redis") as mock_redis_class:
+            mock_redis_instance = MagicMock()
+            mock_redis_instance.ping.return_value = True
+            yield mock_redis_instance
+```
+
+### ✅ Test Isolation
+
+Each test is properly isolated:
+
+```python
+@pytest.fixture
+def rpc_client(mock_redis):
+    """Fresh client instance for each test."""
+    client = WebSocketRPCClient(...)
+    client._redis = mock_redis
+    return client
+```
+
+### ✅ Test Speed
+
+Performance meets django-cfg expectations:
+
+| Metric | Expected | Actual | Status |
+|--------|----------|--------|--------|
+| Single unit test | < 0.1s | ~0.01s | ✅ |
+| Full test suite | < 1s | ~0.5s | ✅ |
+
+### ✅ Test Markers
+
+Tests use custom markers for organization:
+
+```python
+@pytest.mark.unit
+@pytest.mark.models
+class TestNotificationModels:
+    """Tests for notification models."""
+```
+
+Markers defined in `conftest.py`:
+- `unit` - Unit tests for individual components
+- `models` - Tests for Pydantic models
+- `client` - Tests for RPC client
+
+---
+
+## Test Coverage Breakdown
+
+### Model Tests (26 tests)
+
+**`test_models.py`** - Comprehensive Pydantic model validation
+
+- **BaseModels** (6 tests)
+  - ✅ BaseRPCMessage creation
+  - ✅ Correlation ID handling
+  - ✅ Request validation
+  - ✅ Invalid method rejection
+  - ✅ Response success/error states
+
+- **RPC Models** (4 tests)
+  - ✅ Generic typed requests
+  - ✅ Generic typed responses
+  - ✅ EchoParams validation
+
+- **Notification Models** (6 tests)
+  - ✅ Valid notification requests
+  - ✅ Invalid data key rejection
+  - ✅ Expiration validation
+  - ✅ Batch notification creation
+  - ✅ Duplicate user ID rejection
+  - ✅ Batch response totals validation
+
+- **Broadcast Models** (3 tests)
+  - ✅ Broadcast to all users
+  - ✅ Room ID requirement for ROOM target
+  - ✅ Room ID rejection for non-ROOM targets
+
+- **Error Models** (3 tests)
+  - ✅ Basic error creation
+  - ✅ Retryable errors
+  - ✅ Validation errors with field details
+
+- **Connection Models** (4 tests)
+  - ✅ ConnectionInfo creation
+  - ✅ Activity status checking
+  - ✅ Activity updates
+  - ✅ State update validation
+
+### Client Tests (18 tests)
+
+**`test_client.py`** - RPC client functionality with mocked Redis
+
+- **Initialization** (3 tests)
+  - ✅ Successful client init
+  - ✅ Connection error handling
+  - ✅ Custom settings
+
+- **RPC Call** (4 tests)
+  - ✅ Successful RPC call
+  - ✅ Timeout handling
+  - ✅ Remote error handling
+  - ✅ Custom timeout override
+
+- **Fire-and-Forget** (1 test)
+  - ✅ Send without waiting for response
+
+- **Broadcast** (1 test)
+  - ✅ Pub/Sub broadcast
+
+- **Health Check** (3 tests)
+  - ✅ Successful health check
+  - ✅ Ping failure handling
+  - ✅ Exception handling
+
+- **Connection Info** (1 test)
+  - ✅ Get connection details
+
+- **Context Manager** (1 test)
+  - ✅ Proper resource cleanup
+
+- **Singleton** (2 tests)
+  - ✅ Singleton creation
+  - ✅ Force new instance
+
+- **Cleanup** (2 tests)
+  - ✅ Pool disconnection
+  - ✅ Cleanup on error
+
+---
+
+## Example Test Output
+
+```bash
+$ PYTHONPATH=src:$PYTHONPATH pytest src/django_cfg/tests/websocket/ -v
+
+======================== test session starts =========================
+platform darwin -- Python 3.10.18, pytest-8.4.1
+
+collected 44 items
+
+test_client.py::TestWebSocketRPCClientInit::test_client_init_success PASSED
+test_client.py::TestRPCClientCall::test_call_success PASSED
+test_client.py::TestRPCClientCall::test_call_timeout PASSED
+...
+test_models.py::TestNotificationModels::test_notification_request_valid PASSED
+test_models.py::TestBroadcastModels::test_broadcast_request_all PASSED
+test_models.py::TestErrorModels::test_rpc_error_basic PASSED
+...
+
+====================== 44 passed in 0.45s ========================
+```
+
+---
+
+## Future Testing Enhancements
+
+### Integration Tests
+
+Consider adding integration tests in `tests/integration/`:
+
+```python
+# tests/integration/test_rpc_with_django.py
+from django.test import TestCase
+from django_cfg.modules.django_rpc import get_rpc_client
+
+class RPCIntegrationTestCase(TestCase):
+    """Integration tests with Django views/models."""
+
+    def test_rpc_from_django_view(self):
+        """Test RPC call from actual Django view."""
+        # Test with real Django request/response
+        pass
+```
+
+### End-to-End Tests
+
+For complete flow testing:
+
+```python
+# tests/e2e/test_websocket_flow.py
+class WebSocketE2ETestCase(TestCase):
+    """E2E tests with real Redis and WebSocket server."""
+
+    @pytest.mark.slow
+    def test_complete_notification_flow(self):
+        """Test complete flow: Django → Redis → WebSocket → User"""
+        # Requires running Redis and WebSocket server
+        pass
+```
+
+---
+
+## Common Issues and Solutions
+
+### Issue: `ModuleNotFoundError: No module named 'django_cfg'`
+
+**Solution:** Set PYTHONPATH when running tests:
+
+```bash
+PYTHONPATH=src:$PYTHONPATH pytest src/django_cfg/tests/websocket/
+```
+
+### Issue: Redis connection errors
+
+**Solution:** Tests use mocked Redis - no real Redis required!
+
+All external dependencies (Redis, WebSocket servers) are mocked for unit tests.
+
+---
+
+## Test Development Guidelines
+
+When adding new tests:
+
+1. **Follow naming convention**: `test_*.py`
+2. **Use descriptive test names**: `test_notification_request_valid`
+3. **Add proper markers**: `@pytest.mark.unit`, `@pytest.mark.models`
+4. **Mock external services**: Never hit real Redis/APIs
+5. **Keep tests fast**: < 0.1s per test
+6. **Document test purpose**: Clear docstrings
+
+Example:
+
+```python
+@pytest.mark.unit
+@pytest.mark.models
+class TestMyNewModel:
+    """Tests for MyNewModel Pydantic validation."""
+
+    def test_valid_creation(self):
+        """Test model can be created with valid data."""
+        model = MyNewModel(field="value")
+        assert model.field == "value"
+
+    def test_invalid_field_rejection(self):
+        """Test model rejects invalid field values."""
+        with pytest.raises(ValidationError):
+            MyNewModel(field="")  # Empty not allowed
+```
+
+---
+
+**Last Updated:** 2025-10-03
+**Maintainer:** Django-CFG Team
+**Status:** ✅ Production Ready
+
+For questions about testing, see main [TESTING.md](../../TESTING.md)

django_cfg/modules/django_rpc_old/__init__.py

@@ -0,0 +1,39 @@
+"""
+Django RPC Module for WebSocket Communication.
+
+Provides synchronous RPC client for Django applications to communicate
+with external WebSocket servers via Redis.
+
+Example:
+    >>> from django_cfg.modules.django_rpc import get_rpc_client
+    >>> from django_cfg.models.websocket import NotificationRequest, NotificationResponse
+    >>>
+    >>> rpc = get_rpc_client()
+    >>> result: NotificationResponse = rpc.call(
+    ...     method="send_notification",
+    ...     params=NotificationRequest(user_id="123", message="Hello"),
+    ...     result_model=NotificationResponse
+    ... )
+"""
+
+from .client import WebSocketRPCClient, get_rpc_client
+from .config import WebSocketRPCConfig
+from .exceptions import (
+    RPCTimeoutError,
+    RPCRemoteError,
+    RPCConnectionError,
+    RPCConfigurationError,
+)
+
+__all__ = [
+    # Client
+    "WebSocketRPCClient",
+    "get_rpc_client",
+    # Configuration
+    "WebSocketRPCConfig",
+    # Exceptions
+    "RPCTimeoutError",
+    "RPCRemoteError",
+    "RPCConnectionError",
+    "RPCConfigurationError",
+]