Implemented messaging.CriticalSound API (#238)

* Implemented messaging.CriticalSound API

* Disallowing empty strings in APNs sound config

* Minor simplification

* Accepting any Truthy value for critical

Author: hiranya911

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Unreleased
 
+- `messaging.Aps` class now supports configuring a critical sound. A new
+  `messaging.CriticalSound` class has been introduced for this purpose.
 - [changed] Dropped support for Python 3.3.
 
 # v2.14.0

firebase_admin/messaging.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+# pylint: disable=too-many-lines
+
 """Firebase Cloud Messaging module."""
 
 import datetime
@@ -395,7 +397,8 @@ class Aps(object):
     Args:
         alert: A string or a ``messaging.ApsAlert`` instance (optional).
         badge: A number representing the badge to be displayed with the message (optional).
-        sound: Name of the sound file to be played with the message (optional).
+        sound: Name of the sound file to be played with the message or a
+            ``messaging.CriticalSound`` instance (optional).
         content_available: A boolean indicating whether to configure a background update
             notification (optional).
         category: String identifier representing the message type (optional).
@@ -418,6 +421,25 @@ def __init__(self, alert=None, badge=None, sound=None, content_available=None, c
         self.custom_data = custom_data
 
 
+class CriticalSound(object):
+    """Critical alert sound configuration that can be included in ``messaging.Aps``.
+
+    Args:
+        name: The name of a sound file in your app's main bundle or in the ``Library/Sounds``
+            folder of your app's container directory. Specify the string ``default`` to play the
+            system sound.
+        critical: Set to ``True`` to set the critical alert flag on the sound configuration
+            (optional).
+        volume: The volume for the critical alert's sound. Must be a value between 0.0 (silent)
+            and 1.0 (full volume) (optional).
+    """
+
+    def __init__(self, name, critical=None, volume=None):
+        self.name = name
+        self.critical = critical
+        self.volume = volume
+
+
 class ApsAlert(object):
     """An alert that can be included in ``messaging.Aps``.
 
@@ -738,7 +760,7 @@ def encode_aps(cls, aps):
         result = {
             'alert': cls.encode_aps_alert(aps.alert),
             'badge': _Validators.check_number('Aps.badge', aps.badge),
-            'sound': _Validators.check_string('Aps.sound', aps.sound),
+            'sound': cls.encode_aps_sound(aps.sound),
             'category': _Validators.check_string('Aps.category', aps.category),
             'thread-id': _Validators.check_string('Aps.thread_id', aps.thread_id),
         }
@@ -756,6 +778,29 @@ def encode_aps(cls, aps):
                 result[key] = val
         return cls.remove_null_values(result)
 
+    @classmethod
+    def encode_aps_sound(cls, sound):
+        """Encodes an APNs sound configuration into JSON."""
+        if sound is None:
+            return None
+        if sound and isinstance(sound, six.string_types):
+            return sound
+        if not isinstance(sound, CriticalSound):
+            raise ValueError(
+                'Aps.sound must be a non-empty string or an instance of CriticalSound class.')
+        result = {
+            'name': _Validators.check_string('CriticalSound.name', sound.name, non_empty=True),
+            'volume': _Validators.check_number('CriticalSound.volume', sound.volume),
+        }
+        if sound.critical:
+            result['critical'] = 1
+        if not result['name']:
+            raise ValueError('CriticalSond.name must be a non-empty string.')
+        volume = result['volume']
+        if volume is not None and (volume < 0 or volume > 1):
+            raise ValueError('CriticalSound.volume must be in the interval [0,1].')
+        return cls.remove_null_values(result)
+
     @classmethod
     def encode_aps_alert(cls, alert):
         """Encodes an ApsAlert instance into JSON."""

tests/test_messaging.py

@@ -721,12 +721,12 @@ def test_invalid_badge(self, data):
         expected = 'Aps.badge must be a number.'
         assert str(excinfo.value) == expected
 
-    @pytest.mark.parametrize('data', NON_STRING_ARGS)
+    @pytest.mark.parametrize('data', NON_STRING_ARGS + [''])
     def test_invalid_sound(self, data):
         aps = messaging.Aps(sound=data)
         with pytest.raises(ValueError) as excinfo:
             self._encode_aps(aps)
-        expected = 'Aps.sound must be a string.'
+        expected = 'Aps.sound must be a non-empty string or an instance of CriticalSound class.'
         assert str(excinfo.value) == expected
 
     @pytest.mark.parametrize('data', NON_STRING_ARGS)
@@ -832,6 +832,114 @@ def test_aps_custom_data(self):
         check_encoding(msg, expected)
 
 
+class TestApsSoundEncoder(object):
+
+    def _check_sound(self, sound):
+        with pytest.raises(ValueError) as excinfo:
+            check_encoding(messaging.Message(
+                topic='topic', apns=messaging.APNSConfig(
+                    payload=messaging.APNSPayload(aps=messaging.Aps(sound=sound))
+                )
+            ))
+        return excinfo
+
+    @pytest.mark.parametrize('data', NON_STRING_ARGS)
+    def test_invalid_name(self, data):
+        sound = messaging.CriticalSound(name=data)
+        excinfo = self._check_sound(sound)
+        expected = 'CriticalSound.name must be a non-empty string.'
+        assert str(excinfo.value) == expected
+
+    @pytest.mark.parametrize('data', [list(), tuple(), dict(), 'foo'])
+    def test_invalid_volume(self, data):
+        sound = messaging.CriticalSound(name='default', volume=data)
+        excinfo = self._check_sound(sound)
+        expected = 'CriticalSound.volume must be a number.'
+        assert str(excinfo.value) == expected
+
+    @pytest.mark.parametrize('data', [-0.1, 1.1])
+    def test_volume_out_of_range(self, data):
+        sound = messaging.CriticalSound(name='default', volume=data)
+        excinfo = self._check_sound(sound)
+        expected = 'CriticalSound.volume must be in the interval [0,1].'
+        assert str(excinfo.value) == expected
+
+    def test_sound_string(self):
+        msg = messaging.Message(
+            topic='topic',
+            apns=messaging.APNSConfig(
+                payload=messaging.APNSPayload(aps=messaging.Aps(sound='default'))
+            )
+        )
+        expected = {
+            'topic': 'topic',
+            'apns': {
+                'payload': {
+                    'aps': {
+                        'sound': 'default',
+                    },
+                }
+            },
+        }
+        check_encoding(msg, expected)
+
+    def test_critical_sound(self):
+        msg = messaging.Message(
+            topic='topic',
+            apns=messaging.APNSConfig(
+                payload=messaging.APNSPayload(
+                    aps=messaging.Aps(
+                        sound=messaging.CriticalSound(
+                            name='default',
+                            critical=True,
+                            volume=0.5
+                        )
+                    ),
+                )
+            )
+        )
+        expected = {
+            'topic': 'topic',
+            'apns': {
+                'payload': {
+                    'aps': {
+                        'sound': {
+                            'name': 'default',
+                            'critical': 1,
+                            'volume': 0.5,
+                        },
+                    },
+                }
+            },
+        }
+        check_encoding(msg, expected)
+
+    def test_critical_sound_name_only(self):
+        msg = messaging.Message(
+            topic='topic',
+            apns=messaging.APNSConfig(
+                payload=messaging.APNSPayload(
+                    aps=messaging.Aps(
+                        sound=messaging.CriticalSound(name='default')
+                    ),
+                )
+            )
+        )
+        expected = {
+            'topic': 'topic',
+            'apns': {
+                'payload': {
+                    'aps': {
+                        'sound': {
+                            'name': 'default',
+                        },
+                    },
+                }
+            },
+        }
+        check_encoding(msg, expected)
+
+
 class TestApsAlertEncoder(object):
 
     def _check_alert(self, alert):