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.

async supports_commands(peer_jid)

Detect whether a peer supports XEP-0050 Ad-Hoc commands.

Parameters

peer_jid (aioxmpp.JID) – JID of the peer to query

Return type

bool

Returns

True if the peer supports the Ad-Hoc commands protocol, false otherwise.

Note that the fact that a peer supports the protocol does not imply that it offers any commands.

async get_commands(peer_jid)

Return the list of commands offered by the peer.

Parameters

peer_jid (JID) – JID of the peer to query

Return type

list of Item

Returns

List of command items

In the returned list, each Item represents one command supported by the peer. The node attribute is the identifier of the command which can be used with get_command_info() and execute().

async get_command_info(peer_jid, command_name)

Obtain information about a command.

Parameters

• peer_jid (JID) – JID of the peer to query

• command_name (str) – Node name of the command

Return type

InfoQuery

Returns

Service discovery information about the command

Sends a service discovery query to the service discovery node of the command. The returned object contains information about the command, such as the namespaces used by its implementation (generally the XEP-0004 data forms namespace) and possibly localisations of the commands name.

The command_name can be obtained by inspecting the listing from get_commands() or from well-known command names as defined for example in XEP-0133.

async execute(peer_jid, command_name)

Start execution of a command with a peer.

Parameters

• peer_jid (JID) – JID of the peer to start the command at.

• command_name (str) – Node name of the command to execute.

Return type

ClientSession

Returns

A started command execution session.

Initialises a client session and starts execution of the command. The session is returned.

This may raise any exception which may be raised by start().

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

async start()

Initiate the session by starting to execute the command with the peer.

Returns

The first_payload of the response

This sends an empty command IQ request with the EXECUTE action.

The status, response and related attributes get updated with the newly received values.

async proceed(*, action=<ActionType.EXECUTE: 'execute'>, payload=None)

Proceed command execution to the next stage.

Parameters

• action (ActionTyp) – Action type for proceeding

• payload – Payload for the request, or None

Returns

The first_payload of the response

action must be one of the actions returned by allowed_actions. It defaults to EXECUTE, which is (alongside with CANCEL) always allowed.

payload may be a sequence of XSOs, a single XSO or None. If it is None, the XSOs from the request are re-used. This is useful if you modify the payload in-place (e.g. via first_payload). Otherwise, the payload on the request is set to the payload argument; if it is a single XSO, it is wrapped in a sequence.

The status, response and related attributes get updated with the newly received values.

async close()

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.