slidge.command¶

This module implements an unified API to define adhoc or chatbot commands. Just subclass a Command, and make sures it is imported in your legacy module’s __init__.py.

Submodules¶

slidge.command.register

Classes¶

`Command`	Abstract base class to implement gateway commands (chatbot and ad-hoc)
`CommandAccess`	Defines who can access a given Command
`Confirmation`	A confirmation 'dialog'
`Form`	A form, to request user input
`FormField`	Represents a field of the form that a user will see when registering to the gateway
`SearchResult`	Results of the search command (search for contacts via Jabber Search)
`TableResult`	Structured data as the result of a command

Package Contents¶

class slidge.command.Command(xmpp)¶

Abstract base class to implement gateway commands (chatbot and ad-hoc)

Parameters:: xmpp (slidge.core.gateway.BaseGateway)

NAME: str¶: Friendly name of the command, eg: “do something with stuff”

HELP: str¶: Long description of what the command does

NODE: str¶: Name of the node used for ad-hoc commands

CHAT_COMMAND: str¶: Text to send to the gateway to trigger the command via a message

ACCESS: CommandAccess¶: Who can use this command

CATEGORY: str | slidge.command.categories.CommandCategory | None = None¶: If used, the command will be under this top-level category. Use the same string for several commands to group them. This hierarchy only used for the adhoc interface, not the chat command interface.

async run(session, ifrom, *args)¶

Entry point of the command

Parameters:

session (Optional[BaseSession[Any, Any]]) – If triggered by a registered user, its slidge Session
ifrom (slixmpp.JID) – JID of the command-triggering entity
args (str) – When triggered via chatbot type message, additional words after the CHAT_COMMAND string was passed

Returns:

Either a TableResult, a Form, a Confirmation, a text, or None

Return type:

CommandResponseType

raise_if_not_authorized(jid)¶

Raise an appropriate error is jid is not authorized to use the command

Parameters:: jid (slixmpp.JID) – jid of the entity trying to access the command
Return type:: Optional[BaseSession[Any, Any]]

:return:session of JID if it exists

class slidge.command.CommandAccess¶: Defines who can access a given Command

class slidge.command.Confirmation¶

A confirmation ‘dialog’

prompt: str¶: The text presented to the command triggering user

handler: ConfirmationHandlerType¶: An async function that should return a ResponseType

success: str | None = None¶: Text in case of success, used if handler does not return anything

handler_args: Iterable[Any]¶: arguments passed to the handler

handler_kwargs: dict[str, Any]¶: keyword arguments passed to the handler

get_form()¶

Get the slixmpp form

Returns:: some xml
Return type:: slixmpp.plugins.xep_0004.Form

class slidge.command.Form¶

A form, to request user input

get_values(slix_form)¶

Parse form submission

Parameters:: slix_form (slixmpp.plugins.xep_0004.Form) – the xml received as the submission of a form
Returns:: A dict where keys=field.var and values are either strings or JIDs (if field.type=jid-single)
Return type:: dict[str, Union[list[str], list[slixmpp.JID], str, slixmpp.JID, bool, None]]

get_xml()¶

Get the slixmpp “form”

Returns:: some XML
Return type:: slixmpp.plugins.xep_0004.Form

class slidge.command.FormField¶

Represents a field of the form that a user will see when registering to the gateway via their XMPP client.

var: str = ''¶: Internal name of the field, will be used to retrieve via slidge.GatewayUser.registration_form

label: str | None = None¶: Description of the field that the user will see

required: bool = False¶: Whether this field is mandatory or not

private: bool = False¶: For sensitive info that should not be displayed on screen while the user types. Forces field_type to “text-private”

type: slidge.util.types.FieldType = 'text-single'¶: Type of the field, see XEP-0004

value: str = ''¶: Pre-filled value. Will be automatically pre-filled if a registered user modifies their subscription

image_url: str | None = None¶: An image associated to this field, eg, a QR code

validate(value)¶

Raise appropriate XMPPError if a given value is valid for this field

Parameters:: value (Optional[Union[str, list[str]]]) – The value to test
Returns:: The same value OR a JID if self.type=jid-single
Return type:: Union[list[str], list[slixmpp.JID], str, slixmpp.JID, bool, None]

get_xml()¶

Get the field in slixmpp format

Returns:: some XML
Return type:: slixmpp.plugins.xep_0004.FormField

class slidge.command.SearchResult¶

Results of the search command (search for contacts via Jabber Search)

Return type of BaseSession.search().

description: str = 'Contact search results'¶: A description of the content of the table.

fields: Sequence[FormField]¶: The ‘columns names’ of the table.

items: Sequence[dict[str, str | slixmpp.JID]]¶: The rows of the table. Each row is a dict where keys are the fields var attribute.

get_xml()¶

Get a slixmpp “form” (with <reported> header)to represent the data

Returns:: some XML
Return type:: slixmpp.plugins.xep_0004.Form

class slidge.command.TableResult¶

Structured data as the result of a command

fields: Sequence[FormField]¶: The ‘columns names’ of the table.

items: Sequence[dict[str, str | slixmpp.JID]]¶: The rows of the table. Each row is a dict where keys are the fields var attribute.

description: str¶: A description of the content of the table.

get_xml()¶

Get a slixmpp “form” (with <reported> header)to represent the data

Returns:: some XML
Return type:: slixmpp.plugins.xep_0004.Form