improve docs

Author: mhoff

logprep/util/helper.py

@@ -20,22 +20,22 @@
 
 
 class Missing(Enum):
-    """Sentinel value for missing fields."""
+    """Sentinel type for indicating missing fields."""
 
     MISSING = auto()
 
 
-MISSING = Missing.MISSING
-"""Sentinel value for missing fields."""
+MISSING = Missing.MISSING  # pylint: disable=invalid-name
+"""Sentinel value for indicating missing fields."""
 
 
 class Skip(Enum):
-    """Sentinel value for method instrumentation to skip fields."""
+    """Sentinel type for method instrumentation to skip fields."""
 
     SKIP = auto()
 
 
-SKIP = Skip.SKIP
+SKIP = Skip.SKIP  # pylint: disable=invalid-name
 """Sentinel value for method instrumentation to skip fields."""
 
 
@@ -58,6 +58,7 @@ def color_print_line(
 
 
 def color_print_title(background: Union[str, AnsiBack], message: str):
+    """Print dashed title line with black foreground colour and reset the color afterwards."""
     message = f"------ {message} ------"
     color_print_line(background, Fore.BLACK, message)
 
@@ -182,7 +183,6 @@ def add_fields_to(
     rule: "Rule" = None,
     merge_with_target: bool = False,
     overwrite_target: bool = False,
-    filter_none: bool = True,
 ) -> None:
     """
     Handles the batch addition operation while raising a FieldExistsWarning with all unsuccessful targets.
@@ -208,7 +208,7 @@ def add_fields_to(
         existence restrictions.
     """
     # filter out None values
-    fields = {key: value for key, value in fields.items() if not filter_none or value is not None}
+    fields = {key: value for key, value in fields.items() if value is not None}
     number_fields = len(dict(fields))
     if number_fields == 1:
         _add_field_to(event, list(fields.items())[0], rule, merge_with_target, overwrite_target)
@@ -277,9 +277,7 @@ def _get_item(container: FieldValue, key: str) -> FieldValue:
         return list.__getitem__(typing.cast(list[FieldValue], container), index_or_slice)
 
 
-def get_dotted_field_value(
-    event: dict[str, FieldValue], dotted_field: str, silent_fail: bool = True
-) -> FieldValue:
+def get_dotted_field_value(event: dict[str, FieldValue], dotted_field: str) -> FieldValue:
     """
     Returns the value of a requested dotted_field by iterating over the event dictionary until the
     field was found. In case the field could not be found None is returned.
@@ -296,7 +294,7 @@ def get_dotted_field_value(
 
     Returns
     -------
-    Optional[Union[dict, list, str]]
+    FieldValue
         The value of the requested dotted field, which can be None.
         None is also returnd when the field could not be found and silent_fail is True.
 
@@ -310,10 +308,8 @@ def get_dotted_field_value(
         for field in get_dotted_field_list(dotted_field):
             current = _get_item(current, field)
         return current
-    except (KeyError, ValueError, TypeError, IndexError) as error:
-        if silent_fail:
-            return None
-        raise error
+    except (KeyError, ValueError, TypeError, IndexError):
+        return None
 
 
 def get_dotted_field_value_with_explicit_missing(
@@ -355,6 +351,30 @@ def get_dotted_field_values(
     dotted_fields: Iterable[str],
     on_missing: Callable[[str], Union[FieldValue, Skip]] = lambda _: None,
 ) -> dict[str, FieldValue]:
+    """
+    Extract the subset of fields from the dict by using the list of (potentially dotted)
+    field names as an allow list.
+    The behavior for fields targeted by the list but missing in the dict can be controlled
+    by a callback.
+    The callback allows for providing a replacement value, or - by returning SKIP - can
+    instruct the method to omit the field entirely from the extracted dict.
+
+
+    Parameters
+    ----------
+    event : dict
+        The (potentially nested) dict where the values are sourced from
+    dotted_fields : Iterable[str]
+        The (potentially dotted) list of field names to extract
+    on_missing : _type_, optional
+        The callback to control the behavior for missing fields, by default
+        `lambda _: None` which returns missing fields with `None` value
+
+    Returns
+    -------
+    dict[str, FieldValue]
+        The (potentially nested) sub-dict
+    """
     result: dict[str, FieldValue] = {}
     for field_to_copy in dotted_fields:
         value = get_dotted_field_value_with_explicit_missing(event, field_to_copy)
@@ -498,10 +518,10 @@ def copy_fields_to_event(
     target_event: dict,
     source_event: dict,
     dotted_field_names: Iterable[str],
+    *,
     skip_missing: bool = True,
     merge_with_target: bool = False,
     overwrite_target: bool = False,
-    filter_none: bool = True,
     rule: "Rule" = None,
 ) -> None:
     """
@@ -517,11 +537,11 @@ def copy_fields_to_event(
     dotted_field_names : list[str]
         The list of (potentially dotted) field names to copy
     skip_missing : bool, optional
-        _description_, by default False
+        Controls whether missing fields should be skipped or defaulted to None, by default True
     merge_with_target : bool, optional
-        _description_, by default False
+        Controls whether already existing fields should be merged as a list, by default False
     overwrite_target : bool, optional
-        _description_, by default False
+        Controls whether already existing fields should be overwritten, by default False
     rule : Rule, optional
         Contextual info for error handling, by default None
     """
@@ -535,7 +555,6 @@ def copy_fields_to_event(
         rule=rule,
         overwrite_target=overwrite_target,
         merge_with_target=merge_with_target,
-        filter_none=filter_none,
     )