:py:mod:`matridge.matrix`
=========================

.. py:module:: matridge.matrix


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

Classes
~~~~~~~

.. autoapisummary::

   matridge.matrix.Credentials
   matridge.matrix.AuthenticationClient
   matridge.matrix.Client



Functions
~~~~~~~~~

.. autoapisummary::

   matridge.matrix.catch_all



.. py:function:: catch_all(coro)


.. py:class:: Credentials


   Bases: :py:obj:`TypedDict`

   dict() -> new empty dictionary
   dict(mapping) -> new dictionary initialized from a mapping object's
       (key, value) pairs
   dict(iterable) -> new dictionary initialized as if via:
       d = {}
       for k, v in iterable:
           d[k] = v
   dict(**kwargs) -> new dictionary initialized with the name=value pairs
       in the keyword argument list.  For example:  dict(one=1, two=2)

   Initialize self.  See help(type(self)) for accurate signature.

   .. py:attribute:: homeserver
      :type: str

      

   .. py:attribute:: user_id
      :type: str

      

   .. py:attribute:: device_id
      :type: str

      

   .. py:attribute:: access_token
      :type: str

      


.. py:class:: AuthenticationClient(server, handle, jid, log = None)


   Bases: :py:obj:`nio.AsyncClient`

   An async IO matrix client.

   Args:
       homeserver (str): The URL of the homeserver which we want to connect
           to.
       user (str, optional): The user which will be used when we log in to the
           homeserver.
       device_id (str, optional): An unique identifier that distinguishes
           this client instance. If not set the server will provide one after
           log in.
       store_path (str, optional): The directory that should be used for state
           storage.
       config (AsyncClientConfig, optional): Configuration for the client.
       ssl (bool/ssl.SSLContext, optional): SSL validation mode. None for
           default SSL check (ssl.create_default_context() is used), False
           for skip SSL certificate validation connection.
       proxy (str, optional): The proxy that should be used for the HTTP
           connection. Supports SOCKS4(a), SOCKS5, HTTP (tunneling) via an
           URL like e.g. 'socks5://user:password@127.0.0.1:1080'.

   Attributes:
       synced (Event): An asyncio event that is fired every time the client
           successfully syncs with the server. Note, this event will only be
           fired if the `sync_forever()` method is used.

   A simple example can be found bellow.

   Example:
           >>> client = AsyncClient("https://example.org", "example")
           >>> login_response = loop.run_until_complete(
           >>>     client.login("hunter1")
           >>> )
           >>> asyncio.run(client.sync_forever(30000))

   This example assumes a full sync on every run. If a sync token is provided
   for the `since` parameter of the `sync_forever` method `full_state` should
   be set to `True` as well.

   Example:
           >>> asyncio.run(
           >>>     client.sync_forever(30000, since="token123",
           >>>                         full_state=True)
           >>> )

   The client can also be configured to store and restore the sync token
   automatically. The `full_state` argument should be set to `True` in that
   case as well.

   Example:
           >>> config = ClientConfig(store_sync_tokens=True)
           >>> client = AsyncClient("https://example.org", "example",
           >>>                      store_path="/home/example",
           >>>                      config=config)
           >>> login_response = loop.run_until_complete(
           >>>     client.login("hunter1")
           >>> )
           >>> asyncio.run(client.sync_forever(30000, full_state=True))


   .. py:method:: save(resp)


   .. py:method:: load()


   .. py:method:: destroy()


   .. py:method:: login_token()
      :async:


   .. py:method:: fix_homeserver()
      :async:

      Uses https://$HOMESERVER/.well-known/matrix/client to fix the homeserver
      URL.



.. py:class:: Client(server, handle, session)


   Bases: :py:obj:`AuthenticationClient`

   An async IO matrix client.

   Args:
       homeserver (str): The URL of the homeserver which we want to connect
           to.
       user (str, optional): The user which will be used when we log in to the
           homeserver.
       device_id (str, optional): An unique identifier that distinguishes
           this client instance. If not set the server will provide one after
           log in.
       store_path (str, optional): The directory that should be used for state
           storage.
       config (AsyncClientConfig, optional): Configuration for the client.
       ssl (bool/ssl.SSLContext, optional): SSL validation mode. None for
           default SSL check (ssl.create_default_context() is used), False
           for skip SSL certificate validation connection.
       proxy (str, optional): The proxy that should be used for the HTTP
           connection. Supports SOCKS4(a), SOCKS5, HTTP (tunneling) via an
           URL like e.g. 'socks5://user:password@127.0.0.1:1080'.

   Attributes:
       synced (Event): An asyncio event that is fired every time the client
           successfully syncs with the server. Note, this event will only be
           fired if the `sync_forever()` method is used.

   A simple example can be found bellow.

   Example:
           >>> client = AsyncClient("https://example.org", "example")
           >>> login_response = loop.run_until_complete(
           >>>     client.login("hunter1")
           >>> )
           >>> asyncio.run(client.sync_forever(30000))

   This example assumes a full sync on every run. If a sync token is provided
   for the `since` parameter of the `sync_forever` method `full_state` should
   be set to `True` as well.

   Example:
           >>> asyncio.run(
           >>>     client.sync_forever(30000, since="token123",
           >>>                         full_state=True)
           >>> )

   The client can also be configured to store and restore the sync token
   automatically. The `full_state` argument should be set to `True` in that
   case as well.

   Example:
           >>> config = ClientConfig(store_sync_tokens=True)
           >>> client = AsyncClient("https://example.org", "example",
           >>>                      store_path="/home/example",
           >>>                      config=config)
           >>> login_response = loop.run_until_complete(
           >>>     client.login("hunter1")
           >>> )
           >>> asyncio.run(client.sync_forever(30000, full_state=True))


   .. py:attribute:: MIN_RETRY_TIME
      :value: 3

      

   .. py:attribute:: MAX_RETRY_TIME
      :value: 300

      

   .. py:attribute:: REQUEST_TIMEOUT
      :value: 60

      

   .. py:attribute:: CONSIDER_SUCCESSFUL
      :value: 10

      

   .. py:method:: __add_event_handlers()


   .. py:method:: __get_muc(room)
      :async:


   .. py:method:: __sync_forever()
      :async:


   .. py:method:: get_participant(room, event)
      :async:


   .. py:method:: listen()
      :async:


   .. py:method:: stop_listen()


   .. py:method:: fetch_history(room_id, limit)
      :async:


   .. py:method:: on_event(room, event)
      :async:


   .. py:method:: on_message(room, event)
      :async:


   .. py:method:: on_presence(presence)
      :async:


   .. py:method:: on_avatar(room, event)
      :async:


   .. py:method:: on_topic(room, event)
      :async:


   .. py:method:: on_name(room, event)
      :async:


   .. py:method:: on_sticker(room, event)
      :async:


   .. py:method:: on_member(room, event)
      :async:


   .. py:method:: on_typing(room, event)
      :async:


   .. py:method:: on_receipt(room, event)
      :async:


   .. py:method:: on_reaction(room, event, **kw)
      :async:


   .. py:method:: on_redact(room, event)
      :async:


   .. py:method:: get_original_id(room_id, event_id)
      :async:


   .. py:method:: get_event(room_id, event_id)
      :async:



