:py:mod:`matridge.gateway`
==========================

.. py:module:: matridge.gateway


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

Classes
~~~~~~~

.. autoapisummary::

   matridge.gateway.Gateway




Attributes
~~~~~~~~~~

.. autoapisummary::

   matridge.gateway.log


.. py:class:: Gateway


   Bases: :py:obj:`slidge.BaseGateway`

   The gateway component, handling registrations and un-registrations.

   On slidge launch, a singleton is instantiated, and it will be made available
   to public classes such :class:`.LegacyContact` or :class:`.BaseSession` as the
   ``.xmpp`` attribute.

   Must be subclassed by a legacy module to set up various aspects of the XMPP
   component behaviour, such as its display name or welcome message, via
   class attributes :attr:`.COMPONENT_NAME` :attr:`.WELCOME_MESSAGE`.

   Abstract methods related to the registration process must be overriden
   for a functional :term:`Legacy Module`:

   - :meth:`.validate`
   - :meth:`.validate_two_factor_code`
   - :meth:`.get_qr_text`
   - :meth:`.confirm_qr`

   NB: Not all of these must be overridden, it depends on the
   :attr:`REGISTRATION_TYPE`.

   The other methods, such as :meth:`.send_text` or :meth:`.react` are the same
   as those of :class:`.LegacyContact` and :class:`.LegacyParticipant`, because
   the component itself is also a "messaging actor", ie, an :term:`XMPP Entity`.
   For these methods, you need to specify the JID of the recipient with the
   `mto` parameter.

   Since it inherits from :class:`slixmpp.componentxmpp.ComponentXMPP`,you also
   have a hand on low-level XMPP interactions via slixmpp methods, e.g.:

   .. code-block:: python

       self.send_presence(
           pfrom="somebody@component.example.com",
           pto="someonwelse@anotherexample.com",
       )

   However, you should not need to do so often since the classes of the plugin
   API provides higher level abstractions around most commonly needed use-cases, such
   as sending messages, or displaying a custom status.


   .. py:attribute:: REGISTRATION_FIELDS

      

   .. py:attribute:: REGISTRATION_INSTRUCTIONS
      :type: str
      :value: 'Enter your credentials'

      

   .. py:attribute:: COMPONENT_NAME
      :value: 'matridge'

      Name of the component, as seen in service discovery by XMPP clients


   .. py:attribute:: COMPONENT_TYPE
      :value: 'matrix'

      

   .. py:attribute:: COMPONENT_AVATAR
      :value: 'https://upload.wikimedia.org/wikipedia/commons/thumb/7/7c/Matrix_icon.svg/209px-Matrix_icon.svg.png'

      

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

      

   .. py:attribute:: MARK_ALL_MESSAGES
      :value: False

      

   .. py:attribute:: PROPER_RECEIPTS
      :value: True

      

   .. py:attribute:: GROUPS
      :value: True

      

   .. py:method:: validate(user_jid, registration_form)
      :async:

      Validate a user's initial registration form.

      Should raise the appropriate :class:`slixmpp.exceptions.XMPPError`
      if the registration does not allow to continue the registration process.

      If :py:attr:`REGISTRATION_TYPE` is a
      :attr:`.RegistrationType.SINGLE_STEP_FORM`,
      this method should raise something if it wasn't possible to successfully
      log in to the legacy service with the registration form content.

      It is also used for other types of :py:attr:`REGISTRATION_TYPE` too, since
      the first step is always a form. If :attr:`.REGISTRATION_FIELDS` is an
      empty list (ie, it declares no :class:`.FormField`), the "form" is
      effectively a confirmation dialog displaying
      :attr:`.REGISTRATION_INSTRUCTIONS`.

      :param user_jid: JID of the user that has just registered
      :param registration_form: A dict where keys are the :attr:`.FormField.var` attributes
       of the :attr:`.BaseGateway.REGISTRATION_FIELDS` iterable


   .. py:method:: unregister(user)
      :async:

      Optionally override this if you need to clean additional
      stuff after a user has been removed from the permanent user_store.

      By default, this just calls :meth:`BaseSession.logout`.

      :param user:



.. py:data:: log

   

