State Helpers¶
These helpers can be used to retrieve the state of entities from Home Assistant.
is_on
¶
is_on(entity_id: str) -> bool
Returns True
if the state of the given entity is "on"
(case-insensitive), False
otherwise.
is_off
¶
is_off(entity_id: str) -> bool
Returns True
if the state of the given entity is "off"
(case-insensitive), False
otherwise.
Note
There is a difference between using is_off(...)
and not
is_on(...)
. These helper functions only compare the state of the
specified entity to the values "off"
and "on"
, respectively. If
you want to treat a non-existing entity (which’s state is returned as
None
) as if it was "off"
, you have to use not is_on(...)
since is_off(...)
would return False
in this case.
state
¶
state(entity_id: str = None, attribute: str = None) -> Any
A shortcut for app.get_state()
.
It generates a warning when an entity is queried for which no watch has
been configured via watched_entities
. That’s why you should always
use this helper instead of calling app.get_state()
directly.
filter_entities
¶
filter_entities(entities: Union[str, List[str]] = None, **criteria: Any) -> Iterable[str]
From a given set of entities, this function yields only those with a state and/or attributes matching all given criteria.
Entities may either be specified as a single string (full entity id or
domain), a list of such strings, or as None
, which means all entities
found in Home Assistant.
Examples:
# entities with a state of "on"
for entity in filter_entities(state="on"):
...
# binary_sensor and input_boolean entities having a room attribute with the value "living"
for entity in filter_entities(["binary_sensor", "input_boolean"], room="living"):
...