entities

class platypush.plugins.entities.EntitiesPlugin(**kwargs)

Bases: Plugin

This plugin is used to interact with native platform entities (e.g. switches, lights, sensors etc.) through a consistent interface, regardless of the integration type.

__init__(**kwargs)

delete(*entities: int)

Delete a set of entity IDs.

Note: this should only be done if the entity is no longer available or the associated plugin has been disabled, otherwise the entities will be re-created by the plugins on the next scan.

Parameters:

entities – IDs of the entities to be removed.

Returns:

The payload of the deleted entities.

execute(id: Any, action: str, *args, **kwargs)

Execute an action on an entity (for example on/off on a switch, or get on a sensor).

Parameters:

• id – Entity ID (i.e. the entity’s db primary key, not the plugin’s external or “logical” key)

• action – Action that should be run. It should be a method implemented by the entity’s class.

• args – Action’s extra positional arguments.

• kwargs – Action’s extra named arguments.

get(types: Collection[str] | None = None, plugins: Collection[str] | None = None, **filter)

Retrieve a list of entities.

Parameters:

• types – Entity types, as specified by the (lowercase) class name and table name. Default: all entities.

• plugins – Filter by plugin IDs (default: all plugins).

• filter – Filter entities with these criteria (e.g. name, id, state, type, plugin etc.)

rename(**entities: Mapping[str, str])

Rename a sequence of entities. Renaming, as of now, is actually done by setting the .meta.name_override property of an entity rather than fully renaming the entity (which may be owned by a plugin that doesn’t support renaming, therefore the next entity update may overwrite the name).

Parameters:

entities – Entity id -> new_name mapping.

scan(types: Collection[str] | None = None, plugins: Collection[str] | None = None, timeout: float | None = 30.0)

(Re-)scan entities and return the updated results.

Parameters:

• types – Filter by entity types (e.g. switch, light, sensor etc.).

• plugins – Filter by plugin names (e.g. switch.tplink or light.hue).

• timeout – Scan timeout in seconds. Default: 30.

set_meta(**entities)

Update the metadata of a set of entities.

Parameters:

entities – Entity id -> new_metadata_fields mapping.

Returns:

The updated entities.