From 427d437ac5a3cbfd79c9beb6945c0297d3fdce91 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Mon, 24 Jan 2022 14:31:38 +0100 Subject: [PATCH] Add examples of entity property methods vs attributes (#1004) Co-authored-by: Tobias Sauerwein --- docs/core/entity.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/core/entity.md b/docs/core/entity.md index b328822d..b033267d 100644 --- a/docs/core/entity.md +++ b/docs/core/entity.md @@ -144,6 +144,34 @@ entity class for details. If an integration needs to access its own properties it should access the property (`self.name`), not the class or instance attribute (`self._attr_name`). ::: +### Example + +The below code snippet gives an example of best practices for when to implement property functions, and when to use class or instance attributes. + +```py +class SomeEntity(): + _attr_device_clas = DEVICE_CLASS_TEMPERATURE # This will be common to all instances of SomeEntity + def __init__(self, device): + self._device = device + self._attr_available = False # This overrides the default + self._attr_name = device.get_friendly_name() + + # The following should be avoided: + if some_complex_condition and some_other_condition and something_is_none_and_only_valid_after_update and device_available: + ... + + def update(self) + if self.available # Read current state, no need to prefix with _attr_ + # Update the entity + self._device.update() + + if error: + self._attr_available = False # Set property value + return + # We don't need to check if device available here + self._attr_is_on = self._device.get_state() # Update "is_on" property +``` + ## Lifecycle hooks Use these lifecycle hooks to execute code when certain events happen to the entity. All lifecycle hooks are async methods.