Custom deprecation message in API endpoints and Python commands (#5942)

* add custom deprecation message feature in routers

* add custom deprecation message feature in package builder

* using an actual DeprecationWarning instead

* fix tests

---------

Co-authored-by: Igor Radovanovic <74266147+IgorWounds@users.noreply.github.com>
Co-authored-by: hjoaquim <h.joaquim@campus.fct.unl.pt>

3 files changed, 36 insertions, 3 deletions

diff --git a/openbb_platform/core/openbb_core/app/router.py b/openbb_platform/core/openbb_core/app/router.py
index 9f240f2b513..011baa1d070 100644
--- a/openbb_platform/core/openbb_core/app/router.py
+++ b/openbb_platform/core/openbb_core/app/router.py
@@ -230,6 +230,8 @@ class Router:
         api_router = self._api_router
 
         model = kwargs.pop("model", "")
+        deprecation_message = kwargs.pop("deprecation_message", None)
+
         if model:
             kwargs["response_model_exclude_unset"] = True
             kwargs["openapi_extra"] = {"model": model}
@@ -268,6 +270,15 @@ class Router:
                 },
             )
 
+            # For custom deprecation messages
+            if kwargs.get("deprecated", False):
+                if deprecation_message:
+                    kwargs["summary"] = deprecation_message
+                else:
+                    kwargs[
+                        "summary"
+                    ] = "This functionality will be deprecated in the future releases."
+
             api_router.add_api_route(**kwargs)
 
         return func
diff --git a/openbb_platform/core/openbb_core/app/static/package_builder.py b/openbb_platform/core/openbb_core/app/static/package_builder.py
index f44fe1653c3..068ef5865cb 100644
--- a/openbb_platform/core/openbb_core/app/static/package_builder.py
+++ b/openbb_platform/core/openbb_core/app/static/package_builder.py
@@ -478,6 +478,16 @@ class MethodDefinition:
         return "POST" in methods
 
     @staticmethod
+    def is_deprecated_function(path: str) -> bool:
+        """Check if the function is deprecated."""
+        return getattr(PathHandler.build_route_map()[path], "deprecated", False)
+
+    @staticmethod
+    def get_deprecation_message(path: str) -> str:
+        """Get the deprecation message."""
+        return getattr(PathHandler.build_route_map()[path], "summary", "")
+
+    @staticmethod
     def reorder_params(params: Dict[str, Parameter]) -> "OrderedDict[str, Parameter]":
         """Reorder the params."""
         formatted_keys = list(params.keys())
@@ -668,6 +678,7 @@ class MethodDefinition:
         sig = signature(func)
         parameter_map = dict(sig.parameters)
         parameter_map.pop("cc", None)
+        code = ""
 
         if (
             path.replace("/", "_")[1:]
@@ -680,7 +691,12 @@ class MethodDefinition:
                 default=False,
             )
 
-        code = "        return self._run(\n"
+        if MethodDefinition.is_deprecated_function(path):
+            deprecation_message = MethodDefinition.get_deprecation_message(path)
+            code += "        from warnings import warn, simplefilter; simplefilter('always', DeprecationWarning)\n"
+            code += f"""        warn("{deprecation_message}", category=DeprecationWarning, stacklevel=2)\n\n"""
+
+        code += "        return self._run(\n"
         code += f"""            "{path}",\n"""
         code += "            **filter_inputs(\n"
         for name, param in parameter_map.items():
diff --git a/openbb_platform/core/tests/app/static/test_package_builder.py b/openbb_platform/core/tests/app/static/test_package_builder.py
index 9c7c17b5681..c1d4e40782a 100644
--- a/openbb_platform/core/tests/app/static/test_package_builder.py
+++ b/openbb_platform/core/tests/app/static/test_package_builder.py
@@ -302,7 +302,10 @@ def test_build_command_method_body(method_definition):
 
     with patch(
         "openbb_core.app.static.package_builder.MethodDefinition.is_data_processing_function",
-        **{"return_value": False},
+        return_value=False,
+    ), patch(
+        "openbb_core.app.static.package_builder.MethodDefinition.is_deprecated_function",
+        return_value=False,
     ):
         output = method_definition.build_command_method_body(
             path="openbb_core.app.static.container.Container", func=some_func
@@ -321,7 +324,10 @@ def test_build_command_method(method_definition):
 
     with patch(
         "openbb_core.app.static.package_builder.MethodDefinition.is_data_processing_function",
-        **{"return_value": False},
+        return_value=False,
+    ), patch(
+        "openbb_core.app.static.package_builder.MethodDefinition.is_deprecated_function",
+        return_value=False,
     ):
         output = method_definition.build_command_method(
             path="openbb_core.app.static.container.Container",