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

Package Contents

class slidge.command.Command(xmpp: slidge.util.types.AnyGateway)

Bases: _CommandMixin, Generic[slidge.util.types.SessionType]

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

ACCESS: CommandAccess = NotImplemented

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: slidge.util.types.SessionType | None, ifrom: slixmpp.JID, *args: str) → CommandResponseSessionType[slidge.util.types.SessionType]

Entry point of the command

Parameters:

  • session – If triggered by a registered user, its slidge Session

  • ifrom – JID of the command-triggering entity

  • args – 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

raise_if_not_authorized(jid: slixmpp.JID, fetch_session: bool = True, session: slidge.util.types.SessionType | None = None) → slidge.util.types.SessionType | None

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

Parameters:

  • jid – jid of the entity trying to access the command

  • fetch_session

  • session

:return:session of JID if it exists

NAME: str = NotImplemented

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

HELP: str = NotImplemented

Long description of what the command does

NODE: str = NotImplemented

Name of the node used for ad-hoc commands

CHAT_COMMAND: str = NotImplemented

Text to send to the gateway to trigger the command via a message

class slidge.command.CommandAccess

Bases: int, enum.Enum

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: Any

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: collections.abc.Iterable[Any] = []

arguments passed to the handler

handler_kwargs: dict[str, Any]

keyword arguments passed to the handler

get_form() → slixmpp.plugins.xep_0004.Form

Get the slixmpp form

Returns:

some xml

class slidge.command.ContactCommand

Bases: _RecipientCommand[slidge.util.types.LegacyContactType], Generic[slidge.util.types.LegacyContactType]

A command that will be avaible on a contact.

It implicitly requires the user to be registered and logged. It is never instantiated, so all methods must be static methods. Its entrypoint is the run() static method.

static run(recipient: T, *args: str) → CommandResponseRecipientType[T]
Abstractmethod:

Async:

Entrypoint for a recipient-specific command.

The first argument is a LegacyContact or LegacyMUC instance. *args are extra args passed when using the chatbot.

NAME: str = NotImplemented

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

HELP: str = NotImplemented

Long description of what the command does

NODE: str = NotImplemented

Name of the node used for ad-hoc commands

CHAT_COMMAND: str = NotImplemented

Text to send to the gateway to trigger the command via a message

class slidge.command.Form

A form, to request user input

get_values(slix_form: slixmpp.plugins.xep_0004.Form) → dict[str, list[str] | list[slixmpp.JID] | str | slixmpp.JID | bool | None]

Parse form submission

Parameters:

slix_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)

get_xml() → slixmpp.plugins.xep_0004.Form

Get the slixmpp “form”

Returns:

some XML

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: str | list[str] | None) → list[str] | list[slixmpp.JID] | str | slixmpp.JID | bool | None

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

Parameters:

value – The value to test

Returns:

The same value OR a JID if self.type=jid-single

get_xml() → slixmpp.plugins.xep_0004.stanza.field.FormField

Get the field in slixmpp format

Returns:

some XML

class slidge.command.MUCCommand

Bases: _RecipientCommand[slidge.util.types.LegacyMUCType], Generic[slidge.util.types.LegacyMUCType]

A command that will be avaible on a MUC.

It implicitly requires the user to be registered and logged. It is never instantiated, so all methods must be static methods. Its entrypoint is the run() static method.

static run(recipient: T, *args: str) → CommandResponseRecipientType[T]
Abstractmethod:

Async:

Entrypoint for a recipient-specific command.

The first argument is a LegacyContact or LegacyMUC instance. *args are extra args passed when using the chatbot.

NAME: str = NotImplemented

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

HELP: str = NotImplemented

Long description of what the command does

NODE: str = NotImplemented

Name of the node used for ad-hoc commands

CHAT_COMMAND: str = NotImplemented

Text to send to the gateway to trigger the command via a message

class slidge.command.SearchResult

Bases: TableResult

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: collections.abc.Sequence[FormField]

The ‘columns names’ of the table.

items: collections.abc.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() → slixmpp.plugins.xep_0004.Form

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

Returns:

some XML

class slidge.command.TableResult

Structured data as the result of a command

fields: collections.abc.Sequence[FormField]

The ‘columns names’ of the table.

items: collections.abc.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() → slixmpp.plugins.xep_0004.Form

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

Returns:

some XML