Skip to content
Back to top
View this page
Edit this page

# 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 = 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

  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, 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, fetch_session=True, session=None)

    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

      - fetch_session (bool)

      - session (Optional[BaseSession[Any, Any]])

    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