:py:mod:`event` =============== .. py:module:: event .. autoapi-nested-parse:: Plugin-based event system for notifying external services. Subpackages ----------- .. toctree:: :titlesonly: :maxdepth: 3 handler/index.rst Package Contents ---------------- Classes ~~~~~~~ .. autoapisummary:: event.Event event.EventHandler 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 Attributes ~~~~~~~~~~ .. autoapisummary:: event.logger event.default_manager .. 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:method:: __enter__() -> typing_extensions.Self Enter context manager for event. .. py:method:: __exit__(_type: type[BaseException] | None, _val: BaseException | None, _tb: types.TracebackType | None) -> None Exit context manager and close event. :param _type: exception type :param _val: exception value :param _tb: traceback .. 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. :param name: attribute name :param value: attribute value .. py:method:: __getattr__(name: str) -> Any Attributes are retrieved in the _data internal dict. :param name: attribute name .. 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:exception:: EventError(message: str | list[str], origin: str | None = None) Bases: :py:obj:`e3.error.E3Error` Exception raised for event operations errors. .. py:class:: EventManager Manage a set of handlers that will be used to send events. .. 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 :param filename: path to event file .. py:function:: add_handler(name: str, *args: Any, **kwargs: Any) -> None Add handler in the default manager. See EventManager.add_handler :param name: handler name .. 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