# `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, 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.