slidge.command.base

Module Contents

Classes

TableResult

Structured data as the result of a command

SearchResult

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

Confirmation

A confirmation 'dialog'

Form

A form, to request user input

CommandAccess

Defines who can access a given Command

Option

Options to be used for FormField``s of type ``list-*

FormField

Represents a field of the form that a user will see when registering to the gateway

Command

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

class slidge.command.base.TableResult

Structured data as the result of a command

fields: Collection[FormField]

The ‘columns names’ of the table.

items: Collection[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

class slidge.command.base.SearchResult

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

Return type of BaseSession.search().

fields: Collection[FormField]

The ‘columns names’ of the table.

items: Collection[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.base.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

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.base.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.base.CommandAccess

Defines who can access a given Command

class slidge.command.base.Option

Options to be used for FormField``s of type ``list-*

clear()

D.clear() -> None. Remove all items from D.

copy()

D.copy() -> a shallow copy of D

get()

Return the value for key if key is in the dictionary, else default.

items()

D.items() -> a set-like object providing a view on D’s items

keys()

D.keys() -> a set-like object providing a view on D’s keys

pop()

D.pop(k[,d]) -> v, remove specified key and return the corresponding value.

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault()

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update()

D.update([E, ]**F) -> None. Update D from dict/iterable E and F. If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values()

D.values() -> an object providing a view on D’s values

class slidge.command.base.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

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

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.base.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 | 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