heros.event
===========

.. py:module:: heros.event


Classes
-------

.. autoapisummary::

   heros.event.Callback
   heros.event.CallbackStorage
   heros.event.EventHandler
   heros.event.LocalEventHandler
   heros.event.RemoteEventHandler
   heros.event.EventDescriptor
   heros.event.LocalEventDescriptor
   heros.event.RemoteEventDescriptor


Functions
---------

.. autoapisummary::

   heros.event.remote_hero_method_to_str
   heros.event.event


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

.. py:function:: remote_hero_method_to_str(func: callable) -> str

.. py:class:: Callback(func: callable, origin: str = None)

   Represent a callback function.


   .. py:attribute:: func


   .. py:attribute:: origin
      :value: None



   .. py:method:: __eq__(other) -> bool

      Check for equality with other `Callback`.

      :param other: other callback instance.

      :returns: equality result.
      :rtype: bool



   .. py:method:: __call__(*args, **kwargs)

      Call the callback function.



   .. py:method:: __hash__()

      Generate a hash value for this callback using the name in case of remote hero methods
      or the callable itself for builtins or local callables.

      :returns: calculated hash.
      :rtype: int



   .. py:method:: to_dict() -> dict

      Generate a dictionary representation of this callback.

      :returns: dictionary with keys: name, origin, is_remote_hero and func
      :rtype: dict



.. py:class:: CallbackStorage

   Store all callbacks.


   .. py:attribute:: _callbacks


   .. py:method:: __iter__()

      Generate an iteration for this iterable.



   .. py:method:: __contains__(func: callable) -> bool

      Implements the `in` operation for this class.



   .. py:method:: append(func: callable, origin: str = None) -> str

      Append a given callable to the storage.

      :param func: `callable` to append.
      :param origin: `str` (default: `None`) indicating the origin of the callback.

      :returns: name of the callback.
      :rtype: str



   .. py:method:: remove(func: callable) -> bool

      Remove a callable from storage.

      :param func: `callable` to remove.

      :returns: truth value indicating if the callable was a callback.
      :rtype: bool



   .. py:method:: is_callback(func: callable) -> bool

      Check if given `callable` is a callback.

      :param func: `callable` to check.

      :returns: `callable` is a callback
      :rtype: bool



   .. py:method:: get_callbacks() -> list

      Get a list of all callbacks dictionaries.

      :returns: dictionary representation of all callbacks
      :rtype: list



.. py:class:: EventHandler

   Base class for event handlers.


   .. py:method:: connect(callback: callable)
      :abstractmethod:


      Connect a callback function.



   .. py:method:: disconnect(callback: callable)
      :abstractmethod:


      Disconnect a callback function.



   .. py:method:: is_callback(func: callable) -> bool
      :abstractmethod:


      Check if `func` is a callback



   .. py:method:: get_callbacks()
      :abstractmethod:


      Return all callbacks



.. py:class:: LocalEventHandler(instance, func)

   Bases: :py:obj:`EventHandler`


   Handles event connections for a specific instance.


   .. py:attribute:: instance


   .. py:attribute:: func


   .. py:attribute:: callbacks


   .. py:method:: __call__(*args, **kwargs)

      Call the original function and trigger callbacks.



   .. py:method:: connect(callback: callable, origin: str = None) -> str

      Connect a callback function to be triggered when the method is called.

      :param callback: `callable` to connect.
      :param origin: (optional) `str` indicting origin of this callback.

      :returns: name of the callback.
      :rtype: str



   .. py:method:: disconnect(callback: callable) -> bool

      Disconnect a callback function.

      :param callback: `callable` to disconnect.

      :returns: truth value indicating if the callable was a callback.
      :rtype: bool



   .. py:method:: is_callback(func: callable) -> bool

      Check if given callable is already a registered callback.

      :param callback: `callable` to check.

      :returns: truth value indicating if the callable is a callback.
      :rtype: bool



   .. py:method:: get_callbacks() -> list

      Return a list of registered callback functions.

      :returns: dictionary representation of all callbacks
      :rtype: list



.. py:class:: RemoteEventHandler(instance, func: callable = None)

   Bases: :py:obj:`EventHandler`


   Handles remote events for a specific instance.


   .. py:attribute:: instance


   .. py:attribute:: callbacks


   .. py:method:: __call__(payload)

      Call the original function and trigger callbacks.



   .. py:method:: connect(callback: callable) -> str

      Connect a callback function to be triggered when the method is called.

      :param callback: `callable` to connect.
      :param origin: (optional) `str` indicting origin of this callback.

      :returns: name of the callback.
      :rtype: str



   .. py:method:: disconnect(callback: callable) -> None

      Disconnect a callback function.

      :param callback: `callable` to disconnect.

      :returns: truth value indicating if the callable was a callback.
      :rtype: bool



   .. py:method:: is_callback(func: callable) -> bool

      Check if given callable is already a registered callback.

      :param callback: `callable` to check.

      :returns: truth value indicating if the callable is a callback.
      :rtype: bool



   .. py:method:: get_callbacks() -> list

      Return a list of registered callback functions.

      :returns: dictionary representation of all callbacks
      :rtype: list



.. py:class:: EventDescriptor(func: callable = None)

   A descriptor to handle instance-specific event connections.


   .. py:attribute:: func
      :value: None



   .. py:attribute:: _instances


   .. py:method:: _get_event_handler_cls()
      :staticmethod:

      :abstractmethod:



   .. py:method:: __get__(instance, owner)

      Ensure the method and event-handling functions are bound to the instance.

      :param self: the EventDescriptor instance
      :param instance: the owning `LocalHERO`/`RemoteHERO`.
      :param owner:



.. py:class:: LocalEventDescriptor(func: callable = None)

   Bases: :py:obj:`EventDescriptor`


   Descriptor of `@event` decorated methods of a `LocalHERO`.


   .. py:method:: _get_event_handler_cls()
      :staticmethod:



.. py:class:: RemoteEventDescriptor(func: callable = None)

   Bases: :py:obj:`EventDescriptor`


   Descriptor of remote representations of events in a `RemoteHERO`.


   .. py:method:: _get_event_handler_cls()
      :staticmethod:



.. py:function:: event(func: callable)

   Decorator for events.

   .. note:: Only use on methods bound to objects.


