Deprecate has_mean in favor of mean_type in recorder statistic API (home-assistant#154093)

Author: emontnemery

homeassistant/components/recorder/core.py

@@ -78,13 +78,7 @@
     StatisticsShortTerm,
 )
 from .executor import DBInterruptibleThreadPoolExecutor
-from .models import (
-    DatabaseEngine,
-    StatisticData,
-    StatisticMeanType,
-    StatisticMetaData,
-    UnsupportedDialect,
-)
+from .models import DatabaseEngine, StatisticData, StatisticMetaData, UnsupportedDialect
 from .pool import POOL_SIZE, MutexPool, RecorderPool
 from .table_managers.event_data import EventDataManager
 from .table_managers.event_types import EventTypeManager
@@ -621,17 +615,6 @@ def async_import_statistics(
         table: type[Statistics | StatisticsShortTerm],
     ) -> None:
         """Schedule import of statistics."""
-        if "mean_type" not in metadata:
-            # Backwards compatibility for old metadata format
-            # Can be removed after 2026.4
-            metadata["mean_type"] = (  # type: ignore[unreachable]
-                StatisticMeanType.ARITHMETIC
-                if metadata.get("has_mean")
-                else StatisticMeanType.NONE
-            )
-        # Remove deprecated has_mean as it's not needed anymore in core
-        metadata.pop("has_mean", None)
-
         self.queue_task(ImportStatisticsTask(metadata, stats, table))
 
     @callback

homeassistant/components/recorder/statistics.py

@@ -2595,6 +2595,13 @@ def _async_import_statistics(
     statistics: Iterable[StatisticData],
 ) -> None:
     """Validate timestamps and insert an import_statistics job in the queue."""
+    if "mean_type" not in metadata:
+        metadata["mean_type"] = (  # type: ignore[unreachable]
+            StatisticMeanType.ARITHMETIC
+            if metadata.pop("has_mean", False)
+            else StatisticMeanType.NONE
+        )
+
     # If unit class is not set, we try to set it based on the unit of measurement
     # Note: This can't happen from the type checker's perspective, but we need
     # to guard against custom integrations that have not been updated to set
@@ -2661,6 +2668,12 @@ def async_import_statistics(
     if not metadata["source"] or metadata["source"] != DOMAIN:
         raise HomeAssistantError("Invalid source")
 
+    if "mean_type" not in metadata and not _called_from_ws_api:  # type: ignore[unreachable]
+        report_usage(  # type: ignore[unreachable]
+            "doesn't specify mean_type when calling async_import_statistics",
+            breaks_in_ha_version="2026.11",
+            exclude_integrations={DOMAIN},
+        )
     if "unit_class" not in metadata and not _called_from_ws_api:  # type: ignore[unreachable]
         report_usage(  # type: ignore[unreachable]
             "doesn't specify unit_class when calling async_import_statistics",
@@ -2692,6 +2705,12 @@ def async_add_external_statistics(
     if not metadata["source"] or metadata["source"] != domain:
         raise HomeAssistantError("Invalid source")
 
+    if "mean_type" not in metadata and not _called_from_ws_api:  # type: ignore[unreachable]
+        report_usage(  # type: ignore[unreachable]
+            "doesn't specify mean_type when calling async_import_statistics",
+            breaks_in_ha_version="2026.11",
+            exclude_integrations={DOMAIN},
+        )
     if "unit_class" not in metadata and not _called_from_ws_api:  # type: ignore[unreachable]
         report_usage(  # type: ignore[unreachable]
             "doesn't specify unit_class when calling async_add_external_statistics",

homeassistant/components/recorder/websocket_api.py

@@ -544,7 +544,11 @@ def valid_units(
     {
         vol.Required("type"): "recorder/import_statistics",
         vol.Required("metadata"): {
-            vol.Required("has_mean"): bool,
+            vol.Optional("has_mean"): bool,
+            vol.Optional("mean_type"): vol.All(
+                vol.In(StatisticMeanType.__members__.values()),
+                vol.Coerce(StatisticMeanType),
+            ),
             vol.Required("has_sum"): bool,
             vol.Required("name"): vol.Any(str, None),
             vol.Required("source"): str,
@@ -574,10 +578,12 @@ def ws_import_statistics(
     The unit_class specifies which unit conversion class to use, if applicable.
     """
     metadata = msg["metadata"]
-    # The WS command will be changed in a follow up PR
-    metadata["mean_type"] = (
-        StatisticMeanType.ARITHMETIC if metadata["has_mean"] else StatisticMeanType.NONE
-    )
+    if "mean_type" not in metadata:
+        _LOGGER.warning(
+            "WS command recorder/import_statistics called without specifying "
+            "mean_type in metadata, this is deprecated and will stop working "
+            "in HA Core 2026.11"
+        )
     if "unit_class" not in metadata:
         _LOGGER.warning(
             "WS command recorder/import_statistics called without specifying "

tests/components/energy/test_websocket_api.py

@@ -7,6 +7,7 @@
 
 from homeassistant.components.energy import data, is_configured
 from homeassistant.components.recorder import Recorder
+from homeassistant.components.recorder.models import StatisticMeanType
 from homeassistant.components.recorder.statistics import async_add_external_statistics
 from homeassistant.core import HomeAssistant
 from homeassistant.setup import async_setup_component
@@ -365,8 +366,8 @@ async def test_fossil_energy_consumption_no_co2(
         },
     )
     external_energy_metadata_1 = {
-        "has_mean": False,
         "has_sum": True,
+        "mean_type": StatisticMeanType.NONE,
         "name": "Total imported energy",
         "source": "test",
         "statistic_id": "test:total_energy_import_tariff_1",
@@ -400,8 +401,8 @@ async def test_fossil_energy_consumption_no_co2(
         },
     )
     external_energy_metadata_2 = {
-        "has_mean": False,
         "has_sum": True,
+        "mean_type": StatisticMeanType.NONE,
         "name": "Total imported energy",
         "source": "test",
         "statistic_id": "test:total_energy_import_tariff_2",
@@ -532,8 +533,8 @@ async def test_fossil_energy_consumption_hole(
         },
     )
     external_energy_metadata_1 = {
-        "has_mean": False,
         "has_sum": True,
+        "mean_type": StatisticMeanType.NONE,
         "name": "Total imported energy",
         "source": "test",
         "statistic_id": "test:total_energy_import_tariff_1",
@@ -567,8 +568,8 @@ async def test_fossil_energy_consumption_hole(
         },
     )
     external_energy_metadata_2 = {
-        "has_mean": False,
         "has_sum": True,
+        "mean_type": StatisticMeanType.NONE,
         "name": "Total imported energy",
         "source": "test",
         "statistic_id": "test:total_energy_import_tariff_2",
@@ -697,8 +698,8 @@ async def test_fossil_energy_consumption_no_data(
         },
     )
     external_energy_metadata_1 = {
-        "has_mean": False,
         "has_sum": True,
+        "mean_type": StatisticMeanType.NONE,
         "name": "Total imported energy",
         "source": "test",
         "statistic_id": "test:total_energy_import_tariff_1",
@@ -732,8 +733,8 @@ async def test_fossil_energy_consumption_no_data(
         },
     )
     external_energy_metadata_2 = {
-        "has_mean": False,
         "has_sum": True,
+        "mean_type": StatisticMeanType.NONE,
         "name": "Total imported energy",
         "source": "test",
         "statistic_id": "test:total_energy_import_tariff_2",
@@ -851,8 +852,8 @@ async def test_fossil_energy_consumption(
         },
     )
     external_energy_metadata_1 = {
-        "has_mean": False,
         "has_sum": True,
+        "mean_type": StatisticMeanType.NONE,
         "name": "Total imported energy",
         "source": "test",
         "statistic_id": "test:total_energy_import_tariff_1",
@@ -886,8 +887,8 @@ async def test_fossil_energy_consumption(
         },
     )
     external_energy_metadata_2 = {
-        "has_mean": False,
         "has_sum": True,
+        "mean_type": StatisticMeanType.NONE,
         "name": "Total imported energy",
         "source": "test",
         "statistic_id": "test:total_energy_import_tariff_2",
@@ -917,8 +918,8 @@ async def test_fossil_energy_consumption(
         },
     )
     external_co2_metadata = {
-        "has_mean": True,
         "has_sum": False,
+        "mean_type": StatisticMeanType.ARITHMETIC,
         "name": "Fossil percentage",
         "source": "test",
         "statistic_id": "test:fossil_percentage",
@@ -1105,8 +1106,8 @@ async def test_fossil_energy_consumption_check_missing_hour(
         },
     )
     energy_metadata_1 = {
-        "has_mean": False,
         "has_sum": True,
+        "mean_type": StatisticMeanType.NONE,
         "name": "Total imported energy",
         "source": "test",
         "statistic_id": "test:total_energy_import",
@@ -1140,8 +1141,8 @@ async def test_fossil_energy_consumption_check_missing_hour(
         },
     )
     co2_metadata = {
-        "has_mean": True,
         "has_sum": False,
+        "mean_type": StatisticMeanType.ARITHMETIC,
         "name": "Fossil percentage",
         "source": "test",
         "statistic_id": "test:fossil_percentage",
@@ -1202,8 +1203,8 @@ async def test_fossil_energy_consumption_missing_sum(
         {"start": period4, "last_reset": None, "state": 3, "mean": 5},
     )
     external_energy_metadata_1 = {
-        "has_mean": True,
         "has_sum": False,
+        "mean_type": StatisticMeanType.ARITHMETIC,
         "name": "Mean imported energy",
         "source": "test",
         "statistic_id": "test:mean_energy_import_tariff",

tests/components/kitchen_sink/test_init.py

@@ -83,7 +83,7 @@ async def test_demo_statistics_growth(hass: HomeAssistant) -> None:
         "statistic_id": statistic_id,
         "unit_class": "volume",
         "unit_of_measurement": "m³",
-        "has_mean": False,
+        "mean_type": StatisticMeanType.NONE,
         "has_sum": True,
     }
     statistics = [

tests/components/opower/test_coordinator.py

@@ -10,7 +10,11 @@
 from homeassistant.components.opower.const import DOMAIN
 from homeassistant.components.opower.coordinator import OpowerCoordinator
 from homeassistant.components.recorder import Recorder
-from homeassistant.components.recorder.models import StatisticData, StatisticMetaData
+from homeassistant.components.recorder.models import (
+    StatisticData,
+    StatisticMeanType,
+    StatisticMetaData,
+)
 from homeassistant.components.recorder.statistics import (
     async_add_external_statistics,
     get_last_statistics,
@@ -186,6 +190,7 @@ async def test_coordinator_migration(
     statistic_id = "opower:pge_elec_111111_energy_consumption"
     metadata = StatisticMetaData(
         has_sum=True,
+        mean_type=StatisticMeanType.NONE,
         name="Opower pge elec 111111 consumption",
         source=DOMAIN,
         statistic_id=statistic_id,

tests/components/recorder/auto_repairs/statistics/test_duplicates.py

@@ -14,6 +14,7 @@
     delete_statistics_duplicates,
     delete_statistics_meta_duplicates,
 )
+from homeassistant.components.recorder.models import StatisticMeanType
 from homeassistant.components.recorder.statistics import async_add_external_statistics
 from homeassistant.components.recorder.util import session_scope
 from homeassistant.core import HomeAssistant
@@ -59,8 +60,8 @@ async def test_duplicate_statistics_handle_integrity_error(
     period2 = dt_util.as_utc(dt_util.parse_datetime("2021-09-30 23:00:00"))
 
     external_energy_metadata_1 = {
-        "has_mean": False,
         "has_sum": True,
+        "mean_type": StatisticMeanType.NONE,
         "name": "Total imported energy",
         "source": "test",
         "statistic_id": "test:total_energy_import_tariff_1",