From 76f6b1ac085a5136cb3abf2b4581132261dfc9dd Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Thu, 15 Jul 2021 15:47:48 +0200 Subject: [PATCH] Further tweak documentation about _attr-style shorthand for properties (#1000) * Further tweak documentation about _attr-style shorthand for properties * Update entity.md * Update air-quality.md * Update entity.md * Update air-quality.md * Update air-quality.md * Update device-tracker.md * Update device-tracker.md * Update fan.md * Update vacuum.md * Update entity.md * Update entity.md * Move the example to a separate PR --- docs/core/entity.md | 17 +++++++++++++---- docs/core/entity/air-quality.md | 5 +++++ docs/core/entity/device-tracker.md | 8 ++++++++ docs/core/entity/fan.md | 4 ++++ docs/core/entity/vacuum.md | 4 ++++ 5 files changed, 34 insertions(+), 4 deletions(-) diff --git a/docs/core/entity.md b/docs/core/entity.md index ce2815ab..7d7cd406 100644 --- a/docs/core/entity.md +++ b/docs/core/entity.md @@ -89,7 +89,9 @@ The following properties are used and controlled by Home Assistant, and should n | ------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | enabled | boolean | `True` | Indicate if entity is enabled in the entity registry. It also returns `True` if the platform doesn't support the entity registry. Disabled entities will not be added to Home Assistant. | -## Entity class or instance attributes +## Property implementation + +### Property function Writing property methods for each property is just a couple of lines of code, for example @@ -105,6 +107,8 @@ class MySwitch(SwitchEntity): ... ``` +### Entity class or instance attributes + Alternatively, a shorter form is to set Entity class or instance attributes according to either of the following patterns: @@ -125,9 +129,14 @@ class MySwitch(SwitchEntity): ... ``` -This does exactly the same as the first example. Properties that can be set -like this, start with `_attr_` followed by the property name. For example, -the `device_class` property, has the `_attr_device_class` class attribute. +This does exactly the same as the first example but relies on a default +implementation of the property in the base class. The name of the attribute +starts with `_attr_` followed by the property name. For example, the default +`device_class` property returns the `_attr_device_class` class attribute. + +Not all entity classes support the `_attr_` attributes for their entity +specific properties, please refer to the documentation for the respective +entity class for details. :::tip 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`). diff --git a/docs/core/entity/air-quality.md b/docs/core/entity/air-quality.md index fd2ee615..6461ba99 100644 --- a/docs/core/entity/air-quality.md +++ b/docs/core/entity/air-quality.md @@ -12,6 +12,11 @@ separate sensors for these measurements. Integrations that still rely on the Air Quality Entity should be migrated. ::: +:::caution +The Air Quality entity does not support attribute shorthand for [property implementation](../entity.md#entity-class-or-instance-attributes) +::: + + | Name | Type | Default | Description | ---- | ---- | ------- | ----------- | particulate_matter_2_5 | float | **Required** | The particulate matter 2.5 (<= 2.5 μm) level. diff --git a/docs/core/entity/device-tracker.md b/docs/core/entity/device-tracker.md index bd7df163..e0a4ba64 100644 --- a/docs/core/entity/device-tracker.md +++ b/docs/core/entity/device-tracker.md @@ -17,6 +17,10 @@ Derive a platform entity from [`homeassistant.components.device_tracker.config_e Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. ::: +:::caution +ScannerEntity does not support attribute shorthand for [property implementation](../entity.md#entity-class-or-instance-attributes) +::: + | Name | Type | Default | Description | | ------------- | ------- | ------------ | ------------------------------------------------- | | source_type | string | **Required** | The source type, eg `gps` or `router`, of the device. | @@ -44,6 +48,10 @@ Derive a platform entity from [`homeassistant.components.device_tracker.config_e Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. ::: +:::caution +TrackerEntity does not support attribute shorthand for [property implementation](../entity.md#entity-class-or-instance-attributes) +::: + | Name | Type | Default | Description | | ----------------- | ------- | ------------ | ------------------------------------------------- | | source_type | string | **Required** | The source type, eg `gps` or `router`, of the device. | diff --git a/docs/core/entity/fan.md b/docs/core/entity/fan.md index 38aa2236..dbda3cb9 100644 --- a/docs/core/entity/fan.md +++ b/docs/core/entity/fan.md @@ -11,6 +11,10 @@ A fan entity is a device that controls the different vectors of your fan such as Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. ::: +:::caution +FanEntity does not support attribute shorthand for [property implementation](../entity.md#entity-class-or-instance-attributes) +::: + | Name | Type | Default | Description | ---- | ---- | ------- | ----------- | current_direction | str | None | Return the current direction of the fan | diff --git a/docs/core/entity/vacuum.md b/docs/core/entity/vacuum.md index 331018f3..a7a8f90d 100644 --- a/docs/core/entity/vacuum.md +++ b/docs/core/entity/vacuum.md @@ -9,6 +9,10 @@ sidebar_label: Vacuum Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. ::: +:::caution +VacuumEntity and StateVacuumEntity do not support attribute shorthand for [property implementation](../entity.md#entity-class-or-instance-attributes) +::: + | Name | Type | Default | Description | ---- | ---- | ------- | ----------- | name | string | **Required** | Name of the device.