event
=====

.. py:module:: event


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/event/handler/index


Attributes
----------

.. autoapisummary::

   event.logger
   event.default_manager


Classes
-------

.. autoapisummary::

   event.Event
   event.EventHandler
   event.EventError
   event.EventManager


Functions
---------

.. autoapisummary::

   event.unique_id
   event.send_event
   event.send_event_from_file
   event.add_handler
   event.load_handlers_from_env
   event.handler_config_as_env


Package Contents
----------------

.. py:data:: logger

.. py:function:: unique_id() -> str

   Return a random globally unique id.

   :return: an id


.. py:class:: Event(name: str, uid: str | None = None, **kwargs: dict[str, Any])

   Event class for notifying external services.

   An event is composed of:

     * some data organized as key value dict
     * some attachments

   By default the data will contain the following keys:
     * name: the name of the event
     * uid: a global unique id
     * begin_time: time at which the event was created
     * end_time: time at which the event was closed


   .. py:attribute:: uid


   .. py:attribute:: name


   .. py:attribute:: begin_time


   .. py:attribute:: end_time
      :type:  float | None
      :value: None



   .. py:method:: __enter__() -> Event


   .. py:method:: __exit__(_type: type[BaseException] | None, _val: BaseException | None, _tb: types.TracebackType | None) -> None


   .. py:method:: set_formatter(key: str, fun: collections.abc.Callable[[str, Any], dict]) -> None

      Add a formatter for a given key. (see as_dict).

      :param key: the event attribute to format
      :param fun: a function that takes the key and the associated value
          and return a dict



   .. py:method:: __setattr__(name: str, value: Any) -> None

      Store all attributes in the self._data dict.



   .. py:method:: __getattr__(name: str) -> Any

      Attributes are retrieved in the _data internal dict.



   .. py:method:: get_attachments() -> dict[str, tuple[str, str]]

      Return the list of attachments.

      :return: a list of tuple (path, sha1(path))



   .. py:method:: attach_file(path: str, name: str = 'log') -> None

      Attach log file to the event.

      When the event will be submitted, the log file will be attached.
      Note that some notification backend might cut or reject the attachment
      if too big.
      :param path: path to a log file
      :param name: name of the file to attach, by default 'log'



   .. py:method:: close() -> None

      Close the event. Once done it is not supposed to be modified.

      Calling the method close() allow using it with
      contexlib.closing()



   .. py:method:: format_date(key: str, value: float | str) -> dict[str, str]

      Format timestamp fields.

      :param key: the data key
      :param value: a timestamp
      :return: a dict associating the original key to a human readable date



   .. py:method:: as_dict() -> dict[str, str]

      Convert the event data into a dict that can be serialized as json.

      For each key, value of the _data dict by default add them into the
      returned dict (default) or use a formatter that return a dict used to
      update the result.

      :return: a dict



   .. py:method:: dump(event_dir: str) -> str

      Dump the event into a json file.

      :param event_dir: directory in which the json is dumped
      :return: json file location



   .. py:method:: load(json_filename: str) -> Event
      :classmethod:


      Retrieve an event from a JSON file.

      :param json_filename: file from which event is loaded
      :return: an event



.. py:class:: EventHandler

   Interface to implement in order to be able to send events.

   One method needs to be implemented by a new EventManager:

   - send_event: method sending an event to an external service


   .. py:method:: send_event(event: Event) -> bool
      :abstractmethod:


      Send an event.

      :param event: an Event
      :return: True on success, False otherwise



   .. py:method:: decode_config(config_str: str) -> dict
      :classmethod:


      Decode a config string into a dict.

      :param config_str: the string containing configuration information
      :return: a dict that can be used as ``**kwargs`` for the handler
          initialization method



   .. py:method:: encode_config() -> str

      Encode the handler configuration into a string.

      This default implementation can be used for handlers that do not
      need any configuration parameters (i.e: for which __init__ does not
      take any parameter apart for self).

      :return: a string that contains the current handler configuration.
          The string should not contain the '|' character.



.. py:class:: EventError

   Bases: :py:obj:`e3.error.E3Error`


.. py:class:: EventManager

   Manage a set of handlers that will be used to send events.


   .. py:attribute:: handlers
      :type:  dict[str, EventHandler]


   .. py:method:: send_event(event: Event) -> bool

      Send an event to using all registered handlers.

      :param event: an event
      :return: True if the event was sent successfully to all handlers



   .. py:method:: send_event_from_file(filename: str) -> bool

      Send an event from a dumped event.

      :param filename: path to the json file containing the event
      :return: True if the event was sent successfully to all handlers



   .. py:method:: get_handler(name: str) -> collections.abc.Callable[Ellipsis, EventHandler]

      Get an handler class by name.

      Available handler classes are registered using the e3.event.handler
      entry_points in your setup.py

      :param name: handler name
      :return: an handler class



   .. py:method:: add_handler(name: str, *args: Any, **kwargs: Any) -> None

      Add an handler instance to the manager.

      args and kwargs are passed to the handler __init__ method

      :param name: the handler name



   .. py:method:: load_handlers_from_env(var_name: str = 'E3_EVENT_HANDLERS') -> None

      Add handlers by decoding an env variable.

      The variable value should have the following format:

          handler_name1=some_value|handler_name2=some_value|handler_name3

      The value associated with each handler is passed to the handler method
      decode_config. In most cases the user do not need to create this value
      manually but called handler_config_as_env method to create the
      variable. The main goal of this function is to share EventManager
      configuration among several processes

      :param var_name: the name of the variable



   .. py:method:: handler_config_as_env(var_name: str = 'E3_EVENT_HANDLERS') -> None

      Add handlers by decoding an env variable.

      :param var_name: the name of the variable containing the handler
          configurations



.. py:data:: default_manager

.. py:function:: send_event(event: Event) -> bool

   Send event using default manager.

   See EventManager.send_event

   :param event: an event


.. py:function:: send_event_from_file(filename: str) -> bool

   Send event from a file using default manager.

   See EventManager.send_event_from_file


.. py:function:: add_handler(name: str, *args: Any, **kwargs: Any) -> None

   Add handler in the default manager.

   See EventManager.add_handler


.. py:function:: load_handlers_from_env(var_name: str = 'E3_EVENT_HANDLERS') -> None

   Load handlers to default manager using env var.

   See EventManager.load_handlers_from_env

   :param var_name: the name of the variable containing the configuration


.. py:function:: handler_config_as_env(var_name: str = 'E3_EVENT_HANDLERS') -> None

   Export default manager handler configurations into env.

   See EventManager.handler_config_as_env

   :param var_name: the name of the variable


