[API] Improve Formatter Filter Utility + Docs (#5715)

mlrun · Jun 4, 2024 · 74d9619 · 74d9619
1 parent 91cecf8
commit 74d9619
Show file tree

Hide file tree

Showing 2 changed files with 49 additions and 14 deletions.
diff --git a/mlrun/common/formatters/base.py b/mlrun/common/formatters/base.py
@@ -19,10 +19,22 @@
 
 
 class ObjectFormat:
+    """
+    MLRun object formatter. Any class that inherits from this class should implement the `format_method` method
+    to specify the formatting method for each format.
+    A `filter_obj_method` utility method is provided to filter the object based on a list of keys.
+    """
+
     full = "full"
 
     @staticmethod
     def format_method(_format: str) -> typing.Optional[typing.Callable]:
+        """
+        Get the formatting method for the provided format.
+        A `None` value signifies a pass-through formatting method (no formatting).
+        :param _format: The format as a string representation.
+        :return: The formatting method.
+        """
         return {
             ObjectFormat.full: None,
         }[_format]
@@ -34,6 +46,13 @@ def format_obj(
         _format: str,
         exclude_formats: typing.Optional[list[str]] = None,
     ) -> typing.Any:
+        """
+        Format the provided object based on the provided format.
+        :param obj: The object to format.
+        :param _format: The format as a string representation.
+        :param exclude_formats: A list of formats to exclude from the formatting process. If the provided format is in
+                                this list, an invalid format exception will be raised.
+        """
         exclude_formats = exclude_formats or []
         _format = _format or cls.full
         invalid_format_exc = mlrun.errors.MLRunBadRequestError(
@@ -54,10 +73,26 @@ def format_obj(
         return format_method(obj)
 
     @staticmethod
-    def filter_obj_method(_filter: list[list[str]]) -> typing.Callable:
+    def filter_obj_method(_filter: list[str]) -> typing.Callable:
+        """
+        Returns a method that filters the object based on the provided list of keys.
+        The keys should be in a dot-separated format, denoting the path within the dictionary to the desired key.
+        The object maintains its structure, with the filtered keys and their values, while all other keys are removed.
+        :param _filter: The list of keys to filter by.
+                        Example:
+                        [
+                            "kind",
+                            "metadata.name",
+                            "spec.something.else",
+                        ]
+
+        :return: The filtering method.
+        """
+
         def _filter_method(obj: dict) -> dict:
             formatted_obj = {}
-            for key_list in _filter:
+            for key in _filter:
+                key_list = key.split(".")
                 obj_recursive_iterator = obj
                 formatted_obj_recursive_iterator = formatted_obj
                 for idx, key in enumerate(key_list):

diff --git a/mlrun/common/formatters/function.py b/mlrun/common/formatters/function.py
@@ -29,18 +29,18 @@ def format_method(_format: str) -> typing.Optional[typing.Callable]:
             FunctionFormat.full: None,
             FunctionFormat.minimal: FunctionFormat.filter_obj_method(
                 [
-                    ["kind"],
-                    ["metadata"],
-                    ["status"],
-                    ["spec", "description"],
-                    ["spec", "command"],
-                    ["spec", "image"],
-                    ["spec", "default_handler"],
-                    ["spec", "default_class"],
-                    ["spec", "graph"],
-                    ["spec", "preemption_mode"],
-                    ["spec", "node_selector"],
-                    ["spec", "priority_class_name"],
+                    "kind",
+                    "metadata",
+                    "status",
+                    "spec.description",
+                    "spec.command",
+                    "spec.image",
+                    "spec.default_handler",
+                    "spec.default_class",
+                    "spec.graph",
+                    "spec.preemption_mode",
+                    "spec.node_selector",
+                    "spec.priority_class_name",
                 ]
             ),
         }[_format]