clean up

- add CHANGELOG.md
- remove duplicate test
- write documentation

CHANGELOG.md

@@ -7,6 +7,10 @@
 
 * replace `BaseException` with `Exception` for custom errors
 * refactor `generic_resolver` to validate rules on startup instead of application of each rule
+* rewrite the helper method `add_field_to` such that it always raises an `FieldExistsWarning` instead of return a bool.
+* add new helper method `add_batch_to` to directly add multiple fields to one event
+* refactored some processors to make use of the new helper methods
+
 
 ### Bugfix
 

logprep/util/helper.py

@@ -59,34 +59,6 @@ def _add_and_not_overwrite_key(sub_dict, key):
     return sub_dict.get(key)
 
 
-def add_field_to_silent_fail(*args, **kwargs):
-    try:
-        add_field_to(*args, **kwargs)
-    except FieldExistsWarning:
-        return args[1]
-
-
-def add_batch_to(event, targets, contents, extends_lists=False, overwrite_output_field=False):
-    unsuccessful_targets = map(
-        add_field_to_silent_fail,
-        itertools.repeat(event, len(targets)),
-        targets,
-        contents,
-        itertools.repeat(extends_lists, len(targets)),
-        itertools.repeat(overwrite_output_field, len(targets)),
-    )
-    unsuccessful_targets = [item for item in unsuccessful_targets if item is not None]
-    if unsuccessful_targets:
-        raise FieldExistsWarning(event, unsuccessful_targets)
-
-
-def add_batch_to_silent_fail(*args, **kwargs):
-    try:
-        add_batch_to(*args, **kwargs)
-    except FieldExistsWarning as error:
-        return error.skipped_fields
-
-
 def add_field_to(
     event,
     target_field,
@@ -142,6 +114,83 @@ def add_field_to(
             target_parent[target_key].append(content)
 
 
+def add_field_to_silent_fail(*args, **kwargs):
+    """
+    Adds a field to an object, ignoring the FieldExistsWarning if the field already exists.
+
+    Parameters:
+        args: tuple
+            Positional arguments to pass to the add_field_to function.
+        kwargs: dict
+            Keyword arguments to pass to the add_field_to function.
+
+    Returns:
+        The field that was attempted to be added, if the field already exists.
+
+    Raises:
+        FieldExistsWarning: If the field already exists, but this warning is caught and ignored.
+    """
+    try:
+        add_field_to(*args, **kwargs)
+    except FieldExistsWarning:
+        return args[1]
+
+
+def add_batch_to(event, targets, contents, extends_lists=False, overwrite_output_field=False):
+    """
+    Handles the batch addition operation while raising a FieldExistsWarning with all unsuccessful targets.
+
+    Parameters:
+        event: dict
+            The event object to which fields are to be added.
+        targets: list
+            A list of target field names where the contents will be added.
+        contents: list
+            A list of contents corresponding to each target field.
+        extends_lists: bool
+            A boolean indicating whether to extend lists if the target field already exists.
+        overwrite_output_field: bool
+            A boolean indicating whether to overwrite the target field if it already exists.
+
+    Raises:
+        FieldExistsWarning: If there are targets to which the content could not be added due to field
+        existence restrictions.
+    """
+    unsuccessful_targets = map(
+        add_field_to_silent_fail,
+        itertools.repeat(event, len(targets)),
+        targets,
+        contents,
+        itertools.repeat(extends_lists, len(targets)),
+        itertools.repeat(overwrite_output_field, len(targets)),
+    )
+    unsuccessful_targets = [item for item in unsuccessful_targets if item is not None]
+    if unsuccessful_targets:
+        raise FieldExistsWarning(event, unsuccessful_targets)
+
+
+def add_batch_to_silent_fail(*args, **kwargs) -> None | list:
+    """
+    Handles the batch addition operation while silently handling FieldExistsWarning.
+
+    Parameters
+    ----------
+    *args : tuple
+        Variable length argument list.
+    **kwargs : dict
+        Arbitrary keyword arguments.
+
+    Returns
+    -------
+    skipped_fields : list
+        A list of fields that were skipped due to FieldExistWarning.
+    """
+    try:
+        add_batch_to(*args, **kwargs)
+    except FieldExistsWarning as error:
+        return error.skipped_fields
+
+
 def _get_slice_arg(slice_item):
     return int(slice_item) if slice_item else None
 

tests/unit/processor/template_replacer/test_template_replacer.py

@@ -163,14 +163,3 @@ def _create_template_replacer(self, config):
         template_replacer = Factory.create({"test instance": config})
         template_replacer.setup()
         return template_replacer
-
-    def test_replace_message_via_template(self):
-        document = {
-            "winlog": {"channel": "System", "provider_name": "Test", "event_id": 123},
-            "message": "foo",
-        }
-
-        self.object.process(document)
-
-        assert document.get("message")
-        assert document["message"] == "Test %1 Test %2"