feat: Added the ability to update data source data updates via raised events (2 hours dev time)

Author: BottlecapDave

_docs/events.md

@@ -1,3 +1,23 @@
 # Events
 
-The following events are raised by the integration. These events power various entities and can also be used within automations.
+The following events are either raised or received by the integration. These events power various entities and can also be used within automations.
+
+## Update Data Source
+
+`target_timeframe_update_data_source`
+
+Data sources listen for this event and then update the data based on the provided data if the `data_source_id` matches the data source's id.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `data_source_id` | `string` | The id of the data source the data belongs to |
+| `data` | `array` | The data to update the data source with |
+
+For each item in `data`, the following attributes should be present
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `start` | `datetime` | The start timestamp the value is effective from |
+| `end` | `datetime` | The end timestamp the value is effective to |
+| `value` | `float` | The value that is applicable for the timeframe. This could be something like an electricity rate |
+| `metadata` | `object` | Additional metadata that might describe how the value was created |

_docs/setup/data_source.md

@@ -10,12 +10,16 @@ The name of the data source. This is for informative purposes.
 
 ### Id
 
-The unique identifier of the data source. This is used by internal events to ensure sensors use the correct data as well as part of the entity name of all related entities. For example, if you were using data provided by Octopus Energy, then this might be `octopus_energy`.
+The unique identifier of the data source. This is used by internal events to ensure sensors use the correct data as well as part of the entity name of all related entities.
 
-Once the data source has been created, you'll have the following entities created. You'll then need to use the [available service](../services.md#target_timeframesupdate_target_timeframe_data_source) to configure the underlying data. There are also a collection of [blueprints](../blueprints.md#data-sources) available for loading popular data sources.
+The data source will listen for the [update data source event](../events.md#update-data-source) where the `data source id` matches this id. This event might be raised by other integrations. If this data source is being used for this purpose, then the id will need to be set to a certain value which should be highlighted in that integrations guide.
+
+Alternatively, you can use the [available service](../services.md#target_timeframesupdate_target_timeframe_data_source) to configure the underlying data. There is a collection of [blueprints](../blueprints.md#data-sources) available for loading data from popular data sources.
 
 ## Entities
 
+Once the data source has been created, you'll have the following entities created.
+
 ### Data Source Last Updated
 
 `sensor.target_timeframes_{{DATA_SOURCE_ID}}_data_source_last_updated`

custom_components/target_timeframes/const.py

@@ -185,4 +185,5 @@
   ),
 })
 
-EVENT_DATA_SOURCE = "target_time_period_data_source_updated"
+EVENT_DATA_SOURCE = "target_time_period_data_source_updated"
+EVENT_UPDATE_DATA_SOURCE = "target_timeframe_update_data_source"

custom_components/target_timeframes/entities/data_source.py

@@ -17,7 +17,7 @@
 from homeassistant.helpers.entity import generate_entity_id
 
 from ..utils.attributes import dict_to_typed_dict
-from ..const import DOMAIN, EVENT_DATA_SOURCE
+from ..const import DOMAIN, EVENT_DATA_SOURCE, EVENT_UPDATE_DATA_SOURCE
 from ..storage.data_source_data import async_save_cached_data_source_data
 from ..utils.data_source_data import DataSourceItem, merge_data_source_data, validate_data_source_data
 
@@ -67,6 +67,11 @@ def extra_state_attributes(self):
   @property
   def native_value(self):
     return self._state
+  
+  @callback
+  async def _async_handle_event(self, event) -> None:
+    if event.data.get("data_source_id", '').lower() == self._source_id.lower():
+      await self.async_update_target_timeframe_data_source(event.data.get("data", []))
 
   async def async_added_to_hass(self):
     """Call when entity about to be added to hass."""
@@ -81,6 +86,10 @@ async def async_added_to_hass(self):
 
       _LOGGER.debug(f'Restored state: {self._state}')
 
+    self.async_on_remove(
+      self._hass.bus.async_listen(EVENT_UPDATE_DATA_SOURCE, self._async_handle_event)
+    )
+
   @callback
   async def async_update_target_timeframe_data_source(self, data, replace_all_existing_data = False):
     """Update target timeframe data source"""

custom_components/target_timeframes/utils/data_source_data.py

@@ -1,3 +1,4 @@
+from copy import Error
 from datetime import datetime, timedelta
 from typing import Any
 
@@ -19,7 +20,7 @@ def __init__(self, success: bool, data_source_id: str, data: list[DataSourceItem
 
 def validate_data_source_data(items: list[dict], data_source_id: str):
   if items is None or len(items) < 1:
-    return ValidateDataSourceDataResult(True, [])
+    return ValidateDataSourceDataResult(True, data_source_id, [])
 
   processed_data_source = []
   for index in range(len(items)):
@@ -28,7 +29,14 @@ def validate_data_source_data(items: list[dict], data_source_id: str):
 
     start = None
     try:
-      start = datetime.fromisoformat(item["start"])
+      if "start" not in item:
+        error = f"start is missing at index {index}"
+        break
+      
+      if isinstance(item["start"], datetime):
+        start = item["start"]
+      else:
+        start = datetime.fromisoformat(item["start"])
     except:
       error = f"start was not a valid ISO datetime in string format at index {index}"
       break
@@ -39,7 +47,14 @@ def validate_data_source_data(items: list[dict], data_source_id: str):
 
     end = None
     try:
-      end = datetime.fromisoformat(item["end"])
+      if "end" not in item:
+        error = f"end is missing at index {index}"
+        break
+      
+      if isinstance(item["end"], datetime):
+        end = item["end"]
+      else:
+        end = datetime.fromisoformat(item["end"])
     except:
       error = f"end was not a valid ISO datetime in string format at index {index}"
       break