Merge pull request #825 from fkie-cad/dev-event-class-implementation

Dev event class implementation

Author: kaya-david

CHANGELOG.md

@@ -6,6 +6,10 @@
 ### Features
 
 ### Improvements
+* implement abstract Event class to encapsulate event data, processing state, warnings, and errors
+* integrate dotted field handling methods directly into Event, enabling structured field access and manipulation
+* support event identity and hashability based on data, allowing usage in sets and as dictionary keys
+
 * implement EventState class to manage the lifecycle of log events
 * integrate a finite state machine to control valid state transitions
 

logprep/ng/abc/event.py

@@ -0,0 +1,199 @@
+# pylint: disable=too-few-public-methods
+
+"""abstract module for event"""
+
+from abc import ABC
+from typing import TYPE_CHECKING, Any, Optional, Union
+
+from logprep.ng.event_state import EventState
+from logprep.util.helper import (
+    add_fields_to,
+    get_dotted_field_value,
+    pop_dotted_field_value,
+)
+
+if TYPE_CHECKING:  # pragma: no cover
+    from logprep.processor.base.rule import Rule
+
+
+class EventMetadata(ABC):
+    """Abstract EventMetadata Class to define the Interface"""
+
+
+class Event(ABC):
+    """
+    Abstract base class representing an event in the processing pipeline.
+
+    Encapsulates data, warnings, errors, and processing state.
+    """
+
+    __slots__: tuple[str, ...] = ("data", "state", "errors", "warnings")
+
+    def __init__(
+        self,
+        data: dict[str, Any],
+        *,
+        state: EventState | None = None,
+    ) -> None:
+        """
+        Initialize an Event instance.
+
+        Parameters
+        ----------
+        data : dict[str, Any]
+            The raw or processed data associated with the event.
+        state : EventState, optional
+            An optional initial EventState. Defaults to a new EventState() if not provided.
+
+        Examples
+        --------
+        Basic usage with automatic state:
+
+        >>> event = Event({"source": "syslog"})
+        >>> event.data
+        {'source': 'syslog'}
+        >>> event.state.current_state.name
+        'RECEIVING'
+
+        Providing a custom state:
+
+        >>> custom_state = EventState()
+        >>> event = Event({"source": "api"}, state=custom_state)
+        >>> event.state is custom_state
+        True
+
+        Handling warnings and errors:
+
+        >>> event = Event({"id": 123})
+        >>> event.warnings.append("Missing timestamp")
+        >>> event.errors.append(ValueError("Invalid format"))
+        >>> event.warnings
+        ['Missing timestamp']
+        >>> isinstance(event.errors[0], ValueError)
+        True
+        """
+
+        self.state: EventState = EventState() if state is None else state
+        self.data: dict[str, Any] = data
+        self.warnings: list[str] = []
+        self.errors: list[Exception] = []
+        super().__init__()
+
+    def __eq__(self, other: object) -> bool:
+        """
+        Determines whether two Event instances are considered equal.
+        Equality is defined by the equality of their `data` content.
+
+        Parameters
+        ----------
+        other : object
+            The object to compare against.
+
+        Returns
+        -------
+        bool
+            True if the other object is an Event and its `data` is equal to this instance's `data`.
+        """
+
+        if not isinstance(other, Event):
+            return NotImplemented
+
+        return self.data == other.data
+
+    def __hash__(self) -> int:
+        """
+        Returns a hash based on the immutable representation of the `data` field.
+        This enables Event instances to be used as keys in dictionaries or as members of sets.
+
+        Returns
+        -------
+        int
+            A hash value derived from the event's `data`.
+        """
+
+        return hash(self._deep_freeze(self.data))
+
+    def _deep_freeze(self, obj: Any) -> Any:
+        """
+        Recursively converts a data structure into a
+        hashable (immutable) representation. Used internally for generating
+        consistent hash values from nested dictionaries/lists.
+
+        Parameters
+        ----------
+        obj : Any
+            The object (usually dict or list) to be frozen.
+
+        Returns
+        -------
+        Any
+            A hashable, immutable version of the input object.
+        """
+
+        if isinstance(obj, dict):
+            return frozenset((k, self._deep_freeze(v)) for k, v in obj.items())
+
+        if isinstance(obj, list):
+            return tuple(self._deep_freeze(x) for x in obj)
+
+        if isinstance(obj, set):
+            return frozenset(self._deep_freeze(x) for x in obj)
+
+        return obj
+
+    def add_fields_to(
+        self,
+        fields: dict[str, Any],
+        rule: "Rule" = None,
+        merge_with_target: bool = False,
+        overwrite_target: bool = False,
+    ) -> None:
+        """
+        Add one or more fields to the target dictionary.
+
+        This method wraps the global `add_fields_to` utility function from
+        `logprep.util.helper`, allowing convenient field injection, merging,
+        and optional overwriting.
+
+        Args:
+            fields (dict): A dictionary of fields to add.
+            rule (Rule, optional): The rule context under which fields are added.
+            merge_with_target (bool): Whether to merge dictionaries recursively instead of overwriting.
+            overwrite_target (bool): Whether to overwrite existing values in the target.
+
+        Returns:
+            None
+        """
+        return add_fields_to(self.data, fields, rule, merge_with_target, overwrite_target)
+
+    def get_dotted_field_value(self, dotted_field: str) -> Any:
+        """
+        Shortcut method that delegates to the global `get_dotted_field_value` helper.
+
+        Parameters
+        ----------
+        dotted_field : str
+            The dotted path of the field to retrieve.
+
+        Returns
+        -------
+        Any
+            The value at the specified dotted path, or None if not found.
+        """
+        return get_dotted_field_value(self.data, dotted_field)
+
+    def pop_dotted_field_value(self, dotted_field: str) -> Optional[Union[dict, list, str]]:
+        """
+        Shortcut method that delegates to the global `pop_dotted_field_value` helper.
+
+        Parameters
+        ----------
+        dotted_field : str
+            The dotted path of the field to remove.
+
+        Returns
+        -------
+        Any
+            The removed value, or None if the path did not exist.
+        """
+        return pop_dotted_field_value(self.data, dotted_field)

logprep/ng/abc/event_metadata.py

@@ -1,5 +1,4 @@
 # pylint: disable=too-few-public-methods
-# -> deactivate temporarily pylint issue here
 
 """abstract module for event related datatypes"""
 

logprep/ng/inputs/kafka_input.py

@@ -2,7 +2,7 @@
 
 import attrs
 
-from logprep.ng.abc.event_metadata import EventMetadata
+from logprep.ng.abc.event import EventMetadata
 
 
 @attrs.define(slots=True, kw_only=True)

tests/unit/ng/inputs/__init__.py

@@ -3,7 +3,7 @@
 
 import pytest
 
-from logprep.ng.abc.event_metadata import EventMetadata
+from logprep.ng.abc.event import EventMetadata
 from logprep.ng.inputs.kafka_input import KafkaInputMetadata