Enhance deprecation decorator to modify docs with sphinx directives (#9069)

Enhance deprecation decorator

libs/langchain/langchain/_api/deprecation.py

@@ -293,6 +293,21 @@ def deprecated(
         else:
             new_doc = f"[*Deprecated*]  {old_doc}"
 
+        # Modify the docstring to include a deprecation notice.
+        notes_header = "\nNotes\n-----"
+        components = [
+            message,
+            f"Use {alternative} instead." if alternative else "",
+            addendum,
+        ]
+        details = " ".join([component.strip() for component in components if component])
+        new_doc += (
+            f"[*Deprecated*] {old_doc}\n"
+            f"{notes_header if notes_header not in old_doc else ''}\n"
+            f".. deprecated:: {since}\n"
+            f"   {details}"
+        )
+
         return finalize(warning_emitting_wrapper, new_doc)
 
     return deprecate

libs/langchain/langchain/prompts/chat.py

@@ -431,7 +431,7 @@ class ChatPromptTemplate(BaseChatPromptTemplate, ABC):
         return cls.from_messages([message])
 
     @classmethod
-    @deprecated("0.0.260", alternative="from_messages classmethod.", pending=True)
+    @deprecated("0.0.260", alternative="from_messages classmethod", pending=True)
     def from_role_strings(
         cls, string_messages: List[Tuple[str, str]]
     ) -> ChatPromptTemplate:
@@ -451,7 +451,7 @@ class ChatPromptTemplate(BaseChatPromptTemplate, ABC):
         )
 
     @classmethod
-    @deprecated("0.0.260", alternative="from_messages classmethod.", pending=True)
+    @deprecated("0.0.260", alternative="from_messages classmethod", pending=True)
     def from_strings(
         cls, string_messages: List[Tuple[Type[BaseMessagePromptTemplate], str]]
     ) -> ChatPromptTemplate:

libs/langchain/tests/unit_tests/_api/test_deprecation.py

@@ -115,7 +115,9 @@ def test_deprecated_function() -> None:
             "and will be removed in 3.0.0"
         )
 
-        assert deprecated_function.__doc__ == "[*Deprecated*]  original doc"
+        doc = deprecated_function.__doc__
+        assert isinstance(doc, str)
+        assert doc.startswith("[*Deprecated*]  original doc")
 
 
 def test_deprecated_method() -> None:
@@ -131,7 +133,9 @@ def test_deprecated_method() -> None:
             "LangChain 2.0.0 and will be removed in 3.0.0"
         )
 
-        assert obj.deprecated_method.__doc__ == "[*Deprecated*]  original doc"
+        doc = obj.deprecated_method.__doc__
+        assert isinstance(doc, str)
+        assert doc.startswith("[*Deprecated*]  original doc")
 
 
 def test_deprecated_classmethod() -> None:
@@ -145,10 +149,10 @@ def test_deprecated_classmethod() -> None:
             "The function `deprecated_classmethod` was deprecated in "
             "LangChain 2.0.0 and will be removed in 3.0.0"
         )
-        assert (
-            ClassWithDeprecatedMethods.deprecated_classmethod.__doc__
-            == "[*Deprecated*]  original doc"
-        )
+
+        doc = ClassWithDeprecatedMethods.deprecated_classmethod.__doc__
+        assert isinstance(doc, str)
+        assert doc.startswith("[*Deprecated*]  original doc")
 
 
 def test_deprecated_staticmethod() -> None:
@@ -166,10 +170,9 @@ def test_deprecated_staticmethod() -> None:
             "The function `deprecated_staticmethod` was deprecated in "
             "LangChain 2.0.0 and will be removed in 3.0.0"
         )
-        assert (
-            ClassWithDeprecatedMethods.deprecated_staticmethod.__doc__
-            == "[*Deprecated*]  original doc"
-        )
+        doc = ClassWithDeprecatedMethods.deprecated_staticmethod.__doc__
+        assert isinstance(doc, str)
+        assert doc.startswith("[*Deprecated*]  original doc")
 
 
 def test_deprecated_property() -> None:
@@ -187,10 +190,9 @@ def test_deprecated_property() -> None:
             "The function `deprecated_property` was deprecated in "
             "LangChain 2.0.0 and will be removed in 3.0.0"
         )
-        assert (
-            ClassWithDeprecatedMethods.deprecated_property.__doc__
-            == "[*Deprecated*]  original doc"
-        )
+        doc = ClassWithDeprecatedMethods.deprecated_property.__doc__
+        assert isinstance(doc, str)
+        assert doc.startswith("[*Deprecated*]  original doc")
 
 
 def test_whole_class_deprecation() -> None:
@@ -249,4 +251,6 @@ def test_deprecated_method_pydantic() -> None:
             "LangChain 2.0.0 and will be removed in 3.0.0"
         )
 
-        assert obj.deprecated_method.__doc__ == "[*Deprecated*]  original doc"
+        doc = obj.deprecated_method.__doc__
+        assert isinstance(doc, str)
+        assert doc.startswith("[*Deprecated*]  original doc")