github/langchain
1
0
Fork 0
mirror of https://github.com/hwchase17/langchain.git synced 2025-06-19 05:13:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: show deprecation warning first in api ref (#25001)

Browse Source 
OLD
![Screenshot 2024-08-02 at 3 29 39
PM](https://github.com/user-attachments/assets/7f169121-1202-4770-a006-d72ac7a1aa33)


NEW
![Screenshot 2024-08-02 at 3 29 45
PM](https://github.com/user-attachments/assets/9cc07cbd-2ae9-4077-95c5-03cb051e6cd7)
This commit is contained in:
Bagatur 2024-08-02 17:35:25 -07:00 committed by GitHub
parent 679843abb0
commit 57747892ce
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 21 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
libs/core/langchain_core/_api/deprecation.py
View File

@ -279,23 +279,22 @@ def deprecated(
old_doc = "" old_doc = ""
# Modify the docstring to include a deprecation notice. # Modify the docstring to include a deprecation notice.
notes_header = "\nNotes\n-----"
components = [ components = [
message, _message,
f"Use {alternative} instead." if alternative else "", f"Use ``{_alternative}`` instead." if _alternative else "",
addendum, f"Use ``{_alternative_import}`` instead." if _alternative_import else "",
_addendum,
] ]
details = " ".join([component.strip() for component in components if component]) details = " ".join([component.strip() for component in components if component])
package = ( package = (
_package or _name.split(".")[0].replace("_", "-") if "." in _name else None _package or _name.split(".")[0].replace("_", "-") if "." in _name else None
) )
since_str = f"{package}=={since}" if package else since since_str = f"{package}=={since}" if package else since
new_doc = ( new_doc = f"""\
f"[*Deprecated*] {old_doc}\n" .. deprecated:: {since_str} {details}
f"{notes_header if notes_header not in old_doc else ''}\n"
f".. deprecated:: {since_str}\n" {old_doc}\
f" {details}" """
)
if inspect.iscoroutinefunction(obj): if inspect.iscoroutinefunction(obj):
finalized = finalize(awarning_emitting_wrapper, new_doc) finalized = finalize(awarning_emitting_wrapper, new_doc)

24
libs/core/tests/unit_tests/_api/test_deprecation.py
View File

@ -129,7 +129,7 @@ def test_deprecated_function() -> None:
doc = deprecated_function.__doc__ doc = deprecated_function.__doc__
assert isinstance(doc, str) assert isinstance(doc, str)
assert doc.startswith("[*Deprecated*] original doc") assert doc.startswith(".. deprecated::")
assert not inspect.iscoroutinefunction(deprecated_function) assert not inspect.iscoroutinefunction(deprecated_function)
@ -151,7 +151,7 @@ async def test_deprecated_async_function() -> None:
doc = deprecated_function.__doc__ doc = deprecated_function.__doc__
assert isinstance(doc, str) assert isinstance(doc, str)
assert doc.startswith("[*Deprecated*] original doc") assert doc.startswith(".. deprecated::")
assert inspect.iscoroutinefunction(deprecated_async_function) assert inspect.iscoroutinefunction(deprecated_async_function)
@ -171,7 +171,7 @@ def test_deprecated_method() -> None:
doc = obj.deprecated_method.__doc__ doc = obj.deprecated_method.__doc__
assert isinstance(doc, str) assert isinstance(doc, str)
assert doc.startswith("[*Deprecated*] original doc") assert doc.startswith(".. deprecated::")
assert not inspect.iscoroutinefunction(obj.deprecated_method) assert not inspect.iscoroutinefunction(obj.deprecated_method)
@ -194,7 +194,7 @@ async def test_deprecated_async_method() -> None:
doc = obj.deprecated_method.__doc__ doc = obj.deprecated_method.__doc__
assert isinstance(doc, str) assert isinstance(doc, str)
assert doc.startswith("[*Deprecated*] original doc") assert doc.startswith(".. deprecated::")
assert inspect.iscoroutinefunction(obj.deprecated_async_method) assert inspect.iscoroutinefunction(obj.deprecated_async_method)
@ -213,7 +213,7 @@ def test_deprecated_classmethod() -> None:
doc = ClassWithDeprecatedMethods.deprecated_classmethod.__doc__ doc = ClassWithDeprecatedMethods.deprecated_classmethod.__doc__
assert isinstance(doc, str) assert isinstance(doc, str)
assert doc.startswith("[*Deprecated*] original doc") assert doc.startswith(".. deprecated::")
def test_deprecated_staticmethod() -> None: def test_deprecated_staticmethod() -> None:
@ -233,7 +233,7 @@ def test_deprecated_staticmethod() -> None:
) )
doc = ClassWithDeprecatedMethods.deprecated_staticmethod.__doc__ doc = ClassWithDeprecatedMethods.deprecated_staticmethod.__doc__
assert isinstance(doc, str) assert isinstance(doc, str)
assert doc.startswith("[*Deprecated*] original doc") assert doc.startswith(".. deprecated::")
def test_deprecated_property() -> None: def test_deprecated_property() -> None:
@ -253,7 +253,7 @@ def test_deprecated_property() -> None:
) )
doc = ClassWithDeprecatedMethods.deprecated_property.__doc__ doc = ClassWithDeprecatedMethods.deprecated_property.__doc__
assert isinstance(doc, str) assert isinstance(doc, str)
assert doc.startswith("[*Deprecated*] original doc") assert doc.startswith(".. deprecated::")
def test_whole_class_deprecation() -> None: def test_whole_class_deprecation() -> None:
@ -292,7 +292,7 @@ def test_whole_class_deprecation() -> None:
) )
# [*Deprecated*] should be inserted only once: # [*Deprecated*] should be inserted only once:
if obj.__doc__ is not None: if obj.__doc__ is not None:
assert obj.__doc__.count("[*Deprecated*]") == 1 assert obj.__doc__.count(".. deprecated") == 1
def test_whole_class_inherited_deprecation() -> None: def test_whole_class_inherited_deprecation() -> None:
@ -349,7 +349,7 @@ def test_whole_class_inherited_deprecation() -> None:
) )
# if [*Deprecated*] was inserted only once: # if [*Deprecated*] was inserted only once:
if obj.__doc__ is not None: if obj.__doc__ is not None:
assert obj.__doc__.count("[*Deprecated*]") == 1 assert obj.__doc__.count(".. deprecated") == 1
with warnings.catch_warnings(record=True) as warning_list: with warnings.catch_warnings(record=True) as warning_list:
warnings.simplefilter("always") warnings.simplefilter("always")
@ -373,8 +373,8 @@ def test_whole_class_inherited_deprecation() -> None:
) )
# if [*Deprecated*] was inserted only once: # if [*Deprecated*] was inserted only once:
if obj.__doc__ is not None: if obj.__doc__ is not None:
assert obj.__doc__.count("[*Deprecated*]") == 1 assert obj.__doc__.count(".. deprecated::") == 1
assert "[*Deprecated*] Inherited deprecated class." in obj.__doc__ assert ".. deprecated::" in obj.__doc__
# Tests with pydantic models # Tests with pydantic models
@ -400,7 +400,7 @@ def test_deprecated_method_pydantic() -> None:
doc = obj.deprecated_method.__doc__ doc = obj.deprecated_method.__doc__
assert isinstance(doc, str) assert isinstance(doc, str)
assert doc.startswith("[*Deprecated*] original doc") assert doc.startswith(".. deprecated::")
def test_raise_error_for_bad_decorator() -> None: def test_raise_error_for_bad_decorator() -> None: