Media player platform back-compat for custom components without MediaPlayerEntityFeature (#106616)

homeassistant/components/media_player/__init__.py

@@ -766,6 +766,19 @@ class MediaPlayerEntity(Entity, cached_properties=CACHED_PROPERTIES_WITH_ATTR_):
         """Flag media player features that are supported."""
         return self._attr_supported_features
 
+    @property
+    def supported_features_compat(self) -> MediaPlayerEntityFeature:
+        """Return the supported features as MediaPlayerEntityFeature.
+
+        Remove this compatibility shim in 2025.1 or later.
+        """
+        features = self.supported_features
+        if type(features) is int:  # noqa: E721
+            new_features = MediaPlayerEntityFeature(features)
+            self._report_deprecated_supported_features_values(new_features)
+            return new_features
+        return features
+
     def turn_on(self) -> None:
         """Turn the media player on."""
         raise NotImplementedError()
@@ -905,85 +918,87 @@ class MediaPlayerEntity(Entity, cached_properties=CACHED_PROPERTIES_WITH_ATTR_):
     @property
     def support_play(self) -> bool:
         """Boolean if play is supported."""
-        return MediaPlayerEntityFeature.PLAY in self.supported_features
+        return MediaPlayerEntityFeature.PLAY in self.supported_features_compat
 
     @final
     @property
     def support_pause(self) -> bool:
         """Boolean if pause is supported."""
-        return MediaPlayerEntityFeature.PAUSE in self.supported_features
+        return MediaPlayerEntityFeature.PAUSE in self.supported_features_compat
 
     @final
     @property
     def support_stop(self) -> bool:
         """Boolean if stop is supported."""
-        return MediaPlayerEntityFeature.STOP in self.supported_features
+        return MediaPlayerEntityFeature.STOP in self.supported_features_compat
 
     @final
     @property
     def support_seek(self) -> bool:
         """Boolean if seek is supported."""
-        return MediaPlayerEntityFeature.SEEK in self.supported_features
+        return MediaPlayerEntityFeature.SEEK in self.supported_features_compat
 
     @final
     @property
     def support_volume_set(self) -> bool:
         """Boolean if setting volume is supported."""
-        return MediaPlayerEntityFeature.VOLUME_SET in self.supported_features
+        return MediaPlayerEntityFeature.VOLUME_SET in self.supported_features_compat
 
     @final
     @property
     def support_volume_mute(self) -> bool:
         """Boolean if muting volume is supported."""
-        return MediaPlayerEntityFeature.VOLUME_MUTE in self.supported_features
+        return MediaPlayerEntityFeature.VOLUME_MUTE in self.supported_features_compat
 
     @final
     @property
     def support_previous_track(self) -> bool:
         """Boolean if previous track command supported."""
-        return MediaPlayerEntityFeature.PREVIOUS_TRACK in self.supported_features
+        return MediaPlayerEntityFeature.PREVIOUS_TRACK in self.supported_features_compat
 
     @final
     @property
     def support_next_track(self) -> bool:
         """Boolean if next track command supported."""
-        return MediaPlayerEntityFeature.NEXT_TRACK in self.supported_features
+        return MediaPlayerEntityFeature.NEXT_TRACK in self.supported_features_compat
 
     @final
     @property
     def support_play_media(self) -> bool:
         """Boolean if play media command supported."""
-        return MediaPlayerEntityFeature.PLAY_MEDIA in self.supported_features
+        return MediaPlayerEntityFeature.PLAY_MEDIA in self.supported_features_compat
 
     @final
     @property
     def support_select_source(self) -> bool:
         """Boolean if select source command supported."""
-        return MediaPlayerEntityFeature.SELECT_SOURCE in self.supported_features
+        return MediaPlayerEntityFeature.SELECT_SOURCE in self.supported_features_compat
 
     @final
     @property
     def support_select_sound_mode(self) -> bool:
         """Boolean if select sound mode command supported."""
-        return MediaPlayerEntityFeature.SELECT_SOUND_MODE in self.supported_features
+        return (
+            MediaPlayerEntityFeature.SELECT_SOUND_MODE in self.supported_features_compat
+        )
 
     @final
     @property
     def support_clear_playlist(self) -> bool:
         """Boolean if clear playlist command supported."""
-        return MediaPlayerEntityFeature.CLEAR_PLAYLIST in self.supported_features
+        return MediaPlayerEntityFeature.CLEAR_PLAYLIST in self.supported_features_compat
 
     @final
     @property
     def support_shuffle_set(self) -> bool:
         """Boolean if shuffle is supported."""
-        return MediaPlayerEntityFeature.SHUFFLE_SET in self.supported_features
+        return MediaPlayerEntityFeature.SHUFFLE_SET in self.supported_features_compat
 
     @final
     @property
     def support_grouping(self) -> bool:
         """Boolean if player grouping is supported."""
-        return MediaPlayerEntityFeature.GROUPING in self.supported_features
+        return MediaPlayerEntityFeature.GROUPING in self.supported_features_compat
 
     async def async_toggle(self) -> None:
         """Toggle the power on the media player."""
@@ -1012,7 +1027,7 @@ class MediaPlayerEntity(Entity, cached_properties=CACHED_PROPERTIES_WITH_ATTR_):
         if (
             self.volume_level is not None
             and self.volume_level < 1
-            and MediaPlayerEntityFeature.VOLUME_SET in self.supported_features
+            and MediaPlayerEntityFeature.VOLUME_SET in self.supported_features_compat
         ):
             await self.async_set_volume_level(
                 min(1, self.volume_level + self.volume_step)
@@ -1030,7 +1045,7 @@ class MediaPlayerEntity(Entity, cached_properties=CACHED_PROPERTIES_WITH_ATTR_):
         if (
             self.volume_level is not None
             and self.volume_level > 0
-            and MediaPlayerEntityFeature.VOLUME_SET in self.supported_features
+            and MediaPlayerEntityFeature.VOLUME_SET in self.supported_features_compat
         ):
             await self.async_set_volume_level(
                 max(0, self.volume_level - self.volume_step)
@@ -1073,7 +1088,7 @@ class MediaPlayerEntity(Entity, cached_properties=CACHED_PROPERTIES_WITH_ATTR_):
     def capability_attributes(self) -> dict[str, Any]:
         """Return capability attributes."""
         data: dict[str, Any] = {}
-        supported_features = self.supported_features
+        supported_features = self.supported_features_compat
 
         if (
             source_list := self.source_list

tests/components/media_player/test_init.py

@@ -10,6 +10,8 @@ from homeassistant.components.media_player import (
     BrowseMedia,
     MediaClass,
     MediaPlayerEnqueue,
+    MediaPlayerEntity,
+    MediaPlayerEntityFeature,
 )
 from homeassistant.components.websocket_api.const import TYPE_RESULT
 from homeassistant.const import ATTR_ENTITY_ID, STATE_OFF
@@ -327,3 +329,23 @@ async def test_get_async_get_browse_image_quoting(
         url = player.get_browse_image_url("album", media_content_id)
         await client.get(url)
         mock_browse_image.assert_called_with("album", media_content_id, None)
+
+
+def test_deprecated_supported_features_ints(caplog: pytest.LogCaptureFixture) -> None:
+    """Test deprecated supported features ints."""
+
+    class MockMediaPlayerEntity(MediaPlayerEntity):
+        @property
+        def supported_features(self) -> int:
+            """Return supported features."""
+            return 1
+
+    entity = MockMediaPlayerEntity()
+    assert entity.supported_features_compat is MediaPlayerEntityFeature(1)
+    assert "MockMediaPlayerEntity" in caplog.text
+    assert "is using deprecated supported features values" in caplog.text
+    assert "Instead it should use" in caplog.text
+    assert "MediaPlayerEntityFeature.PAUSE" in caplog.text
+    caplog.clear()
+    assert entity.supported_features_compat is MediaPlayerEntityFeature(1)
+    assert "is using deprecated supported features values" not in caplog.text