Document entity.has_entity_name (#1387)

* Update entity.md

* Tweak

Co-authored-by: Franck Nijhof <git@frenck.dev>
This commit is contained in:
Erik Montnemery 2022-07-08 10:01:03 +02:00 committed by GitHub
parent 50f7cf2e26
commit 6fd2d1babe
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -14,6 +14,8 @@ from homeassistant.components.switch import SwitchEntity
class MySwitch(SwitchEntity):
_attr_has_entity_name = True
def __init__(self):
self._is_on = False
@ -69,6 +71,7 @@ Properties should always only return information from memory and not do I/O (lik
| entity_category | string | `None` | Classification of a non-primary entity. Set to `config` for an entity which allows changing the configuration of a device, for example a switch entity making it possible to turn the background illumination of a switch on and off. Set to `diagnostic` for an entity exposing some configuration parameter or diagnostics of a device but does not allow changing it, for example a sensor showing RSSI or MAC-address. |
| entity_picture | URL | `None` | Url of a picture to show for the entity. |
| extra_state_attributes | dict | `None` | Extra information to store in the state machine. It needs to be information that further explains the state, it should not be static information like firmware version. |
| has_entity_name | boolean | | Return `True` if the entity's `name` property represents the entity itself (required for new integrations). This is explained in more detail below.
| name | string | `None` | Name of the entity |
| should_poll | boolean | `True` | Should Home Assistant check with the entity for an updated state. If set to `False`, entity will need to notify Home Assistant of new updates by calling one of the [schedule update methods](integration_fetching_data.md#push-vs-poll). |
| unique_id | string | `None` | A unique identifier for this entity. Needs to be unique within a platform (ie `light.hue`). Should not be configurable by the user or be changeable. [Learn more.](entity_registry_index.md#unique-id-requirements) |
@ -96,6 +99,25 @@ 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 naming
### `has_entity_name` True (Mandatory for new integrations)
The entity's name property only identifies the data point represented by the entity, and should not include the name of the device or the type of the entity. So for a sensor that represents the power usage of its device, this would be “Power usage”.
The main entity of a device may have its name property return `None`.
The `friendly_name` state attribute is generated by combining then entity name with the device name as follows:
- The entity is not a member of a device: `friendly_name = entity.name`
- The entity is a member of a device and `entity.name` is not `None`: `friendly_name = f"{device.name} {entity.name}"`
- The entity is a member of a device and `entity.name` is `None`: `friendly_name = f"{device.name}"`
Entity names should start with a capital letter, the rest of the words are lower case (unless it's a proper noun or a capitalized abbreviation of course).
### `has_entity_name` not implemented or False (Deprecated)
The entity's name property may be a combination of the device name and the data point represented by the entity.
## Property implementation
### Property function