Introduce new MediaPlayerState StrEnum (#77941)

* Adjust media-player checks in pylint plugin

* Adjust media-player definitions

* Adjust cast signatures

* Adjust play_media signature

* Introduce MediaPlayerState

* Fix cast implementations

* Revert cast changes

* Update hass_enforce_type_hints.py

* Use set

Co-authored-by: Marc Mueller <30130371+cdce8p@users.noreply.github.com>

* Fix tests

* Keep unused constants

* Fix test

* Revert tests

Co-authored-by: Marc Mueller <30130371+cdce8p@users.noreply.github.com>

homeassistant/components/media_player/__init__.py

@@ -30,7 +30,7 @@ from homeassistant.components.websocket_api.const import (
     ERR_UNKNOWN_ERROR,
 )
 from homeassistant.config_entries import ConfigEntry
-from homeassistant.const import (
+from homeassistant.const import (  # noqa: F401
     SERVICE_MEDIA_NEXT_TRACK,
     SERVICE_MEDIA_PAUSE,
     SERVICE_MEDIA_PLAY,
@@ -128,6 +128,8 @@ from .const import (  # noqa: F401
     SUPPORT_VOLUME_SET,
     SUPPORT_VOLUME_STEP,
     MediaPlayerEntityFeature,
+    MediaPlayerState,
+    MediaType,
     RepeatMode,
 )
 from .errors import BrowseError
@@ -226,7 +228,8 @@ def is_on(hass, entity_id=None):
     """
     entity_ids = [entity_id] if entity_id else hass.states.entity_ids(DOMAIN)
     return any(
-        not hass.states.is_state(entity_id, STATE_OFF) for entity_id in entity_ids
+        not hass.states.is_state(entity_id, MediaPlayerState.OFF)
+        for entity_id in entity_ids
     )
 
 
@@ -454,7 +457,7 @@ class MediaPlayerEntity(Entity):
     _attr_media_artist: str | None = None
     _attr_media_channel: str | None = None
     _attr_media_content_id: str | None = None
-    _attr_media_content_type: str | None = None
+    _attr_media_content_type: MediaType | str | None = None
     _attr_media_duration: int | None = None
     _attr_media_episode: str | None = None
     _attr_media_image_hash: str | None
@@ -467,13 +470,13 @@ class MediaPlayerEntity(Entity):
     _attr_media_series_title: str | None = None
     _attr_media_title: str | None = None
     _attr_media_track: int | None = None
-    _attr_repeat: str | None = None
+    _attr_repeat: RepeatMode | str | None = None
     _attr_shuffle: bool | None = None
     _attr_sound_mode_list: list[str] | None = None
     _attr_sound_mode: str | None = None
     _attr_source_list: list[str] | None = None
     _attr_source: str | None = None
-    _attr_state: str | None = None
+    _attr_state: MediaPlayerState | str | None = None
     _attr_supported_features: int = 0
     _attr_volume_level: float | None = None
 
@@ -488,7 +491,7 @@ class MediaPlayerEntity(Entity):
         return None
 
     @property
-    def state(self) -> str | None:
+    def state(self) -> MediaPlayerState | str | None:
         """State of the player."""
         return self._attr_state
 
@@ -515,7 +518,7 @@ class MediaPlayerEntity(Entity):
         return self._attr_media_content_id
 
     @property
-    def media_content_type(self) -> str | None:
+    def media_content_type(self) -> MediaType | str | None:
         """Content type of current playing media."""
         return self._attr_media_content_type
 
@@ -664,7 +667,7 @@ class MediaPlayerEntity(Entity):
         return self._attr_shuffle
 
     @property
-    def repeat(self) -> str | None:
+    def repeat(self) -> RepeatMode | str | None:
         """Return current repeat mode."""
         return self._attr_repeat
 
@@ -758,12 +761,14 @@ class MediaPlayerEntity(Entity):
         """Send seek command."""
         await self.hass.async_add_executor_job(self.media_seek, position)
 
-    def play_media(self, media_type: str, media_id: str, **kwargs: Any) -> None:
+    def play_media(
+        self, media_type: MediaType | str, media_id: str, **kwargs: Any
+    ) -> None:
         """Play a piece of media."""
         raise NotImplementedError()
 
     async def async_play_media(
-        self, media_type: str, media_id: str, **kwargs: Any
+        self, media_type: MediaType | str, media_id: str, **kwargs: Any
     ) -> None:
         """Play a piece of media."""
         await self.hass.async_add_executor_job(
@@ -905,7 +910,11 @@ class MediaPlayerEntity(Entity):
             )
             return
 
-        if self.state in (STATE_OFF, STATE_IDLE, STATE_STANDBY):
+        if self.state in {
+            MediaPlayerState.OFF,
+            MediaPlayerState.IDLE,
+            MediaPlayerState.STANDBY,
+        }:
             await self.async_turn_on()
         else:
             await self.async_turn_off()
@@ -954,7 +963,7 @@ class MediaPlayerEntity(Entity):
             )
             return
 
-        if self.state == STATE_PLAYING:
+        if self.state == MediaPlayerState.PLAYING:
             await self.async_media_pause()
         else:
             await self.async_media_play()
@@ -962,7 +971,7 @@ class MediaPlayerEntity(Entity):
     @property
     def entity_picture(self) -> str | None:
         """Return image of the media playing."""
-        if self.state == STATE_OFF:
+        if self.state == MediaPlayerState.OFF:
             return None
 
         if self.media_image_remotely_accessible:
@@ -1008,7 +1017,7 @@ class MediaPlayerEntity(Entity):
         if self.support_grouping:
             state_attr[ATTR_GROUP_MEMBERS] = self.group_members
 
-        if self.state == STATE_OFF:
+        if self.state == MediaPlayerState.OFF:
             return state_attr
 
         for attr in ATTR_TO_PROPERTY:

homeassistant/components/media_player/const.py

@@ -41,6 +41,18 @@ ATTR_SOUND_MODE_LIST = "sound_mode_list"
 DOMAIN = "media_player"
 
 
+class MediaPlayerState(StrEnum):
+    """State of media player entities."""
+
+    OFF = "off"
+    ON = "on"
+    IDLE = "idle"
+    PLAYING = "playing"
+    PAUSED = "paused"
+    STANDBY = "standby"
+    BUFFERING = "buffering"
+
+
 class MediaClass(StrEnum):
     """Media class for media player entities."""
 

pylint/plugins/hass_enforce_type_hints.py

@@ -1514,7 +1514,7 @@ _INHERITANCE_MATCH: dict[str, list[ClassTypeHintMatch]] = {
                 ),
                 TypeHintMatch(
                     function_name="state",
-                    return_type=["str", None],
+                    return_type=["MediaPlayerState", None],
                 ),
                 TypeHintMatch(
                     function_name="access_token",
@@ -1534,7 +1534,7 @@ _INHERITANCE_MATCH: dict[str, list[ClassTypeHintMatch]] = {
                 ),
                 TypeHintMatch(
                     function_name="media_content_type",
-                    return_type=["str", None],
+                    return_type=["MediaType", "str", None],
                 ),
                 TypeHintMatch(
                     function_name="media_duration",
@@ -1643,7 +1643,7 @@ _INHERITANCE_MATCH: dict[str, list[ClassTypeHintMatch]] = {
                 ),
                 TypeHintMatch(
                     function_name="repeat",
-                    return_type=["str", None],
+                    return_type=["RepeatMode", None],
                 ),
                 TypeHintMatch(
                     function_name="group_members",
@@ -1711,7 +1711,7 @@ _INHERITANCE_MATCH: dict[str, list[ClassTypeHintMatch]] = {
                 TypeHintMatch(
                     function_name="play_media",
                     arg_types={
-                        1: "str",
+                        1: "MediaType | str",
                         2: "str",
                     },
                     kwargs_type="Any",