event

Subpackages

• event.handler
  • event.handler.file
  • event.handler.logging
  • event.handler.s3
  • event.handler.smtp

Package Contents

Classes

Event	Event class for notifying external services.
EventHandler	Interface to implement in order to be able to send events.
EventManager	Manage a set of handlers that will be used to send events.

Functions

unique_id(→ str)	Return a random globally unique id.
send_event(→ bool)	Send event using default manager.
send_event_from_file(→ bool)	Send event from a file using default manager.
add_handler(→ None)	Add handler in the default manager.
load_handlers_from_env(→ None)	Load handlers to default manager using env var.
handler_config_as_env(→ None)	Export default manager handler configurations into env.

Attributes

logger
default_manager

event.logger

event.unique_id() → str

Return a random globally unique id.

Returns:

an id

class event.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

__enter__() → Event

__exit__(_type: type[BaseException] | None, _val: BaseException | None, _tb: types.TracebackType | None) → None

set_formatter(key: str, fun: collections.abc.Callable[[str, Any], dict]) → None

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

Parameters:

• key – the event attribute to format

• fun – a function that takes the key and the associated value and return a dict

__setattr__(name: str, value: Any) → None

Store all attributes in the self._data dict.

__getattr__(name: str) → Any

Attributes are retrieved in the _data internal dict.

get_attachments() → dict[str, tuple[str, str]]

Return the list of attachments.

Returns:

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

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’

close() → None

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

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

format_date(key: str, value: float | str) → dict[str, str]

Format timestamp fields.

Parameters:

• key – the data key

• value – a timestamp

Returns:

a dict associating the original key to a human readable date

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.

Returns:

a dict

dump(event_dir: str) → str

Dump the event into a json file.

Parameters:

event_dir – directory in which the json is dumped

Returns:

json file location

classmethod load(json_filename: str) → Event

Retrieve an event from a JSON file.

Parameters:

json_filename – file from which event is loaded

Returns:

an event

class event.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

abstract send_event(event: Event) → bool

Send an event.

Parameters:

event – an Event

Returns:

True on success, False otherwise

classmethod decode_config(config_str: str) → dict

Decode a config string into a dict.

Parameters:

config_str – the string containing configuration information

Returns:

a dict that can be used as **kwargs for the handler initialization 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).

Returns:

a string that contains the current handler configuration. The string should not contain the ‘|’ character.

exception event.EventError(message: str | list[str], origin: str | None = None)

Bases: e3.error.E3Error

Exception raised by functions defined in E3.

class event.EventManager

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

send_event(event: Event) → bool

Send an event to using all registered handlers.

Parameters:

event – an event

Returns:

True if the event was sent successfully to all handlers

send_event_from_file(filename: str) → bool

Send an event from a dumped event.

Parameters:

filename – path to the json file containing the event

Returns:

True if the event was sent successfully to all handlers

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

Parameters:

name – handler name

Returns:

an handler class

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

Parameters:

name – the handler name

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

Parameters:

var_name – the name of the variable

handler_config_as_env(var_name: str = 'E3_EVENT_HANDLERS') → None

Add handlers by decoding an env variable.

Parameters:

var_name – the name of the variable containing the handler configurations

event.default_manager

event.send_event(event: Event) → bool

Send event using default manager.

See EventManager.send_event

Parameters:

event – an event

event.send_event_from_file(filename: str) → bool

Send event from a file using default manager.

See EventManager.send_event_from_file

event.add_handler(name: str, *args: Any, **kwargs: Any) → None

Add handler in the default manager.

See EventManager.add_handler

event.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

Parameters:

var_name – the name of the variable containing the configuration

event.handler_config_as_env(var_name: str = 'E3_EVENT_HANDLERS') → None

Export default manager handler configurations into env.

See EventManager.handler_config_as_env

Parameters:

var_name – the name of the variable