feat(fcm): Enable `fid` and deprecate `token` for Send API by yvonnep165 · Pull Request #951 · firebase/firebase-admin-python

yvonnep165 · 2026-05-07T17:20:29Z

This change deprecates token (in Message) and tokens (in MulticastMessage) as message targets, transitioning support to fid (Firebase Installation ID) and fids as the primary targets instead.

The active multicast helper functions (send_each_for_multicast and send_each_for_multicast_async) are updated to support both target types. These helpers leverage Python's warnings.catch_warnings() to suppress duplicate internal warning logs during loop instantiation, ensuring a clean developer experience by raising only a single deprecation warning at the point of object construction.

… tests

gemini-code-assist

Code Review

This pull request introduces support for Firebase Installation IDs (fid and fids) in the Message and MulticastMessage classes, marking the existing token and tokens fields as deprecated. Feedback highlights a critical backward-compatibility issue where changing the MulticastMessage constructor signature breaks positional arguments for existing users. Additionally, it is recommended to extract duplicated logic for converting multicast messages into individual message objects into a shared helper function to improve maintainability.

gemini-code-assist · 2026-05-07T17:23:39Z

+    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


The change to the MulticastMessage.__init__ method signature introduces a significant backward-incompatible change. The new signature is def __init__(self, fids=None, tokens=None, ...) where previously it was def __init__(self, tokens, ...). This breaks calls that use positional arguments, as MulticastMessage(['my-token']) will now silently and incorrectly interpret ['my-token'] as a list of fids.

To avoid this breaking change, I suggest reverting the argument order and adjusting the logic to handle the mutual exclusivity of tokens and fids. The tokens parameter should be made optional, and fids can be added at the end. This ensures backward compatibility for existing users.

def __init__(self, tokens=None, data=None, notification=None, android=None, webpush=None, apns=None, fcm_options=None, fids=None): if tokens is not None: warnings.warn( "Deprecated. Use 'fids' instead.", DeprecationWarning, stacklevel=2 ) if (tokens is not None) + (fids is not None) != 1: raise ValueError("Must specify exactly one of '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

gemini-code-assist · 2026-05-07T17:23:39Z

+    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]


This block of logic for converting a MulticastMessage into a list of Message objects is duplicated in send_each_for_multicast (lines 245-266). To improve maintainability and follow the DRY (Don't Repeat Yourself) principle, consider extracting this logic into a private helper function that can be called from both send_each_for_multicast_async and send_each_for_multicast.

Helper function is added

…y positional arguments and add a unit test for it

…per function

lahirumaramba

Thank you! Looks great! :)
Added a few comments.

lahirumaramba · 2026-05-07T19:51:42Z


    def __init__(self, data=None, notification=None, android=None, webpush=None, apns=None,
-                 fcm_options=None, token=None, topic=None, condition=None):
+                 fcm_options=None, fid=None, token=None, topic=None, condition=None):


Let's move fid=None to end of the list to remove any potential backward compatibility issues if someone is currently passing arguments positionally rather than by keyword.

def __init__(self, data=None, notification=None, android=None, webpush=None, apns=None, fcm_options=None, token=None, topic=None, condition=None, fid=None):

lahirumaramba · 2026-05-07T19:53:28Z

+                 fcm_options=None, fid=None, token=None, topic=None, condition=None):
+        if token is not None:
+            warnings.warn(
+                "Deprecated. Use 'fid' instead.",


Let's change this to Message.token is deprecated. Use fid instead.

Suggested change

"Deprecated. Use 'fid' instead.",

"Message.token is deprecated. Use fid instead.",

lahirumaramba · 2026-05-07T19:54:09Z

+            webpush=None, apns=None, fcm_options=None):
+        if tokens is not None:
+            warnings.warn(
+                "Deprecated. Use 'fids' instead.",


Suggested change

"Deprecated. Use 'fids' instead.",

"MulticastMessage.tokens is deprecated. Use fids instead.",

lahirumaramba · 2026-05-07T19:55:12Z

        fcm_options: An instance of ``messaging.FCMOptions`` (optional).
-        token: The registration token of the device to which the message should be sent (optional).
+        fid: The Firebase installation ID of an FCM registered app instance to which the
+            message should be sent (optional)


nit: missing . at the end

lahirumaramba · 2026-05-07T19:55:22Z


    Args:
-        tokens: A list of registration tokens of targeted devices.
+        fids: A list of Firebase Installation IDs of targeted app instances (optional)


nit: missing . at the end

lahirumaramba · 2026-05-07T19:56:26Z

        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):


do we have any tests for send_each_for_multicast_async?

We didn't have unit tests for send_each_for_multicast_async previously but only included it in integration tests. Added some unit tests with respx to mock raw HTTP/2 concurrent POST requests to Google's servers

…ddress other review comments

yvonnep165 added 2 commits May 6, 2026 16:44

add fid arg and token deprecate warning to Message class and add unit…

64e98d1

… tests

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

92fa458

… tests

gemini-code-assist Bot reviewed May 7, 2026

View reviewed changes

yvonnep165 added 4 commits May 7, 2026 13:28

Fix lint formatting error

f384d6e

Position tokens first to guarantee backward compatibility for legac…

0509f0a

…y positional arguments and add a unit test for it

Extract multicast-to-message-list conversion logic into a private hel…

5c68f2a

…per function

Add docstring for the helper function

f258b3f

yvonnep165 requested review from Doris-Ge and lahirumaramba May 7, 2026 18:04

Merge branch 'main' into yp-add-fid-arg

e808deb

lahirumaramba reviewed May 7, 2026

View reviewed changes

lahirumaramba assigned yvonnep165 May 7, 2026

lahirumaramba added release-note release:stage Stage a release candidate labels May 7, 2026

Add unit tests for the async function, change deprecate message and a…

1831f6a

…ddress other review comments

	"Deprecated. Use 'fid' instead.",
	"Message.token is deprecated. Use fid instead.",

	"Deprecated. Use 'fids' instead.",
	"MulticastMessage.tokens is deprecated. Use fids instead.",

Conversation

yvonnep165 commented May 7, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot May 7, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 7, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lahirumaramba left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants