slidge.command¶

This module implements an unified API to define adhoc or chatbot commands. Subclass a Command, ContactCommand or MUCCommand, and list it in your gateway’s BaseGateway.COMMANDS.

Submodules¶

slidge.command.register

Package Contents¶

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

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

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

For a command to be available to users, it must be listed in BaseGateway.COMMANDS.

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.CommandBase¶

Bases: abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

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

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.

For the command to be available to users, it must be listed in BaseGateway.COMMANDS.

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

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

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]

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.

For the command to be available to users, it must be listed in BaseGateway.COMMANDS.

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

slidge.command.BUILTIN_COMMANDS: tuple[type[base.CommandBase], Ellipsis]¶: The commands slidge provides out of the box. They are registered by default via BaseGateway.COMMANDS.

slidge.command.commands_from_module(module: types.ModuleType) → tuple[type[base.CommandBase], Ellipsis]¶

Collect all CommandBase subclasses defined in module.

Does not include classes which are imported from another module or abstract classes.