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
This commit is contained in:
Erik Montnemery 2021-07-15 15:47:48 +02:00 committed by GitHub
parent a0878e40f5
commit 76f6b1ac08
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 34 additions and 4 deletions

View File

@ -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`).

View File

@ -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.

View File

@ -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. |

View File

@ -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 |

View File

@ -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.