tribler.core.restapi.events_endpoint
====================================

.. py:module:: tribler.core.restapi.events_endpoint


Attributes
----------

.. autoapisummary::

   tribler.core.restapi.events_endpoint.topics_to_send_to_gui


Classes
-------

.. autoapisummary::

   tribler.core.restapi.events_endpoint.MessageDict
   tribler.core.restapi.events_endpoint.EventsEndpoint


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

.. py:data:: topics_to_send_to_gui

.. py:class:: MessageDict

   Bases: :py:obj:`TypedDict`


   A message fit for the GUI, usually forwarded from the Notifier.


   .. py:attribute:: topic
      :type:  str


   .. py:attribute:: kwargs
      :type:  dict[str, str]


.. py:class:: EventsEndpoint(notifier: tribler.core.notifier.Notifier, public_key: str | None = None)

   Bases: :py:obj:`tribler.core.restapi.rest_endpoint.RESTEndpoint`


   Important events in Tribler are returned over the events endpoint. This connection is held open. Each event is
   pushed over this endpoint in the form of a JSON dictionary. Each JSON dictionary contains a type field that
   indicates the type of the event. Individual events are separated by a newline character.


   .. py:attribute:: path
      :value: '/api/events'



   .. py:attribute:: shutdown_event


   .. py:attribute:: events_responses
      :type:  list[aiohttp.web.StreamResponse]
      :value: []



   .. py:attribute:: undelivered_error
      :type:  Exception | None
      :value: None



   .. py:attribute:: public_key
      :value: None



   .. py:attribute:: notifier


   .. py:attribute:: queue
      :type:  asyncio.Queue[MessageDict]


   .. py:property:: _shutdown
      :type: bool



   .. py:method:: on_notification(topic: tribler.core.notifier.Notification, **kwargs) -> None

      Callback for when a notification is received. Check if we should forward it to the GUI.



   .. py:method:: on_circuit_removed(circuit: ipv8.messaging.anonymization.tunnel.Circuit, additional_info: str) -> None

      Special handler for circuit removal notifications.

      The original notification contains non-JSON-serializable argument, so we send another one to GUI.



   .. py:method:: initial_message() -> MessageDict

      Create the initial message to announce to the GUI.



   .. py:method:: error_message(reported_error: Exception) -> MessageDict

      Create an error message for the GUI.



   .. py:method:: encode_message(message: MessageDict) -> bytes

      Use JSON to dump the given message to bytes.



   .. py:method:: has_connection_to_gui() -> bool

      Whether the GUI has responded before.



   .. py:method:: should_skip_message(message: MessageDict) -> bool

      Returns True if EventsEndpoint should skip sending message to GUI due to a shutdown or no connection to GUI.
      Issue an appropriate warning if the message cannot be sent.



   .. py:method:: send_event(message: MessageDict) -> None

      Put event message to a queue to be sent to GUI.



   .. py:method:: process_queue() -> None
      :async:


      Get all failed messages in the queue and send them to the GUI.



   .. py:method:: _write_data(message: MessageDict) -> None
      :async:


      Write data over the event socket if it's open.



   .. py:method:: on_tribler_exception(reported_error: Exception) -> None

      An exception has occurred in Tribler.



   .. py:method:: get_info(request: aiohttp.web_request.Request) -> tribler.core.restapi.rest_endpoint.RESTResponse
      :async:


      Get the general info of the events endpoint.



   .. py:method:: get_events(request: aiohttp.web_request.Request) -> aiohttp.web.StreamResponse
      :async:


      A GET request to this endpoint will open the event connection.

          **Example request**:

              .. sourcecode:: none

                  curl -X GET http://localhost:20100/events