procedures

procedures#

Description#

Utility plugin to run and store procedures as native entities.

param poll_interval:

How often the ProceduresPlugin.loop function should be executed (default: 15 seconds). NOTE: For back-compatibility reasons, the poll_seconds argument is also supported, but it’s deprecated.

param stop_timeout:

How long we should wait for any running threads/processes to stop before exiting (default: 5 seconds).

param disable_monitor:

If set to True then the plugin will not monitor for new events. This is useful if you want to run a plugin in stateless mode and only leverage its actions, without triggering any events. Defaults to False.

Configuration#

procedures:
  # [Optional]
  # How often the `RunnablePlugin.loop <https://docs.platypush.tech/platypush/plugins/.html#platypush.plugins.RunnablePlugin.loop>`_ function should be
  # executed (default: 15 seconds). *NOTE*: For back-compatibility
  # reasons, the `poll_seconds` argument is also supported, but it's
  # deprecated.
  # poll_interval: 15  # type=Optional[float]

  # [Optional]
  # How long we should wait for any running
  # threads/processes to stop before exiting (default: 5 seconds).
  # stop_timeout: 5  # type=Optional[float]

  # [Optional]
  # If set to True then the plugin will not monitor
  # for new events. This is useful if you want to run a plugin in
  # stateless mode and only leverage its actions, without triggering any
  # events. Defaults to False.
  # disable_monitor: False  # type=bool

Actions#

Module reference#

class platypush.plugins.procedures.ProceduresPlugin(*_, **__)[source]#

Bases: RunnablePlugin, ProcedureEntityManager

Utility plugin to run and store procedures as native entities.

__init__(*args, **kwargs)[source]#
Parameters:

  • poll_interval – How often the loop() function should be executed (default: 15 seconds). NOTE: For back-compatibility reasons, the poll_seconds argument is also supported, but it’s deprecated.

  • stop_timeout – How long we should wait for any running threads/processes to stop before exiting (default: 5 seconds).

  • disable_monitor – If set to True then the plugin will not monitor for new events. This is useful if you want to run a plugin in stateless mode and only leverage its actions, without triggering any events. Defaults to False.

delete(name: str)[source]#

Delete a procedure by name.

Note that this is only possible for procedures that are stored on the database. Procedures that are loaded from Python scripts or configuration files should be removed from the source file.

Parameters:

name – Name of the procedure to be deleted.

exec(procedure: str | dict, *args, **kwargs)[source]#

Execute a procedure.

Parameters:

  • procedure – Procedure name or definition. If a string is passed, then the procedure will be looked up by name in the configured procedures. If a dictionary is passed, then it should be a valid procedure definition with at least the actions key.

  • args – Optional arguments to be passed to the procedure.

  • kwargs – Optional arguments to be passed to the procedure.

main(*_, **__)[source]#

Implementation of the main loop of the plugin.

publish_entities(entities: Collection[Any] | None, callback: Callable[[Entity], Any] | None = None, **kwargs) → Collection[Entity]#

Publishes a list of entities. The downstream consumers include:

It also accepts an optional callback that will be called when each of the entities in the set is flushed to the database.

You usually don’t need to override this class (but you may want to extend transform_entities() instead if your extension doesn’t natively handle Entity objects).

save(name: str, actions: Iterable[dict], args: Iterable[str] | None = None, old_name: str | None = None, meta: dict | None = None, **_)[source]#

Save a procedure.

Parameters:

  • name – Name of the procedure.

  • actions –

    Definition of the actions to be executed. Format:

    [
    {
        "action": "logger.info",
        "args": {
            "msg": "Hello, world!"
        }
    }
]

  • args – Optional list of arguments to be passed to the procedure, as a list of strings with the argument names.

  • old_name – Optional old name of the procedure if it’s being renamed.

  • meta –

    Optional metadata to be stored with the procedure. Example:

    {
    "icon": {
        "class": "fas fa-cogs",
        "color": "#00ff00"
    }
}

start()#

Start the plugin.

status(*_, publish: bool = True, **__)[source]#
Parameters:

publish – If set to True (default) then the platypush.message.event.entities.EntityUpdateEvent events will be published to the bus with the current configured procedures. Usually this should be set to True, unless you’re calling this method from a context where you first want to retrieve the procedures and then immediately modify them. In such cases, the published events may result in race conditions on the entities engine.

Returns:

The serialized configured procedures. Format:

{
    "procedure_name": {
        "type": "python",
        "module": "module_name",
        "source": "/path/to/source.py",
        "line": 42,
        "args": ["arg1", "arg2"]
    }
}

stop()#

Stop the plugin.

to_yaml(procedure: str | dict) → str[source]#

Serialize a procedure to YAML.

This method is useful to export a procedure to a file. Note that it only works with either YAML-based procedures or database-stored procedures: Python procedures can’t be converted to YAML.

Parameters:

procedure – Procedure name or definition. If a string is passed, then the procedure will be looked up by name in the configured procedures. If a dictionary is passed, then it should be a valid procedure definition with at least the actions and name keys.

Returns:

The serialized procedure in YAML format.

transform_entities(entities: Collection[_ProcedureWrapper], **_) → Collection[Procedure][source]#

This method takes a list of entities in any (plugin-specific) format and converts them into a standardized collection of Entity objects. Since this method is called by publish_entities() before entity updates are published, you may usually want to extend it to pre-process the entities managed by your extension into the standard format before they are stored and published to all the consumers.

wait_stop(timeout=None)#

Wait until a stop event is received.

platypush.plugins.procedures.ensure_initialized(f: Callable[[...], Any])[source]#

Ensures that the entities engine has been initialized before reading/writing the db.