From d62da432d098721151ca0d2712cd1146680b2846 Mon Sep 17 00:00:00 2001
From: G Johansson <goran.johansson@shiftit.se>
Date: Tue, 24 Sep 2024 18:15:41 +0000
Subject: [PATCH] Deprecate STATE_ON in light

---
 homeassistant/components/light/__init__.py | 28 +++++++++----
 tests/components/light/test_init.py        | 46 ++++++++++++++++++++++
 2 files changed, 67 insertions(+), 7 deletions(-)

diff --git a/homeassistant/components/light/__init__.py b/homeassistant/components/light/__init__.py
index cfed7d70f64..6ad4c248ab1 100644
--- a/homeassistant/components/light/__init__.py
+++ b/homeassistant/components/light/__init__.py
@@ -7,7 +7,7 @@ import csv
 import dataclasses
 from datetime import timedelta
 from enum import IntFlag, StrEnum
-from functools import cached_property
+from functools import cached_property, partial
 import logging
 import os
 from typing import Any, Self, cast, final
@@ -15,15 +15,16 @@ from typing import Any, Self, cast, final
 import voluptuous as vol
 
 from homeassistant.config_entries import ConfigEntry
-from homeassistant.const import (  # noqa: F401
-    SERVICE_TOGGLE,
-    SERVICE_TURN_OFF,
-    SERVICE_TURN_ON,
-    STATE_ON,
-)
+from homeassistant.const import SERVICE_TOGGLE, SERVICE_TURN_OFF, SERVICE_TURN_ON
 from homeassistant.core import HomeAssistant, ServiceCall, callback
 from homeassistant.exceptions import HomeAssistantError
 from homeassistant.helpers import config_validation as cv, entity_registry as er
+from homeassistant.helpers.deprecation import (
+    DeprecatedConstantEnum,
+    all_with_deprecated_constants,
+    check_if_deprecated_constant,
+    dir_with_deprecated_constants,
+)
 from homeassistant.helpers.entity import ToggleEntity, ToggleEntityDescription
 from homeassistant.helpers.entity_component import EntityComponent
 from homeassistant.helpers.typing import ConfigType, VolDictType
@@ -48,6 +49,11 @@ class LightState(StrEnum):
     OFF = "off"
 
 
+# The STATE_ON constant is deprecated as of Home Assistant 2024.10
+# Please use the LightState enum instead.
+_DEPRECATED_STATE_ON = DeprecatedConstantEnum(LightState.ON, "2025.10")
+
+
 class LightEntityFeature(IntFlag):
     """Supported features of the light entity."""
 
@@ -1352,3 +1358,11 @@ class LightEntity(ToggleEntity, cached_properties=CACHED_PROPERTIES_WITH_ATTR_):
             return True
         # philips_js has known issues, we don't need users to open issues
         return self.platform.platform_name not in {"philips_js"}
+
+
+# These can be removed if no deprecated constant are in this module anymore
+__getattr__ = partial(check_if_deprecated_constant, module_globals=globals())
+__dir__ = partial(
+    dir_with_deprecated_constants, module_globals_keys=[*globals().keys()]
+)
+__all__ = all_with_deprecated_constants(globals())
diff --git a/tests/components/light/test_init.py b/tests/components/light/test_init.py
index 2bf0e9ef100..7a7ef865d9a 100644
--- a/tests/components/light/test_init.py
+++ b/tests/components/light/test_init.py
@@ -1,5 +1,6 @@
 """The tests for the Light component."""
 
+from types import ModuleType
 from typing import Literal
 from unittest.mock import MagicMock, mock_open, patch
 
@@ -27,6 +28,8 @@ from tests.common import (
     MockEntityPlatform,
     MockUser,
     async_mock_service,
+    help_test_all,
+    import_and_test_deprecated_constant_enum,
     setup_test_component_platform,
 )
 
@@ -2800,3 +2803,46 @@ def test_report_invalid_color_modes(
     entity._async_calculate_state()
     expected_warning = "sets invalid supported color modes"
     assert (expected_warning in caplog.text) is warning_expected
+
+
+@pytest.mark.parametrize(
+    "module",
+    [light],
+)
+def test_all(module: ModuleType) -> None:
+    """Test module.__all__ is correctly set."""
+    help_test_all(module)
+
+
+@pytest.mark.parametrize(
+    "enum",
+    [light.LightState.ON],
+)
+@pytest.mark.parametrize(
+    "module",
+    [light],
+)
+def test_deprecated_stream_type_constants(
+    caplog: pytest.LogCaptureFixture,
+    enum: light.LightState,
+    module: ModuleType,
+) -> None:
+    """Test deprecated stream type constants."""
+    import_and_test_deprecated_constant_enum(caplog, module, enum, "STATE_", "2025.10")
+
+
+@pytest.mark.parametrize(
+    "enum",
+    [light.LightState.ON],
+)
+@pytest.mark.parametrize(
+    "module",
+    [light],
+)
+def test_deprecated_state_constants(
+    caplog: pytest.LogCaptureFixture,
+    enum: light.LightState,
+    module: ModuleType,
+) -> None:
+    """Test deprecated stream type constants."""
+    import_and_test_deprecated_constant_enum(caplog, module, enum, "STATE_", "2025.10")