feat(service): support backend-based message generation with context formatting

Author: CuriousLearner

CHANGELOG.rst

@@ -1,6 +1,19 @@
 Release Notes
 -------------
 
+[3.1.0]
+^^^^^^^
+
+Added
+"""""
+- Allow custom backends to override `generate_message(security_code, context=None)` for dynamic message generation at runtime.
+- `context` parameter support added to `send_verification()` for passing additional formatting data dynamically.
+
+Changed
+"""""""
+- `PhoneVerificationService` now delegates message generation to the backend if `generate_message()` is implemented.
+- Moved `phone_settings` inside `__init__` for better error handling when `PHONE_VERIFICATION` is missing from settings.
+
 [3.0.1]
 ^^^^^^^
 

docs/customization.rst

@@ -71,6 +71,15 @@ Step 3: Implement the Backend Class
                 'text': message,
             })
 
+        def generate_message(self, security_code, context=None):
+            """You can optionally override the message formatting by
+            defining a `generate_message()` method in your backend.
+            This method receives the `security_code` and an optional
+            `context` dictionary passed at runtime, giving you more
+            flexibility than using a static `MESSAGE` template."""
+            username = context.get("username", "User") if context else "User"
+            return f"Hi {username}, your OTP is {security_code}."
+
         def send_bulk_sms(self, numbers, message):
             for number in numbers:
                 self.send_sms(number, message)
@@ -107,6 +116,9 @@ Step 1: Implement the Sandbox Backend
                 'text': message,
             })
 
+        def generate_message(self, security_code, context=None):
+            return f"[SANDBOX] Your code is {security_code}"
+
         def send_bulk_sms(self, numbers, message):
             for number in numbers:
                 self.send_sms(number, message)

phone_verify/backends/base.py

@@ -148,3 +148,16 @@ def validate_security_code(self, security_code, phone_number, session_token):
         stored_verification.save()
 
         return stored_verification, self.SECURITY_CODE_VALID
+
+    def generate_message(self, security_code, context=None):
+        """
+        Optionally override this method to customize the verification message.
+
+        If this method returns None, the PhoneVerificationService will fall back
+        to the default message defined in settings.
+
+        :param security_code: The generated verification code.
+        :param context: Optional dictionary with runtime values.
+        :return: A string message or None to trigger fallback.
+        """
+        return None

phone_verify/services.py

@@ -20,33 +20,47 @@
 
 
 class PhoneVerificationService(object):
-    try:
-        phone_settings = settings.PHONE_VERIFICATION
-    except AttributeError as e:
-        raise ImproperlyConfigured("Please define PHONE_VERIFICATION in settings") from e
-
-    verification_message = phone_settings.get("MESSAGE", DEFAULT_MESSAGE)
 
     def __init__(self, phone_number, backend=None):
+        try:
+            self.phone_settings = settings.PHONE_VERIFICATION
+        except AttributeError as e:
+            raise ImproperlyConfigured("Please define PHONE_VERIFICATION in settings") from e
         self._check_required_settings()
         if backend is None:
             self.backend = get_sms_backend(phone_number=phone_number)
+        else:
+            self.backend = backend
 
-    def send_verification(self, number, security_code):
+        self.verification_message = self.phone_settings.get("MESSAGE", DEFAULT_MESSAGE)
+
+    def send_verification(self, number, security_code, context=None):
         """
         Send a verification text to the given number to verify.
 
         :param number: the phone number of recipient.
+        :param security_code: generated code to verify
+        :param context: optional dictionary for custom message formatting
         """
-        message = self._generate_message(security_code)
-
+        message = self._generate_message(security_code, context)
         self.backend.send_sms(number, message)
 
-    def _generate_message(self, security_code):
-        return self.verification_message.format(
-            app=settings.PHONE_VERIFICATION.get("APP_NAME", DEFAULT_APP_NAME),
-            security_code=security_code,
-        )
+    def _generate_message(self, security_code, context=None):
+        # If the backend has its own message generator, prefer it
+        if hasattr(self.backend, "generate_message") and callable(self.backend.generate_message):
+            message = self.backend.generate_message(security_code, context=context)
+            if message:
+                return message
+
+        # Default fallback
+        format_context = {
+            "app": settings.PHONE_VERIFICATION.get("APP_NAME", DEFAULT_APP_NAME),
+            "security_code": security_code,
+        }
+        if context:
+            format_context.update(context)
+
+        return self.verification_message.format(**format_context)
 
     def _check_required_settings(self):
         required_settings = {

tests/test_services.py

@@ -82,3 +82,52 @@ def test_exception_is_raised_when_no_settings(client, backend):
             importlib.reload(phone_verify.services)
             PhoneVerificationService(phone_number="+13478379634")
             assert exc.info == "Please define PHONE_VERIFICATION in settings"
+
+
+class DummyBackend:
+    def __init__(self):
+        self.sent_messages = []
+
+    def send_sms(self, number, message):
+        self.sent_messages.append((number, message))
+
+
+class CustomBackendWithMessage(DummyBackend):
+    def generate_message(self, security_code, context=None):
+        return f"Custom: {security_code} / {context.get('extra', '')}"
+
+
+@pytest.mark.django_db
+def test_generate_message_default_fallback(settings):
+    settings.PHONE_VERIFICATION = {
+        'BACKEND': 'tests.test_services.DummyBackend',
+        'OPTIONS': {},
+        'TOKEN_LENGTH': 6,
+        'MESSAGE': 'Code: {security_code} from {app}, note: {extra}',
+        'APP_NAME': 'TestApp',
+        'SECURITY_CODE_EXPIRATION_TIME': 300,
+        'VERIFY_SECURITY_CODE_ONLY_ONCE': True,
+    }
+
+    svc = PhoneVerificationService(phone_number="+1234567890", backend=DummyBackend())
+    msg = svc._generate_message("123456", context={"extra": "extra-info"})
+
+    assert msg == "Code: 123456 from TestApp, note: extra-info"
+
+
+@pytest.mark.django_db
+def test_generate_message_from_custom_backend(settings):
+    settings.PHONE_VERIFICATION = {
+        'BACKEND': 'tests.test_services.CustomBackendWithMessage',
+        'OPTIONS': {},
+        'TOKEN_LENGTH': 6,
+        'MESSAGE': 'SHOULD NOT BE USED',
+        'APP_NAME': 'TestApp',
+        'SECURITY_CODE_EXPIRATION_TIME': 300,
+        'VERIFY_SECURITY_CODE_ONLY_ONCE': True,
+    }
+
+    svc = PhoneVerificationService(phone_number="+1234567890", backend=CustomBackendWithMessage())
+    msg = svc._generate_message("999999", context={"extra": "runtime"})
+
+    assert msg == "Custom: 999999 / runtime"