matridge.matrix
===============

.. py:module:: matridge.matrix


Classes
-------

.. autoapisummary::

   matridge.matrix.AuthenticationClient
   matridge.matrix.Client


Functions
---------

.. autoapisummary::

   matridge.matrix.catch_all


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

.. py:function:: catch_all(coro)

.. 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:: get_credentials(resp)


   .. 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:attribute:: __sync_task
      :type:  Optional[asyncio.Task]
      :value: None



   .. py:attribute:: session


   .. py:attribute:: reactions


   .. py:method:: load()


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



   .. 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:: on_power_levels(room, event)
      :async:



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



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



   .. py:method:: on_key_verification(event)
      :async:



