Add geocaching cache sensors (#145453)

homeassistant/components/geocaching/entity.py

@@ -0,0 +1,39 @@
+"""Sensor entities for Geocaching."""
+
+from typing import cast
+
+from geocachingapi.models import GeocachingCache
+
+from homeassistant.helpers.device_registry import DeviceEntryType, DeviceInfo
+from homeassistant.helpers.update_coordinator import CoordinatorEntity
+
+from .const import DOMAIN
+from .coordinator import GeocachingDataUpdateCoordinator
+
+
+# Base class for all platforms
+class GeocachingBaseEntity(CoordinatorEntity[GeocachingDataUpdateCoordinator]):
+    """Base class for Geocaching sensors."""
+
+    _attr_has_entity_name = True
+
+
+# Base class for cache entities
+class GeocachingCacheEntity(GeocachingBaseEntity):
+    """Base class for Geocaching cache entities."""
+
+    def __init__(
+        self, coordinator: GeocachingDataUpdateCoordinator, cache: GeocachingCache
+    ) -> None:
+        """Initialize the Geocaching cache entity."""
+        super().__init__(coordinator)
+        self.cache = cache
+
+        # A device can have multiple entities, and for a cache which requires multiple entities we want to group them together.
+        # Therefore, we create a device for each cache, which holds all related entities.
+        self._attr_device_info = DeviceInfo(
+            name=f"Geocache {cache.name}",
+            identifiers={(DOMAIN, cast(str, cache.reference_code))},
+            entry_type=DeviceEntryType.SERVICE,
+            manufacturer=cache.owner.username,
+        )

homeassistant/components/geocaching/icons.json

@@ -15,6 +15,24 @@
       },
       "awarded_favorite_points": {
         "default": "mdi:heart"
+      },
+      "cache_name": {
+        "default": "mdi:label"
+      },
+      "cache_owner": {
+        "default": "mdi:account"
+      },
+      "cache_found_date": {
+        "default": "mdi:calendar-search"
+      },
+      "cache_found": {
+        "default": "mdi:package-variant-closed-check"
+      },
+      "cache_favorite_points": {
+        "default": "mdi:star-check"
+      },
+      "cache_hidden_date": {
+        "default": "mdi:calendar-badge"
       }
     }
   }

homeassistant/components/geocaching/sensor.py

@@ -4,18 +4,25 @@ from __future__ import annotations
 
 from collections.abc import Callable
 from dataclasses import dataclass
+import datetime
 from typing import cast
 
-from geocachingapi.models import GeocachingStatus
+from geocachingapi.models import GeocachingCache, GeocachingStatus
 
-from homeassistant.components.sensor import SensorEntity, SensorEntityDescription
+from homeassistant.components.sensor import (
+    SensorDeviceClass,
+    SensorEntity,
+    SensorEntityDescription,
+)
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.device_registry import DeviceEntryType, DeviceInfo
+from homeassistant.helpers.entity import Entity
 from homeassistant.helpers.entity_platform import AddConfigEntryEntitiesCallback
-from homeassistant.helpers.update_coordinator import CoordinatorEntity
+from homeassistant.helpers.typing import StateType
 
 from .const import DOMAIN
 from .coordinator import GeocachingConfigEntry, GeocachingDataUpdateCoordinator
+from .entity import GeocachingBaseEntity, GeocachingCacheEntity
 
 
 @dataclass(frozen=True, kw_only=True)
@@ -25,43 +32,63 @@ class GeocachingSensorEntityDescription(SensorEntityDescription):
     value_fn: Callable[[GeocachingStatus], str | int | None]
 
 
-SENSORS: tuple[GeocachingSensorEntityDescription, ...] = (
+PROFILE_SENSORS: tuple[GeocachingSensorEntityDescription, ...] = (
     GeocachingSensorEntityDescription(
         key="find_count",
         translation_key="find_count",
-        native_unit_of_measurement="caches",
         value_fn=lambda status: status.user.find_count,
     ),
     GeocachingSensorEntityDescription(
         key="hide_count",
         translation_key="hide_count",
-        native_unit_of_measurement="caches",
         entity_registry_visible_default=False,
         value_fn=lambda status: status.user.hide_count,
     ),
     GeocachingSensorEntityDescription(
         key="favorite_points",
         translation_key="favorite_points",
-        native_unit_of_measurement="points",
         entity_registry_visible_default=False,
         value_fn=lambda status: status.user.favorite_points,
     ),
     GeocachingSensorEntityDescription(
         key="souvenir_count",
         translation_key="souvenir_count",
-        native_unit_of_measurement="souvenirs",
         value_fn=lambda status: status.user.souvenir_count,
     ),
     GeocachingSensorEntityDescription(
         key="awarded_favorite_points",
         translation_key="awarded_favorite_points",
-        native_unit_of_measurement="points",
         entity_registry_visible_default=False,
         value_fn=lambda status: status.user.awarded_favorite_points,
     ),
 )
 
 
+@dataclass(frozen=True, kw_only=True)
+class GeocachingCacheSensorDescription(SensorEntityDescription):
+    """Define Sensor entity description class."""
+
+    value_fn: Callable[[GeocachingCache], StateType | datetime.date]
+
+
+CACHE_SENSORS: tuple[GeocachingCacheSensorDescription, ...] = (
+    GeocachingCacheSensorDescription(
+        key="found_date",
+        device_class=SensorDeviceClass.DATE,
+        value_fn=lambda cache: cache.found_date_time,
+    ),
+    GeocachingCacheSensorDescription(
+        key="favorite_points",
+        value_fn=lambda cache: cache.favorite_points,
+    ),
+    GeocachingCacheSensorDescription(
+        key="hidden_date",
+        device_class=SensorDeviceClass.DATE,
+        value_fn=lambda cache: cache.hidden_date,
+    ),
+)
+
+
 async def async_setup_entry(
     hass: HomeAssistant,
     entry: GeocachingConfigEntry,
@@ -69,14 +96,68 @@ async def async_setup_entry(
 ) -> None:
     """Set up a Geocaching sensor entry."""
     coordinator = entry.runtime_data
-    async_add_entities(
-        GeocachingSensor(coordinator, description) for description in SENSORS
+
+    entities: list[Entity] = []
+
+    entities.extend(
+        GeocachingProfileSensor(coordinator, description)
+        for description in PROFILE_SENSORS
     )
 
+    status = coordinator.data
 
-class GeocachingSensor(
-    CoordinatorEntity[GeocachingDataUpdateCoordinator], SensorEntity
-):
+    # Add entities for tracked caches
+    entities.extend(
+        GeoEntityCacheSensorEntity(coordinator, cache, description)
+        for cache in status.tracked_caches
+        for description in CACHE_SENSORS
+    )
+
+    async_add_entities(entities)
+
+
+# Base class for a cache entity.
+# Sets the device, ID and translation settings to correctly group the entity to the correct cache device and give it the correct name.
+class GeoEntityBaseCache(GeocachingCacheEntity, SensorEntity):
+    """Base class for cache entities."""
+
+    def __init__(
+        self,
+        coordinator: GeocachingDataUpdateCoordinator,
+        cache: GeocachingCache,
+        key: str,
+    ) -> None:
+        """Initialize the Geocaching sensor."""
+        super().__init__(coordinator, cache)
+
+        self._attr_unique_id = f"{cache.reference_code}_{key}"
+
+        # The translation key determines the name of the entity as this is the lookup for the `strings.json` file.
+        self._attr_translation_key = f"cache_{key}"
+
+
+class GeoEntityCacheSensorEntity(GeoEntityBaseCache, SensorEntity):
+    """Representation of a cache sensor."""
+
+    entity_description: GeocachingCacheSensorDescription
+
+    def __init__(
+        self,
+        coordinator: GeocachingDataUpdateCoordinator,
+        cache: GeocachingCache,
+        description: GeocachingCacheSensorDescription,
+    ) -> None:
+        """Initialize the Geocaching sensor."""
+        super().__init__(coordinator, cache, description.key)
+        self.entity_description = description
+
+    @property
+    def native_value(self) -> StateType | datetime.date:
+        """Return the state of the sensor."""
+        return self.entity_description.value_fn(self.cache)
+
+
+class GeocachingProfileSensor(GeocachingBaseEntity, SensorEntity):
     """Representation of a Sensor."""
 
     entity_description: GeocachingSensorEntityDescription

homeassistant/components/geocaching/strings.json

@@ -33,11 +33,36 @@
   },
   "entity": {
     "sensor": {
-      "find_count": { "name": "Total finds" },
-      "hide_count": { "name": "Total hides" },
-      "favorite_points": { "name": "Favorite points" },
-      "souvenir_count": { "name": "Total souvenirs" },
-      "awarded_favorite_points": { "name": "Awarded favorite points" }
+      "find_count": {
+        "name": "Total finds",
+        "unit_of_measurement": "caches"
+      },
+      "hide_count": {
+        "name": "Total hides",
+        "unit_of_measurement": "caches"
+      },
+      "favorite_points": {
+        "name": "Favorite points",
+        "unit_of_measurement": "points"
+      },
+      "souvenir_count": {
+        "name": "Total souvenirs",
+        "unit_of_measurement": "souvenirs"
+      },
+      "awarded_favorite_points": {
+        "name": "Awarded favorite points",
+        "unit_of_measurement": "points"
+      },
+      "cache_found_date": {
+        "name": "Found date"
+      },
+      "cache_favorite_points": {
+        "name": "Favorite points",
+        "unit_of_measurement": "points"
+      },
+      "cache_hidden_date": {
+        "name": "Hidden date"
+      }
     }
   }
 }