adhoc — Ad-Hoc Commands support (XEP-0050)

This subpackage implements support for Ad-Hoc Commands as specified in XEP-0050. Both the client and the server side of Ad-Hoc Commands are supported.

New in version 0.8.

Client-side

class aioxmpp.AdHocClient(client, *, logger_base=None, dependencies={}, service_order_index=0)

Access other entities XEP-0050 Ad-Hoc commands.

This service provides helpers to conveniently access and execute XEP-0050 Ad-Hoc commands.

class aioxmpp.adhoc.service.ClientSession(stream, peer_jid, command_name, *, logger=None)

Represent an Ad-Hoc command session on the client side.

Parameters

• stream (StanzaStream) – The stanza stream over which the session is established.

• peer_jid (JID) – The full JID of the peer to communicate with

• command_name (str) – The command to run

The constructor does not send any stanza, it merely prepares the internal state. To start the command itself, use the ClientSession object as context manager or call start().

Note

The client session returned by AdHocClient.execute() is already started.

The command_name must be one of the node values as returned by AdHocClient.get_commands().

The following attributes change depending on the stage of execution of the command:

allowed_actions

Shorthand to access allowed_actions of the response.

If no response has been received yet or if the response specifies no set of valid actions, this is the minimal set of allowed actions ( EXECUTE and CANCEL).

first_payload

Shorthand to access first_payload of the response.

This is initially (and after close()) None.

response

The last Command received from the peer.

This is initially (and after close()) None.

status

The current status of command execution. This is either None or one of the CommandStatus enumeration values.

Initially, this attribute is None. After calls to start(), proceed() or close(), it takes the value of the status attribute of the response.

Server-side

class aioxmpp.adhoc.AdHocServer(client, **kwargs)

Support for serving Ad-Hoc commands.

register_stateless_command(node, name, handler, *, is_allowed=None, features={'jabber:x:data'})

Register a handler for a stateless command.

Parameters

• node (str) – Name of the command (node in the service discovery list).

• name (str or LanguageMap) – Human-readable name of the command

• handler – Coroutine function to run to get the response for a request.

• is_allowed (function or None) – A predicate which determines whether the command is shown and allowed for a given peer.

• features (set of str) – Set of features to announce for the command

When a request for the command is received, handler is invoked. The semantics of handler are the same as for register_iq_request_handler(). It must produce a valid Command response payload.

If is_allowed is not None, it is invoked whenever a command listing is generated and whenever a command request is received. The aioxmpp.JID of the requester is passed as positional argument to is_allowed. If is_allowed returns false, the command is not included in the list and attempts to execute it are rejected with <forbidden/> without calling handler.

If is_allowed is None, the command is always visible and allowed.

The features are returned on a service discovery info request for the command node. By default, the XEP-0004 (Data Forms) namespace is included, but this can be overridden by passing a different set without that feature to features.

unregister_command(node)

Unregister a command previously registered.

Parameters

node (str) – Name of the command (node in the service discovery list).

XSOs

class aioxmpp.adhoc.xso.Command(*args, **kwargs)

class aioxmpp.adhoc.xso.Actions(*args, **kwargs)

class aioxmpp.adhoc.xso.Note(*args, **kwargs)

Enumerations

class aioxmpp.adhoc.CommandStatus(value)

Describes the status a command execution is in.

EXECUTING

The command is being executed.

COMPLETED

The command has been completed.

CANCELED

The command has been canceled.

class aioxmpp.adhoc.ActionType(value)

An enumeration.