Start deprecation for media_player constants (#126351)

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

homeassistant/components/media_player/__init__.py

@@ -54,6 +54,12 @@ from homeassistant.const import (  # noqa: F401
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers import config_validation as cv
 from homeassistant.helpers.aiohttp_client import async_get_clientsession
+from homeassistant.helpers.deprecation import (
+    DeprecatedConstantEnum,
+    all_with_deprecated_constants,
+    check_if_deprecated_constant,
+    dir_with_deprecated_constants,
+)
 from homeassistant.helpers.entity import Entity, EntityDescription
 from homeassistant.helpers.entity_component import EntityComponent
 from homeassistant.helpers.network import get_url
@@ -63,6 +69,26 @@ from homeassistant.util.hass_dict import HassKey
 
 from .browse_media import BrowseMedia, async_process_play_media_url  # noqa: F401
 from .const import (  # noqa: F401
+    _DEPRECATED_MEDIA_CLASS_DIRECTORY,
+    _DEPRECATED_SUPPORT_BROWSE_MEDIA,
+    _DEPRECATED_SUPPORT_CLEAR_PLAYLIST,
+    _DEPRECATED_SUPPORT_GROUPING,
+    _DEPRECATED_SUPPORT_NEXT_TRACK,
+    _DEPRECATED_SUPPORT_PAUSE,
+    _DEPRECATED_SUPPORT_PLAY,
+    _DEPRECATED_SUPPORT_PLAY_MEDIA,
+    _DEPRECATED_SUPPORT_PREVIOUS_TRACK,
+    _DEPRECATED_SUPPORT_REPEAT_SET,
+    _DEPRECATED_SUPPORT_SEEK,
+    _DEPRECATED_SUPPORT_SELECT_SOUND_MODE,
+    _DEPRECATED_SUPPORT_SELECT_SOURCE,
+    _DEPRECATED_SUPPORT_SHUFFLE_SET,
+    _DEPRECATED_SUPPORT_STOP,
+    _DEPRECATED_SUPPORT_TURN_OFF,
+    _DEPRECATED_SUPPORT_TURN_ON,
+    _DEPRECATED_SUPPORT_VOLUME_MUTE,
+    _DEPRECATED_SUPPORT_VOLUME_SET,
+    _DEPRECATED_SUPPORT_VOLUME_STEP,
     ATTR_APP_ID,
     ATTR_APP_NAME,
     ATTR_ENTITY_PICTURE_LOCAL,
@@ -96,7 +122,6 @@ from .const import (  # noqa: F401
     ATTR_SOUND_MODE_LIST,
     CONTENT_AUTH_EXPIRY_TIME,
     DOMAIN,
-    MEDIA_CLASS_DIRECTORY,
     REPEAT_MODES,
     SERVICE_CLEAR_PLAYLIST,
     SERVICE_JOIN,
@@ -104,25 +129,6 @@ from .const import (  # noqa: F401
     SERVICE_SELECT_SOUND_MODE,
     SERVICE_SELECT_SOURCE,
     SERVICE_UNJOIN,
-    SUPPORT_BROWSE_MEDIA,
-    SUPPORT_CLEAR_PLAYLIST,
-    SUPPORT_GROUPING,
-    SUPPORT_NEXT_TRACK,
-    SUPPORT_PAUSE,
-    SUPPORT_PLAY,
-    SUPPORT_PLAY_MEDIA,
-    SUPPORT_PREVIOUS_TRACK,
-    SUPPORT_REPEAT_SET,
-    SUPPORT_SEEK,
-    SUPPORT_SELECT_SOUND_MODE,
-    SUPPORT_SELECT_SOURCE,
-    SUPPORT_SHUFFLE_SET,
-    SUPPORT_STOP,
-    SUPPORT_TURN_OFF,
-    SUPPORT_TURN_ON,
-    SUPPORT_VOLUME_MUTE,
-    SUPPORT_VOLUME_SET,
-    SUPPORT_VOLUME_STEP,
     MediaClass,
     MediaPlayerEntityFeature,
     MediaPlayerState,
@@ -172,10 +178,16 @@ DEVICE_CLASSES_SCHEMA = vol.All(vol.Lower, vol.Coerce(MediaPlayerDeviceClass))
 
 # DEVICE_CLASS* below are deprecated as of 2021.12
 # use the MediaPlayerDeviceClass enum instead.
+_DEPRECATED_DEVICE_CLASS_TV = DeprecatedConstantEnum(
+    MediaPlayerDeviceClass.TV, "2025.10"
+)
+_DEPRECATED_DEVICE_CLASS_SPEAKER = DeprecatedConstantEnum(
+    MediaPlayerDeviceClass.SPEAKER, "2025.10"
+)
+_DEPRECATED_DEVICE_CLASS_RECEIVER = DeprecatedConstantEnum(
+    MediaPlayerDeviceClass.RECEIVER, "2025.10"
+)
 DEVICE_CLASSES = [cls.value for cls in MediaPlayerDeviceClass]
-DEVICE_CLASS_TV = MediaPlayerDeviceClass.TV.value
-DEVICE_CLASS_SPEAKER = MediaPlayerDeviceClass.SPEAKER.value
-DEVICE_CLASS_RECEIVER = MediaPlayerDeviceClass.RECEIVER.value
 
 
 MEDIA_PLAYER_PLAY_MEDIA_SCHEMA = {
@@ -1358,3 +1370,13 @@ async def async_fetch_image(
         logger.warning("Error retrieving proxied image from %s", url)
 
     return content, content_type
+
+
+# As we import deprecated constants from the const module, we need to add these two functions
+# otherwise this module will be logged for using deprecated constants and not the custom component
+# These can be removed if no deprecated constant are in this module anymore
+__getattr__ = ft.partial(check_if_deprecated_constant, module_globals=globals())
+__dir__ = ft.partial(
+    dir_with_deprecated_constants, module_globals_keys=[*globals().keys()]
+)
+__all__ = all_with_deprecated_constants(globals())

homeassistant/components/media_player/const.py

@@ -1,6 +1,14 @@
 """Provides the constants needed for component."""
 
 from enum import IntFlag, StrEnum
+from functools import partial
+
+from homeassistant.helpers.deprecation import (
+    DeprecatedConstantEnum,
+    all_with_deprecated_constants,
+    check_if_deprecated_constant,
+    dir_with_deprecated_constants,
+)
 
 # How long our auth signature on the content should be valid for
 CONTENT_AUTH_EXPIRY_TIME = 3600 * 24
@@ -79,26 +87,34 @@ class MediaClass(StrEnum):
 
 # These MEDIA_CLASS_* constants are deprecated as of Home Assistant 2022.10.
 # Please use the MediaClass enum instead.
-MEDIA_CLASS_ALBUM = "album"
+_DEPRECATED_MEDIA_CLASS_ALBUM = DeprecatedConstantEnum(MediaClass.ALBUM, "2025.10")
-MEDIA_CLASS_APP = "app"
+_DEPRECATED_MEDIA_CLASS_APP = DeprecatedConstantEnum(MediaClass.APP, "2025.10")
-MEDIA_CLASS_ARTIST = "artist"
+_DEPRECATED_MEDIA_CLASS_ARTIST = DeprecatedConstantEnum(MediaClass.ARTIST, "2025.10")
-MEDIA_CLASS_CHANNEL = "channel"
+_DEPRECATED_MEDIA_CLASS_CHANNEL = DeprecatedConstantEnum(MediaClass.CHANNEL, "2025.10")
-MEDIA_CLASS_COMPOSER = "composer"
+_DEPRECATED_MEDIA_CLASS_COMPOSER = DeprecatedConstantEnum(
-MEDIA_CLASS_CONTRIBUTING_ARTIST = "contributing_artist"
+    MediaClass.COMPOSER, "2025.10"
-MEDIA_CLASS_DIRECTORY = "directory"
+)
-MEDIA_CLASS_EPISODE = "episode"
+_DEPRECATED_MEDIA_CLASS_CONTRIBUTING_ARTIST = DeprecatedConstantEnum(
-MEDIA_CLASS_GAME = "game"
+    MediaClass.CONTRIBUTING_ARTIST, "2025.10"
-MEDIA_CLASS_GENRE = "genre"
+)
-MEDIA_CLASS_IMAGE = "image"
+_DEPRECATED_MEDIA_CLASS_DIRECTORY = DeprecatedConstantEnum(
-MEDIA_CLASS_MOVIE = "movie"
+    MediaClass.DIRECTORY, "2025.10"
-MEDIA_CLASS_MUSIC = "music"
+)
-MEDIA_CLASS_PLAYLIST = "playlist"
+_DEPRECATED_MEDIA_CLASS_EPISODE = DeprecatedConstantEnum(MediaClass.EPISODE, "2025.10")
-MEDIA_CLASS_PODCAST = "podcast"
+_DEPRECATED_MEDIA_CLASS_GAME = DeprecatedConstantEnum(MediaClass.GAME, "2025.10")
-MEDIA_CLASS_SEASON = "season"
+_DEPRECATED_MEDIA_CLASS_GENRE = DeprecatedConstantEnum(MediaClass.GENRE, "2025.10")
-MEDIA_CLASS_TRACK = "track"
+_DEPRECATED_MEDIA_CLASS_IMAGE = DeprecatedConstantEnum(MediaClass.IMAGE, "2025.10")
-MEDIA_CLASS_TV_SHOW = "tv_show"
+_DEPRECATED_MEDIA_CLASS_MOVIE = DeprecatedConstantEnum(MediaClass.MOVIE, "2025.10")
-MEDIA_CLASS_URL = "url"
+_DEPRECATED_MEDIA_CLASS_MUSIC = DeprecatedConstantEnum(MediaClass.MUSIC, "2025.10")
-MEDIA_CLASS_VIDEO = "video"
+_DEPRECATED_MEDIA_CLASS_PLAYLIST = DeprecatedConstantEnum(
+    MediaClass.PLAYLIST, "2025.10"
+)
+_DEPRECATED_MEDIA_CLASS_PODCAST = DeprecatedConstantEnum(MediaClass.PODCAST, "2025.10")
+_DEPRECATED_MEDIA_CLASS_SEASON = DeprecatedConstantEnum(MediaClass.SEASON, "2025.10")
+_DEPRECATED_MEDIA_CLASS_TRACK = DeprecatedConstantEnum(MediaClass.TRACK, "2025.10")
+_DEPRECATED_MEDIA_CLASS_TV_SHOW = DeprecatedConstantEnum(MediaClass.TV_SHOW, "2025.10")
+_DEPRECATED_MEDIA_CLASS_URL = DeprecatedConstantEnum(MediaClass.URL, "2025.10")
+_DEPRECATED_MEDIA_CLASS_VIDEO = DeprecatedConstantEnum(MediaClass.VIDEO, "2025.10")
 
 
 class MediaType(StrEnum):
@@ -129,27 +145,30 @@ class MediaType(StrEnum):
 
 # These MEDIA_TYPE_* constants are deprecated as of Home Assistant 2022.10.
 # Please use the MediaType enum instead.
-MEDIA_TYPE_ALBUM = "album"
+_DEPRECATED_MEDIA_TYPE_ALBUM = DeprecatedConstantEnum(MediaType.ALBUM, "2025.10")
-MEDIA_TYPE_APP = "app"
+_DEPRECATED_MEDIA_TYPE_APP = DeprecatedConstantEnum(MediaType.APP, "2025.10")
-MEDIA_TYPE_APPS = "apps"
+_DEPRECATED_MEDIA_TYPE_APPS = DeprecatedConstantEnum(MediaType.APPS, "2025.10")
-MEDIA_TYPE_ARTIST = "artist"
+_DEPRECATED_MEDIA_TYPE_ARTIST = DeprecatedConstantEnum(MediaType.ARTIST, "2025.10")
-MEDIA_TYPE_CHANNEL = "channel"
+_DEPRECATED_MEDIA_TYPE_CHANNEL = DeprecatedConstantEnum(MediaType.CHANNEL, "2025.10")
-MEDIA_TYPE_CHANNELS = "channels"
+_DEPRECATED_MEDIA_TYPE_CHANNELS = DeprecatedConstantEnum(MediaType.CHANNELS, "2025.10")
-MEDIA_TYPE_COMPOSER = "composer"
+_DEPRECATED_MEDIA_TYPE_COMPOSER = DeprecatedConstantEnum(MediaType.COMPOSER, "2025.10")
-MEDIA_TYPE_CONTRIBUTING_ARTIST = "contributing_artist"
+_DEPRECATED_MEDIA_TYPE_CONTRIBUTING_ARTIST = DeprecatedConstantEnum(
-MEDIA_TYPE_EPISODE = "episode"
+    MediaType.CONTRIBUTING_ARTIST, "2025.10"
-MEDIA_TYPE_GAME = "game"
+)
-MEDIA_TYPE_GENRE = "genre"
+_DEPRECATED_MEDIA_TYPE_EPISODE = DeprecatedConstantEnum(MediaType.EPISODE, "2025.10")
-MEDIA_TYPE_IMAGE = "image"
+_DEPRECATED_MEDIA_TYPE_GAME = DeprecatedConstantEnum(MediaType.GAME, "2025.10")
-MEDIA_TYPE_MOVIE = "movie"
+_DEPRECATED_MEDIA_TYPE_GENRE = DeprecatedConstantEnum(MediaType.GENRE, "2025.10")
-MEDIA_TYPE_MUSIC = "music"
+_DEPRECATED_MEDIA_TYPE_IMAGE = DeprecatedConstantEnum(MediaType.IMAGE, "2025.10")
-MEDIA_TYPE_PLAYLIST = "playlist"
+_DEPRECATED_MEDIA_TYPE_MOVIE = DeprecatedConstantEnum(MediaType.MOVIE, "2025.10")
-MEDIA_TYPE_PODCAST = "podcast"
+_DEPRECATED_MEDIA_TYPE_MUSIC = DeprecatedConstantEnum(MediaType.MUSIC, "2025.10")
-MEDIA_TYPE_SEASON = "season"
+_DEPRECATED_MEDIA_TYPE_PLAYLIST = DeprecatedConstantEnum(MediaType.PLAYLIST, "2025.10")
-MEDIA_TYPE_TRACK = "track"
+_DEPRECATED_MEDIA_TYPE_PODCAST = DeprecatedConstantEnum(MediaType.PODCAST, "2025.10")
-MEDIA_TYPE_TVSHOW = "tvshow"
+_DEPRECATED_MEDIA_TYPE_SEASON = DeprecatedConstantEnum(MediaType.SEASON, "2025.10")
-MEDIA_TYPE_URL = "url"
+_DEPRECATED_MEDIA_TYPE_TRACK = DeprecatedConstantEnum(MediaType.TRACK, "2025.10")
-MEDIA_TYPE_VIDEO = "video"
+_DEPRECATED_MEDIA_TYPE_TVSHOW = DeprecatedConstantEnum(MediaType.TVSHOW, "2025.10")
+_DEPRECATED_MEDIA_TYPE_URL = DeprecatedConstantEnum(MediaType.URL, "2025.10")
+_DEPRECATED_MEDIA_TYPE_VIDEO = DeprecatedConstantEnum(MediaType.VIDEO, "2025.10")
+
 
 SERVICE_CLEAR_PLAYLIST = "clear_playlist"
 SERVICE_JOIN = "join"
@@ -169,10 +188,10 @@ class RepeatMode(StrEnum):
 
 # These REPEAT_MODE_* constants are deprecated as of Home Assistant 2022.10.
 # Please use the RepeatMode enum instead.
-REPEAT_MODE_ALL = "all"
+_DEPRECATED_REPEAT_MODE_ALL = DeprecatedConstantEnum(RepeatMode.ALL, "2025.10")
-REPEAT_MODE_OFF = "off"
+_DEPRECATED_REPEAT_MODE_OFF = DeprecatedConstantEnum(RepeatMode.OFF, "2025.10")
-REPEAT_MODE_ONE = "one"
+_DEPRECATED_REPEAT_MODE_ONE = DeprecatedConstantEnum(RepeatMode.ONE, "2025.10")
-REPEAT_MODES = [REPEAT_MODE_OFF, REPEAT_MODE_ALL, REPEAT_MODE_ONE]
+REPEAT_MODES = [cls.value for cls in RepeatMode]
 
 
 class MediaPlayerEntityFeature(IntFlag):
@@ -204,23 +223,67 @@ class MediaPlayerEntityFeature(IntFlag):
 
 # These SUPPORT_* constants are deprecated as of Home Assistant 2022.5.
 # Please use the MediaPlayerEntityFeature enum instead.
-SUPPORT_PAUSE = 1
+_DEPRECATED_SUPPORT_PAUSE = DeprecatedConstantEnum(
-SUPPORT_SEEK = 2
+    MediaPlayerEntityFeature.PAUSE, "2025.10"
-SUPPORT_VOLUME_SET = 4
+)
-SUPPORT_VOLUME_MUTE = 8
+_DEPRECATED_SUPPORT_SEEK = DeprecatedConstantEnum(
-SUPPORT_PREVIOUS_TRACK = 16
+    MediaPlayerEntityFeature.SEEK, "2025.10"
-SUPPORT_NEXT_TRACK = 32
+)
+_DEPRECATED_SUPPORT_VOLUME_SET = DeprecatedConstantEnum(
+    MediaPlayerEntityFeature.VOLUME_SET, "2025.10"
+)
+_DEPRECATED_SUPPORT_VOLUME_MUTE = DeprecatedConstantEnum(
+    MediaPlayerEntityFeature.VOLUME_MUTE, "2025.10"
+)
+_DEPRECATED_SUPPORT_PREVIOUS_TRACK = DeprecatedConstantEnum(
+    MediaPlayerEntityFeature.PREVIOUS_TRACK, "2025.10"
+)
+_DEPRECATED_SUPPORT_NEXT_TRACK = DeprecatedConstantEnum(
+    MediaPlayerEntityFeature.NEXT_TRACK, "2025.10"
+)
+_DEPRECATED_SUPPORT_TURN_ON = DeprecatedConstantEnum(
+    MediaPlayerEntityFeature.TURN_ON, "2025.10"
+)
+_DEPRECATED_SUPPORT_TURN_OFF = DeprecatedConstantEnum(
+    MediaPlayerEntityFeature.TURN_OFF, "2025.10"
+)
+_DEPRECATED_SUPPORT_PLAY_MEDIA = DeprecatedConstantEnum(
+    MediaPlayerEntityFeature.PLAY_MEDIA, "2025.10"
+)
+_DEPRECATED_SUPPORT_VOLUME_STEP = DeprecatedConstantEnum(
+    MediaPlayerEntityFeature.VOLUME_STEP, "2025.10"
+)
+_DEPRECATED_SUPPORT_SELECT_SOURCE = DeprecatedConstantEnum(
+    MediaPlayerEntityFeature.SELECT_SOURCE, "2025.10"
+)
+_DEPRECATED_SUPPORT_STOP = DeprecatedConstantEnum(
+    MediaPlayerEntityFeature.STOP, "2025.10"
+)
+_DEPRECATED_SUPPORT_CLEAR_PLAYLIST = DeprecatedConstantEnum(
+    MediaPlayerEntityFeature.CLEAR_PLAYLIST, "2025.10"
+)
+_DEPRECATED_SUPPORT_PLAY = DeprecatedConstantEnum(
+    MediaPlayerEntityFeature.PLAY, "2025.10"
+)
+_DEPRECATED_SUPPORT_SHUFFLE_SET = DeprecatedConstantEnum(
+    MediaPlayerEntityFeature.SHUFFLE_SET, "2025.10"
+)
+_DEPRECATED_SUPPORT_SELECT_SOUND_MODE = DeprecatedConstantEnum(
+    MediaPlayerEntityFeature.SELECT_SOUND_MODE, "2025.10"
+)
+_DEPRECATED_SUPPORT_BROWSE_MEDIA = DeprecatedConstantEnum(
+    MediaPlayerEntityFeature.BROWSE_MEDIA, "2025.10"
+)
+_DEPRECATED_SUPPORT_REPEAT_SET = DeprecatedConstantEnum(
+    MediaPlayerEntityFeature.REPEAT_SET, "2025.10"
+)
+_DEPRECATED_SUPPORT_GROUPING = DeprecatedConstantEnum(
+    MediaPlayerEntityFeature.GROUPING, "2025.10"
+)
 
-SUPPORT_TURN_ON = 128
+# These can be removed if no deprecated constant are in this module anymore
-SUPPORT_TURN_OFF = 256
+__getattr__ = partial(check_if_deprecated_constant, module_globals=globals())
-SUPPORT_PLAY_MEDIA = 512
+__dir__ = partial(
-SUPPORT_VOLUME_STEP = 1024
+    dir_with_deprecated_constants, module_globals_keys=[*globals().keys()]
-SUPPORT_SELECT_SOURCE = 2048
+)
-SUPPORT_STOP = 4096
+__all__ = all_with_deprecated_constants(globals())
-SUPPORT_CLEAR_PLAYLIST = 8192
-SUPPORT_PLAY = 16384
-SUPPORT_SHUFFLE_SET = 32768
-SUPPORT_SELECT_SOUND_MODE = 65536
-SUPPORT_BROWSE_MEDIA = 131072
-SUPPORT_REPEAT_SET = 262144
-SUPPORT_GROUPING = 524288

tests/components/media_player/test_init.py

@@ -1,11 +1,14 @@
 """Test the base functions of the media player."""
 
+from enum import Enum
 from http import HTTPStatus
+from types import ModuleType
 from unittest.mock import patch
 
 import pytest
 import voluptuous as vol
 
+from homeassistant.components import media_player
 from homeassistant.components.media_player import (
     BrowseMedia,
     MediaClass,
@@ -18,6 +21,7 @@ from homeassistant.const import ATTR_ENTITY_ID, STATE_OFF
 from homeassistant.core import HomeAssistant
 from homeassistant.setup import async_setup_component
 
+from tests.common import help_test_all, import_and_test_deprecated_constant_enum
 from tests.test_util.aiohttp import AiohttpClientMocker
 from tests.typing import ClientSessionGenerator, WebSocketGenerator
 
@@ -28,6 +32,71 @@ async def setup_homeassistant(hass: HomeAssistant):
     await async_setup_component(hass, "homeassistant", {})
 
 
+def _create_tuples(enum: type[Enum], constant_prefix: str) -> list[tuple[Enum, str]]:
+    return [
+        (enum_field, constant_prefix)
+        for enum_field in enum
+        if enum_field
+        not in [
+            MediaPlayerEntityFeature.MEDIA_ANNOUNCE,
+            MediaPlayerEntityFeature.MEDIA_ENQUEUE,
+        ]
+    ]
+
+
+@pytest.mark.parametrize(
+    "module",
+    [media_player, media_player.const],
+)
+def test_all(module: ModuleType) -> None:
+    """Test module.__all__ is correctly set."""
+    help_test_all(module)
+
+
+@pytest.mark.parametrize(
+    ("enum", "constant_prefix"),
+    _create_tuples(media_player.MediaPlayerEntityFeature, "SUPPORT_")
+    + _create_tuples(media_player.MediaPlayerDeviceClass, "DEVICE_CLASS_"),
+)
+@pytest.mark.parametrize(
+    "module",
+    [media_player],
+)
+def test_deprecated_constants(
+    caplog: pytest.LogCaptureFixture,
+    enum: Enum,
+    constant_prefix: str,
+    module: ModuleType,
+) -> None:
+    """Test deprecated constants."""
+    import_and_test_deprecated_constant_enum(
+        caplog, module, enum, constant_prefix, "2025.10"
+    )
+
+
+@pytest.mark.parametrize(
+    ("enum", "constant_prefix"),
+    _create_tuples(media_player.MediaClass, "MEDIA_CLASS_")
+    + _create_tuples(media_player.MediaPlayerEntityFeature, "SUPPORT_")
+    + _create_tuples(media_player.MediaType, "MEDIA_TYPE_")
+    + _create_tuples(media_player.RepeatMode, "REPEAT_MODE_"),
+)
+@pytest.mark.parametrize(
+    "module",
+    [media_player.const],
+)
+def test_deprecated_constants_const(
+    caplog: pytest.LogCaptureFixture,
+    enum: Enum,
+    constant_prefix: str,
+    module: ModuleType,
+) -> None:
+    """Test deprecated constants."""
+    import_and_test_deprecated_constant_enum(
+        caplog, module, enum, constant_prefix, "2025.10"
+    )
+
+
 async def test_get_image_http(
     hass: HomeAssistant, hass_client_no_auth: ClientSessionGenerator
 ) -> None: