Fan platform back-compat for custom components without FanEntityFeature (#106607)

homeassistant/components/fan/__init__.py

@@ -400,7 +400,7 @@ class FanEntity(ToggleEntity, cached_properties=CACHED_PROPERTIES_WITH_ATTR_):
     def capability_attributes(self) -> dict[str, list[str] | None]:
         """Return capability attributes."""
         attrs = {}
-        supported_features = self.supported_features
+        supported_features = self.supported_features_compat
 
         if (
             FanEntityFeature.SET_SPEED in supported_features
@@ -415,7 +415,7 @@ class FanEntity(ToggleEntity, cached_properties=CACHED_PROPERTIES_WITH_ATTR_):
     def state_attributes(self) -> dict[str, float | str | None]:
         """Return optional state attributes."""
         data: dict[str, float | str | None] = {}
-        supported_features = self.supported_features
+        supported_features = self.supported_features_compat
 
         if FanEntityFeature.DIRECTION in supported_features:
             data[ATTR_DIRECTION] = self.current_direction
@@ -439,6 +439,19 @@ class FanEntity(ToggleEntity, cached_properties=CACHED_PROPERTIES_WITH_ATTR_):
         """Flag supported features."""
         return self._attr_supported_features
 
+    @property
+    def supported_features_compat(self) -> FanEntityFeature:
+        """Return the supported features as FanEntityFeature.
+
+        Remove this compatibility shim in 2025.1 or later.
+        """
+        features = self.supported_features
+        if type(features) is int:  # noqa: E721
+            new_features = FanEntityFeature(features)
+            self._report_deprecated_supported_features_values(new_features)
+            return new_features
+        return features
+
     @cached_property
     def preset_mode(self) -> str | None:
         """Return the current preset mode, e.g., auto, smart, interval, favorite.

tests/components/fan/test_init.py

@@ -8,6 +8,7 @@ from homeassistant.components.fan import (
     DOMAIN,
     SERVICE_SET_PRESET_MODE,
     FanEntity,
+    FanEntityFeature,
     NotValidPresetModeError,
 )
 from homeassistant.core import HomeAssistant
@@ -156,3 +157,23 @@ def test_deprecated_constants(
 ) -> None:
     """Test deprecated constants."""
     import_and_test_deprecated_constant_enum(caplog, fan, enum, "SUPPORT_", "2025.1")
+
+
+def test_deprecated_supported_features_ints(caplog: pytest.LogCaptureFixture) -> None:
+    """Test deprecated supported features ints."""
+
+    class MockFan(FanEntity):
+        @property
+        def supported_features(self) -> int:
+            """Return supported features."""
+            return 1
+
+    entity = MockFan()
+    assert entity.supported_features_compat is FanEntityFeature(1)
+    assert "MockFan" in caplog.text
+    assert "is using deprecated supported features values" in caplog.text
+    assert "Instead it should use" in caplog.text
+    assert "FanEntityFeature.SET_SPEED" in caplog.text
+    caplog.clear()
+    assert entity.supported_features_compat is FanEntityFeature(1)
+    assert "is using deprecated supported features values" not in caplog.text