[ENH] improved deep_equals utility - plugins for custom types (#238)

This PR improves the `deep_equals` utility by introducing the ability to
provide custom plugins.

Ultimately, this enables more flexibility in soft dependencies for data
containers such as `polars` (see, e.g.,
sktime/sktime#5423) throughout the `sktime`
package ecosystem, as `deep_equals` is used for extrinsic testing and
validity checking.
Similarly, the `ForecastingHorizon` check should be moved as a plugin
into `sktime`.

In addition, makes the following changes:

* splits up the `deep_equals` file into a module with multiple files

Depends on #239.

skbase/tests/conftest.py

@@ -49,6 +49,8 @@
     "skbase.utils._nested_iter",
     "skbase.utils._utils",
     "skbase.utils.deep_equals",
+    "skbase.utils.deep_equals._common",
+    "skbase.utils.deep_equals._deep_equals",
     "skbase.utils.dependencies",
     "skbase.utils.dependencies._dependencies",
     "skbase.validate",
@@ -160,6 +162,7 @@
     ),
     "skbase.utils._utils": ("subset_dict_keys",),
     "skbase.utils.deep_equals": ("deep_equals",),
+    "skbase.utils.deep_equals._deep_equals": ("deep_equals", "deep_equals_custom"),
     "skbase.validate._types": ("check_sequence", "check_type", "is_sequence"),
 }
 SKBASE_FUNCTIONS_BY_MODULE = SKBASE_PUBLIC_FUNCTIONS_BY_MODULE.copy()
@@ -207,19 +210,22 @@
             "unflatten",
         ),
         "skbase.utils._utils": ("subset_dict_keys",),
-        "skbase.utils.deep_equals": (
+        "skbase.utils.deep_equals": ("deep_equals",),
+        "skbase.utils.deep_equals._common": ("_make_ret", "_ret"),
+        "skbase.utils.deep_equals._deep_equals": (
             "_coerce_list",
             "_dict_equals",
-            "_fh_equals",
+            "_fh_equals_plugin",
             "_is_npnan",
             "_is_npndarray",
             "_is_pandas",
-            "_make_ret",
+            "_numpy_equals_plugin",
             "_pandas_equals",
-            "_ret",
+            "_pandas_equals_plugin",
             "_softdep_available",
             "_tuple_equals",
             "deep_equals",
+            "deep_equals_custom",
         ),
         "skbase.utils.dependencies._dependencies": (
             "_check_soft_dependencies",

skbase/utils/deep_equals/__init__.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+# copyright: skbase developers, BSD-3-Clause License (see LICENSE file)
+"""Module for nested equality checking."""
+from skbase.utils.deep_equals._deep_equals import deep_equals
+
+__all__ = [
+    "deep_equals",
+]

skbase/utils/deep_equals/_common.py

@@ -0,0 +1,41 @@
+# -*- coding: utf-8 -*-
+"""Common utility functions for skbase.utils.deep_equals."""
+
+
+def _ret(is_equal, msg="", string_arguments: list = None, return_msg=False):
+    """Return is_equal and msg, formatted with string_arguments if return_msg=True.
+
+    Parameters
+    ----------
+    is_equal : bool
+    msg : str, optional, default=""
+        message to return if is_equal=False
+    string_arguments : list, optional, default=None
+        list of arguments to format msg with
+
+    Returns
+    -------
+    is_equal : bool
+        identical to input ``is_equal``, always returned
+    msg : str, only returned if return_msg=True
+        if ``is_equal=True``, ``msg`` is always ``""``
+        if ``is_equal=False``, ``msg`` is formatted with ``string_arguments``
+        via ``msg.format(*string_arguments)``
+    """
+    if return_msg:
+        if is_equal:
+            msg = ""
+        elif isinstance(string_arguments, (list, tuple)) and len(string_arguments) > 0:
+            msg = msg.format(*string_arguments)
+        return is_equal, msg
+    else:
+        return is_equal
+
+
+def _make_ret(return_msg):
+    """Curry _ret with return_msg."""
+
+    def ret(is_equal, msg, string_arguments=None):
+        return _ret(is_equal, msg, string_arguments, return_msg)
+
+    return ret