add fids to MulticastMessage and token deprecate warning and add unit tests

Author: yvonnep165

firebase_admin/_messaging_encoder.py

@@ -28,7 +28,7 @@ class Message:
     """A message that can be sent via Firebase Cloud Messaging.
 
     Contains payload information as well as recipient information. In particular, the message must
-    contain exactly one of token, topic or condition fields.
+    contain exactly one of fid, token, topic or condition fields.
 
     Args:
         data: A dictionary of data fields (optional). All keys and values in the dictionary must be
@@ -70,10 +70,11 @@ def __str__(self):
 
 
 class MulticastMessage:
-    """A message that can be sent to multiple tokens via Firebase Cloud Messaging.
+    """A message that can be sent to multiple tokens or fids via Firebase Cloud Messaging.
 
     Args:
-        tokens: A list of registration tokens of targeted devices.
+        fids: A list of Firebase Installation IDs of targeted app instances (optional)
+        tokens: Deprecated. Use ``fids`` instead (optional).
         data: A dictionary of data fields (optional). All keys and values in the dictionary must be
             strings.
         notification: An instance of ``messaging.Notification`` (optional).
@@ -82,12 +83,31 @@ class MulticastMessage:
         apns: An instance of ``messaging.ApnsConfig`` (optional).
         fcm_options: An instance of ``messaging.FCMOptions`` (optional).
     """
-    def __init__(self, tokens, data=None, notification=None, android=None, webpush=None, apns=None,
+    def __init__(self, fids=None, tokens=None, data=None, notification=None, android=None, webpush=None, apns=None,
                  fcm_options=None):
-        _Validators.check_string_list('MulticastMessage.tokens', tokens)
-        if len(tokens) > 500:
-            raise ValueError('MulticastMessage.tokens must not contain more than 500 tokens.')
-        self.tokens = tokens
+        if tokens is not None:
+            warnings.warn(
+                "Deprecated. Use 'fids' instead.",
+                DeprecationWarning,
+                stacklevel=2
+            )
+
+        if (tokens is None and fids is None) or (tokens is not None and fids is not None):
+            raise ValueError("Must specify either 'tokens' or 'fids'.")
+
+        if tokens is not None:
+            _Validators.check_string_list('MulticastMessage.tokens', tokens)
+            if len(tokens) > 500:
+                raise ValueError('MulticastMessage.tokens must not contain more than 500 tokens.')
+            self.tokens = tokens
+            self.fids = None
+        else:
+            _Validators.check_string_list('MulticastMessage.fids', fids)
+            if len(fids) > 500:
+                raise ValueError('MulticastMessage.fids must not contain more than 500 fids.')
+            self.fids = fids
+            self.tokens = None
+
         self.data = data
         self.notification = notification
         self.android = android

firebase_admin/messaging.py

@@ -20,6 +20,7 @@
 import json
 import asyncio
 import logging
+import warnings
 import requests
 import httpx
 
@@ -177,7 +178,7 @@ async def send_each_for_multicast_async(
         dry_run: bool = False,
         app: Optional[App] = None
     ) -> BatchResponse:
-    """Sends the given mutlicast message to each token asynchronously via Firebase Cloud Messaging
+    """Sends the given multicast message to each token or fid asynchronously via Firebase Cloud Messaging
     (FCM).
 
     If the ``dry_run`` mode is enabled, the message will not be actually delivered to the
@@ -197,19 +198,32 @@ async def send_each_for_multicast_async(
     """
     if not isinstance(multicast_message, MulticastMessage):
         raise ValueError('Message must be an instance of messaging.MulticastMessage class.')
-    messages = [Message(
-        data=multicast_message.data,
-        notification=multicast_message.notification,
-        android=multicast_message.android,
-        webpush=multicast_message.webpush,
-        apns=multicast_message.apns,
-        fcm_options=multicast_message.fcm_options,
-        token=token
-    ) for token in multicast_message.tokens]
+    if multicast_message.tokens is not None:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            messages = [Message(
+                data=multicast_message.data,
+                notification=multicast_message.notification,
+                android=multicast_message.android,
+                webpush=multicast_message.webpush,
+                apns=multicast_message.apns,
+                fcm_options=multicast_message.fcm_options,
+                token=token
+            ) for token in multicast_message.tokens]
+    else:
+        messages = [Message(
+            data=multicast_message.data,
+            notification=multicast_message.notification,
+            android=multicast_message.android,
+            webpush=multicast_message.webpush,
+            apns=multicast_message.apns,
+            fcm_options=multicast_message.fcm_options,
+            fid=fid
+        ) for fid in multicast_message.fids]
     return await _get_messaging_service(app).send_each_async(messages, dry_run)
 
 def send_each_for_multicast(multicast_message, dry_run=False, app=None):
-    """Sends the given mutlicast message to each token via Firebase Cloud Messaging (FCM).
+    """Sends the given multicast message to each token or fid via Firebase Cloud Messaging (FCM).
 
     If the ``dry_run`` mode is enabled, the message will not be actually delivered to the
     recipients. Instead, FCM performs all the usual validations and emulates the send operation.
@@ -228,15 +242,28 @@ def send_each_for_multicast(multicast_message, dry_run=False, app=None):
     """
     if not isinstance(multicast_message, MulticastMessage):
         raise ValueError('Message must be an instance of messaging.MulticastMessage class.')
-    messages = [Message(
-        data=multicast_message.data,
-        notification=multicast_message.notification,
-        android=multicast_message.android,
-        webpush=multicast_message.webpush,
-        apns=multicast_message.apns,
-        fcm_options=multicast_message.fcm_options,
-        token=token
-    ) for token in multicast_message.tokens]
+    if multicast_message.tokens is not None:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            messages = [Message(
+                data=multicast_message.data,
+                notification=multicast_message.notification,
+                android=multicast_message.android,
+                webpush=multicast_message.webpush,
+                apns=multicast_message.apns,
+                fcm_options=multicast_message.fcm_options,
+                token=token
+            ) for token in multicast_message.tokens]
+    else:
+        messages = [Message(
+            data=multicast_message.data,
+            notification=multicast_message.notification,
+            android=multicast_message.android,
+            webpush=multicast_message.webpush,
+            apns=multicast_message.apns,
+            fcm_options=multicast_message.fcm_options,
+            fid=fid
+        ) for fid in multicast_message.fids]
     return _get_messaging_service(app).send_each(messages, dry_run)
 
 def subscribe_to_topic(tokens, topic, app=None):

tests/test_messaging.py

@@ -99,6 +99,15 @@ def test_data_message(self):
 
 class TestMulticastMessage:
 
+    def test_invalid_targets(self):
+        with pytest.raises(ValueError) as excinfo:
+            messaging.MulticastMessage()
+        assert str(excinfo.value) == "Must specify either 'tokens' or 'fids'."
+
+        with pytest.raises(ValueError) as excinfo:
+            messaging.MulticastMessage(tokens=['token'], fids=['fid'])
+        assert str(excinfo.value) == "Must specify either 'tokens' or 'fids'."
+
     @pytest.mark.parametrize('tokens', NON_LIST_ARGS)
     def test_invalid_tokens_type(self, tokens):
         with pytest.raises(ValueError) as excinfo:
@@ -123,6 +132,34 @@ def test_tokens_type(self):
         message = messaging.MulticastMessage(tokens=['token' for _ in range(0, 500)])
         assert len(message.tokens) == 500
 
+    @pytest.mark.parametrize('fids', NON_LIST_ARGS)
+    def test_invalid_fids_type(self, fids):
+        with pytest.raises(ValueError) as excinfo:
+            messaging.MulticastMessage(fids=fids)
+        if isinstance(fids, list):
+            expected = 'MulticastMessage.fids must not contain non-string values.'
+            assert str(excinfo.value) == expected
+        else:
+            expected = 'MulticastMessage.fids must be a list of strings.'
+            assert str(excinfo.value) == expected
+
+    def test_fids_over_500(self):
+        with pytest.raises(ValueError) as excinfo:
+            messaging.MulticastMessage(fids=['fid' for _ in range(0, 501)])
+        expected = 'MulticastMessage.fids must not contain more than 500 fids.'
+        assert str(excinfo.value) == expected
+
+    def test_fids_type(self):
+        message = messaging.MulticastMessage(fids=['fid'])
+        assert len(message.fids) == 1
+
+        message = messaging.MulticastMessage(fids=['fid' for _ in range(0, 500)])
+        assert len(message.fids) == 500
+
+    def test_tokens_deprecation_warning(self):
+        with pytest.deprecated_call():
+            messaging.MulticastMessage(tokens=['token'])
+
 
 class TestMessageEncoder:
 
@@ -2231,6 +2268,20 @@ def test_send_each_for_multicast(self):
         assert all(r.success for r in batch_response.responses)
         assert not any(r.exception for r in batch_response.responses)
 
+    def test_send_each_for_multicast_fids(self):
+        payload1 = json.dumps({'name': 'message-id1'})
+        payload2 = json.dumps({'name': 'message-id2'})
+        _ = self._instrument_messaging_service(
+            response_dict={'foo1': [200, payload1], 'foo2': [200, payload2]})
+        msg = messaging.MulticastMessage(fids=['foo1', 'foo2'])
+        batch_response = messaging.send_each_for_multicast(msg, dry_run=True)
+        assert batch_response.success_count == 2
+        assert batch_response.failure_count == 0
+        assert len(batch_response.responses) == 2
+        assert [r.message_id for r in batch_response.responses] == ['message-id1', 'message-id2']
+        assert all(r.success for r in batch_response.responses)
+        assert not any(r.exception for r in batch_response.responses)
+
     @pytest.mark.parametrize('status', HTTP_ERROR_CODES)
     def test_send_each_for_multicast_detailed_error(self, status):
         success_payload = json.dumps({'name': 'message-id'})