The entity class

Every entity in Home Assistant is a Python object that inherits from Entity in homeassistant.helpers.entity. You almost never inherit from Entity directly, though. You inherit from the base class of an entity platform, like SwitchEntity or SensorEntity. That class adds the properties and methods of its domain on top of the generic ones described here.

This switch keeps its state in memory. It is the main feature of its device, so it takes the name of the device.

from typing import Any

from homeassistant.components.switch import SwitchEntity
from homeassistant.helpers.device_registry import DeviceInfo

from .const import DOMAIN


class ExampleSwitch(SwitchEntity):
    """A switch that remembers if it is on."""

    _attr_has_entity_name = True
    _attr_name = None
    _attr_is_on = False

    def __init__(self, serial: str) -> None:
        """Initialize the switch."""
        self._attr_unique_id = serial
        self._attr_device_info = DeviceInfo(
            identifiers={(DOMAIN, serial)},
            name="Garden pump",
        )

    async def async_turn_on(self, **kwargs: Any) -> None:
        """Turn the switch on."""
        self._attr_is_on = True
        self.async_write_ha_state()

    async def async_turn_off(self, **kwargs: Any) -> None:
        """Turn the switch off."""
        self._attr_is_on = False
        self.async_write_ha_state()

The rest of this page, and the other pages in this group, explain each part of that example.

Home Assistant reads the properties of your entity every time it writes the state. You can provide a property in three ways. They all end up in the same place, so pick the one that reads best.

Most properties have a default implementation in the base class that returns an attribute with the same name and an _attr_ prefix. The device_class property returns self._attr_device_class, the is_on property of a switch returns self._attr_is_on, and so on. Set them as class attributes when they never change, or as instance attributes when they do.

class ExampleSwitch(SwitchEntity):
    _attr_icon = "mdi:water-pump"

    def __init__(self, serial: str) -> None:
        self._attr_unique_id = serial

This is the most common style. When your own code needs a value, read the property (self.available), not the attribute (self._attr_available). Not every platform property has an _attr_ attribute: the page of each platform says so when it doesn't.

When a value has to be calculated, override the property itself.

class ExampleSwitch(SwitchEntity):
    @property
    def is_on(self) -> bool:
        """Return if the pump is running."""
        return self._device.pump_speed > 0

An entity description is a frozen dataclass that holds the static properties of one kind of entity. Every platform has its own subclass, like SensorEntityDescription. Set it as self.entity_description, and the base class reads properties like device_class, translation_key, and entity_category from it.

The only required field is key, a string that is unique within your platform. It is a good building block for the unique ID.

Descriptions shine when one class serves many entities that only differ in their settings. You declare them in a tuple, and loop over it during setup.

from collections.abc import Callable
from dataclasses import dataclass

from homeassistant.components.sensor import (
    SensorDeviceClass,
    SensorEntity,
    SensorEntityDescription,
    SensorStateClass,
)
from homeassistant.const import UnitOfTemperature
from homeassistant.helpers.typing import StateType


@dataclass(frozen=True, kw_only=True)
class ExampleSensorEntityDescription(SensorEntityDescription):
    """Describes an Example sensor."""

    value_fn: Callable[[ExampleDevice], StateType]


SENSORS: tuple[ExampleSensorEntityDescription, ...] = (
    ExampleSensorEntityDescription(
        key="water_temperature",
        translation_key="water_temperature",
        device_class=SensorDeviceClass.TEMPERATURE,
        native_unit_of_measurement=UnitOfTemperature.CELSIUS,
        state_class=SensorStateClass.MEASUREMENT,
        value_fn=lambda device: device.water_temperature,
    ),
)


class ExampleSensor(SensorEntity):
    """A sensor of an Example device."""

    entity_description: ExampleSensorEntityDescription
    _attr_has_entity_name = True

    def __init__(
        self,
        device: ExampleDevice,
        description: ExampleSensorEntityDescription,
    ) -> None:
        """Initialize the sensor."""
        self._device = device
        self.entity_description = description
        self._attr_unique_id = f"{device.serial}_{description.key}"

    @property
    def native_value(self) -> StateType:
        """Return the value from the device."""
        return self.entity_description.value_fn(self._device)

An _attr_ attribute wins over the description. So you can share a description and still override one value for a single entity.

These properties exist on every entity. All of them are optional.

Leave name unset when the entity should get its name from its translation key or its device class. Setting _attr_name = None is not the same thing: it explicitly says "this entity has no name of its own".

You may change device_class, supported_features, and the capability attributes of a domain while the entity runs, but do it rarely. Every change updates the entity registry, and some consumers, like voice assistants, resynchronize with their cloud service when they see it. Home Assistant logs a warning when an entity updates its capabilities more than 100 times in an hour.

Some properties belong to the platform base class or to Home Assistant itself.

The properties, features, and states of each domain are shared by every integration that implements it, so changing them is a bigger deal than changing one integration. If you want to add something to a domain, propose it first in the architecture discussions. Additions are considered when they are common across several brands, not when they serve one device.