class platypush.plugins.entities.EntitiesPlugin(**kwargs)[source]#

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.

delete(*entities: int)[source]#

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.


entities – IDs of the entities to be removed.


The payload of the deleted entities.

execute(id: Any, action: str, *args, **kwargs)[source]#

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

  • 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)[source]#

Retrieve a list of entities.

  • 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])[source]#

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


entities – Entity id -> new_name mapping.

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

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

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


Update the metadata of a set of entities.


entities – Entity id -> new_metadata_fields mapping.


The updated entities.