:orphan:

:py:mod:`slidge.command.base`
=============================

.. py:module:: slidge.command.base


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   slidge.command.base.TableResult
   slidge.command.base.SearchResult
   slidge.command.base.Confirmation
   slidge.command.base.Form
   slidge.command.base.CommandAccess
   slidge.command.base.Option
   slidge.command.base.FormField
   slidge.command.base.Command




.. py:class:: TableResult


   Structured data as the result of a command

   .. py:attribute:: fields
      :type: Collection[FormField]

      The 'columns names' of the table.


   .. py:attribute:: items
      :type: Collection[dict[str, Union[str, slixmpp.JID]]]

      The rows of the table. Each row is a dict where keys are the fields ``var``
      attribute.


   .. py:attribute:: description
      :type: str

      A description of the content of the table.


   .. py:method:: get_xml()

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

      :return: some XML



.. py:class:: SearchResult




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

   Return type of :meth:`BaseSession.search`.

   .. py:attribute:: fields
      :type: Collection[FormField]

      The 'columns names' of the table.


   .. py:attribute:: items
      :type: Collection[dict[str, Union[str, slixmpp.JID]]]

      The rows of the table. Each row is a dict where keys are the fields ``var``
      attribute.


   .. py:method:: get_xml()

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

      :return: some XML



.. py:class:: Confirmation


   A confirmation 'dialog'

   .. py:attribute:: prompt
      :type: str

      The text presented to the command triggering user


   .. py:attribute:: handler
      :type: ConfirmationHandlerType

      An async function that should return a ResponseType


   .. py:attribute:: success
      :type: Optional[str]

      Text in case of success, used if handler does not return anything


   .. py:attribute:: handler_args
      :type: Iterable[Any]

      arguments passed to the handler


   .. py:attribute:: handler_kwargs
      :type: dict[str, Any]

      keyword arguments passed to the handler


   .. py:method:: get_form()

      Get the slixmpp form

      :return: some xml



.. py:class:: Form


   A form, to request user input

   .. py:method:: get_values(slix_form)

      Parse form submission

      :param slix_form: the xml received as the submission of a form
      :return: A dict where keys=field.var and values are either strings
          or JIDs (if field.type=jid-single)


   .. py:method:: get_xml()

      Get the slixmpp "form"

      :return: some XML



.. py:class:: CommandAccess




   Defines who can access a given Command


.. py:class:: Option




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

   .. py:method:: clear()

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


   .. py:method:: copy()

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


   .. py:method:: get()

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


   .. py:method:: items()

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


   .. py:method:: keys()

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


   .. py:method:: 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.


   .. py:method:: 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.


   .. py:method:: 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.


   .. py:method:: 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]


   .. py:method:: values()

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



.. py:class:: FormField


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

   .. py:attribute:: var
      :type: str
      :value: ''

      Internal name of the field, will be used to retrieve via :py:attr:`slidge.GatewayUser.registration_form`


   .. py:attribute:: label
      :type: Optional[str]

      Description of the field that the user will see


   .. py:attribute:: required
      :type: bool
      :value: False

      Whether this field is mandatory or not


   .. py:attribute:: private
      :type: bool
      :value: False

      For sensitive info that should not be displayed on screen while the user types.
      Forces field_type to "text-private"


   .. py:attribute:: type
      :type: slidge.util.types.FieldType
      :value: 'text-single'

      Type of the field, see `XEP-0004 <https://xmpp.org/extensions/xep-0004.html#protocol-fieldtypes>`_


   .. py:attribute:: value
      :type: str
      :value: ''

      Pre-filled value. Will be automatically pre-filled if a registered user modifies their subscription


   .. py:attribute:: image_url
      :type: Optional[str]

      An image associated to this field, eg, a QR code


   .. py:method:: validate(value)

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

      :param value: The value to test
      :return: The same value OR a JID if ``self.type=jid-single``


   .. py:method:: get_xml()

      Get the field in slixmpp format

      :return: some XML



.. py:class:: Command(xmpp)




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

   .. py:attribute:: NAME
      :type: str

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


   .. py:attribute:: HELP
      :type: str

      Long description of what the command does


   .. py:attribute:: NODE
      :type: str

      Name of the node used for ad-hoc commands


   .. py:attribute:: CHAT_COMMAND
      :type: str

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


   .. py:attribute:: ACCESS
      :type: CommandAccess

      Who can use this command


   .. py:attribute:: CATEGORY
      :type: Optional[str]

      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.


   .. py:method:: run(session, ifrom, *args)
      :async:

      Entry point of the command

      :param session: If triggered by a registered user, its slidge Session
      :param ifrom: JID of the command-triggering entity
      :param args: When triggered via chatbot type message, additional words
          after the CHAT_COMMAND string was passed

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


   .. py:method:: raise_if_not_authorized(jid)

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

      :param jid: jid of the entity trying to access the command
      :return:session of JID if it exists



