The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
feat(core): add PEP 702 `__deprecated__` attribute support to `@deprecated` (#34257)
Mason Daugherty85c401f6485b
diff --git a/libs/core/langchain_core/_api/deprecation.py b/libs/core/langchain_core/_api/deprecation.pyindex 5a3e90b539..ede02915fd 100644--- a/libs/core/langchain_core/_api/deprecation.py+++ b/libs/core/langchain_core/_api/deprecation.py@@ -28,6 +28,27 @@ from pydantic.v1.fields import FieldInfo as FieldInfoV1from langchain_core._api.internal import is_caller_internal+def _build_deprecation_message(+ *,+ alternative: str = "",+ alternative_import: str = "",+) -> str:+ """Build a simple deprecation message for `__deprecated__` attribute.++ Args:+ alternative: An alternative API name.+ alternative_import: A fully qualified import path for the alternative.++ Returns:+ A deprecation message string for IDE/type checker display.+ """+ if alternative_import:+ return f"Use {alternative_import} instead."+ if alternative:+ return f"Use {alternative} instead."+ return "Deprecated."++class LangChainDeprecationWarning(DeprecationWarning):"""A class for issuing deprecation warnings for LangChain users."""@@ -81,60 +102,57 @@ def deprecated() -> Callable[[T], T]:"""Decorator to mark a function, a class, or a property as deprecated.- When deprecating a classmethod, a staticmethod, or a property, the- `@deprecated` decorator should go *under* `@classmethod` and- `@staticmethod` (i.e., `deprecated` should directly decorate the- underlying callable), but *over* `@property`.+ When deprecating a classmethod, a staticmethod, or a property, the `@deprecated`+ decorator should go *under* `@classmethod` and `@staticmethod` (i.e., `deprecated`+ should directly decorate the underlying callable), but *over* `@property`.- When deprecating a class `C` intended to be used as a base class in a- multiple inheritance hierarchy, `C` *must* define an `__init__` method- (if `C` instead inherited its `__init__` from its own base class, then- `@deprecated` would mess up `__init__` inheritance when installing its- own (deprecation-emitting) `C.__init__`).+ When deprecating a class `C` intended to be used as a base class in a multiple+ inheritance hierarchy, `C` *must* define an `__init__` method (if `C` instead+ inherited its `__init__` from its own base class, then `@deprecated` would mess up+ `__init__` inheritance when installing its own (deprecation-emitting) `C.__init__`).- Parameters are the same as for `warn_deprecated`, except that *obj_type*- defaults to 'class' if decorating a class, 'attribute' if decorating a- property, and 'function' otherwise.+ Parameters are the same as for `warn_deprecated`, except that *obj_type* defaults to+ 'class' if decorating a class, 'attribute' if decorating a property, and 'function'+ otherwise.Args:- since:- The release at which this API became deprecated.- message:- Override the default deprecation message. The %(since)s,- %(name)s, %(alternative)s, %(obj_type)s, %(addendum)s,- and %(removal)s format specifiers will be replaced by the+ since: The release at which this API became deprecated.+ message: Override the default deprecation message.++ The `%(since)s`, `%(name)s`, `%(alternative)s`, `%(obj_type)s`,+ `%(addendum)s`, and `%(removal)s` format specifiers will be replaced by thevalues of the respective arguments passed to this function.- name:- The name of the deprecated object.- alternative:- An alternative API that the user may use in place of the- deprecated API. The deprecation warning will tell the user- about this alternative if provided.- alternative_import:- An alternative import that the user may use instead.- pending:- If `True`, uses a `PendingDeprecationWarning` instead of a- DeprecationWarning. Cannot be used together with removal.- obj_type:- The object type being deprecated.- addendum:- Additional text appended directly to the final message.- removal:- The expected removal version. With the default (an empty- string), a removal version is automatically computed from- since. Set to other Falsy values to not schedule a removal- date. Cannot be used together with pending.- package:- The package of the deprecated object.+ name: The name of the deprecated object.+ alternative: An alternative API that the user may use in place of the deprecated+ API.++ The deprecation warning will tell the user about this alternative if+ provided.+ alternative_import: An alternative import that the user may use instead.+ pending: If `True`, uses a `PendingDeprecationWarning` instead of a+ `DeprecationWarning`.++ Cannot be used together with removal.+ obj_type: The object type being deprecated.+ addendum: Additional text appended directly to the final message.+ removal: The expected removal version.++ With the default (an empty string), a removal version is automatically+ computed from since. Set to other Falsy values to not schedule a removal+ date.++ Cannot be used together with pending.+ package: The package of the deprecated object.Returns:A decorator to mark a function or class as deprecated.- ```python- @deprecated("1.4.0")- def the_function_to_deprecate():- pass- ```+ Example:+ ```python+ @deprecated("1.4.0")+ def the_function_to_deprecate():+ pass+ ```"""_validate_deprecation_params(removal, alternative, alternative_import, pending=pending@@ -223,6 +241,11 @@ def deprecated(obj.__init__ = functools.wraps(obj.__init__)( # type: ignore[misc]warn_if_direct_instance)+ # Set __deprecated__ for PEP 702 (IDE/type checker support)+ obj.__deprecated__ = _build_deprecation_message( # type: ignore[attr-defined]+ alternative=alternative,+ alternative_import=alternative_import,+ )return objelif isinstance(obj, FieldInfoV1):@@ -315,12 +338,15 @@ def deprecated(def finalize(wrapper: Callable[..., Any], new_doc: str) -> T: # noqa: ARG001"""Finalize the property."""- return cast(- "T",- _DeprecatedProperty(- fget=obj.fget, fset=obj.fset, fdel=obj.fdel, doc=new_doc- ),+ prop = _DeprecatedProperty(+ fget=obj.fget, fset=obj.fset, fdel=obj.fdel, doc=new_doc)+ # Set __deprecated__ for PEP 702 (IDE/type checker support)+ prop.__deprecated__ = _build_deprecation_message( # type: ignore[attr-defined]+ alternative=alternative,+ alternative_import=alternative_import,+ )+ return cast("T", prop)else:_name = _name or cast("type | Callable", obj).__qualname__@@ -343,6 +369,11 @@ def deprecated("""wrapper = functools.wraps(wrapped)(wrapper)wrapper.__doc__ = new_doc+ # Set __deprecated__ for PEP 702 (IDE/type checker support)+ wrapper.__deprecated__ = _build_deprecation_message( # type: ignore[attr-defined]+ alternative=alternative,+ alternative_import=alternative_import,+ )return cast("T", wrapper)old_doc = inspect.cleandoc(old_doc or "").strip("\n")@@ -398,7 +429,7 @@ def deprecated(@contextlib.contextmanagerdef suppress_langchain_deprecation_warning() -> Generator[None, None, None]:- """Context manager to suppress LangChainDeprecationWarning."""+ """Context manager to suppress `LangChainDeprecationWarning`."""with warnings.catch_warnings():warnings.simplefilter("ignore", LangChainDeprecationWarning)warnings.simplefilter("ignore", LangChainPendingDeprecationWarning)@@ -421,35 +452,33 @@ def warn_deprecated("""Display a standardized deprecation.Args:- since:- The release at which this API became deprecated.- message:- Override the default deprecation message. The %(since)s,- %(name)s, %(alternative)s, %(obj_type)s, %(addendum)s,- and %(removal)s format specifiers will be replaced by the+ since: The release at which this API became deprecated.+ message: Override the default deprecation message.++ The `%(since)s`, `%(name)s`, `%(alternative)s`, `%(obj_type)s`,+ `%(addendum)s`, and `%(removal)s` format specifiers will be replaced by thevalues of the respective arguments passed to this function.- name:- The name of the deprecated object.- alternative:- An alternative API that the user may use in place of the- deprecated API. The deprecation warning will tell the user- about this alternative if provided.- alternative_import:- An alternative import that the user may use instead.- pending:- If `True`, uses a `PendingDeprecationWarning` instead of a- DeprecationWarning. Cannot be used together with removal.- obj_type:- The object type being deprecated.- addendum:- Additional text appended directly to the final message.- removal:- The expected removal version. With the default (an empty- string), a removal version is automatically computed from- since. Set to other Falsy values to not schedule a removal- date. Cannot be used together with pending.- package:- The package of the deprecated object.+ name: The name of the deprecated object.+ alternative: An alternative API that the user may use in place of the+ deprecated API.++ The deprecation warning will tell the user about this alternative if+ provided.+ alternative_import: An alternative import that the user may use instead.+ pending: If `True`, uses a `PendingDeprecationWarning` instead of a+ `DeprecationWarning`.++ Cannot be used together with removal.+ obj_type: The object type being deprecated.+ addendum: Additional text appended directly to the final message.+ removal: The expected removal version.++ With the default (an empty string), a removal version is automatically+ computed from since. Set to other Falsy values to not schedule a removal+ date.++ Cannot be used together with pending.+ package: The package of the deprecated object."""if not pending:if not removal:@@ -534,8 +563,8 @@ def rename_parameter("""Decorator indicating that parameter *old* of *func* is renamed to *new*.The actual implementation of *func* should use *new*, not *old*. If *old* is passed- to *func*, a DeprecationWarning is emitted, and its value is used, even if *new* is- also passed by keyword.+ to *func*, a `DeprecationWarning` is emitted, and its value is used, even if *new*+ is also passed by keyword.Args:since: The version in which the parameter was renamed.diff --git a/libs/core/tests/unit_tests/_api/test_deprecation.py b/libs/core/tests/unit_tests/_api/test_deprecation.pyindex 3826da5980..66895eeeae 100644--- a/libs/core/tests/unit_tests/_api/test_deprecation.py+++ b/libs/core/tests/unit_tests/_api/test_deprecation.py@@ -493,3 +493,88 @@ def test_rename_parameter_method() -> None:with pytest.raises(TypeError):assert foo.a("hello", old_name="hello") # type: ignore[call-arg]+++# Tests for PEP 702 __deprecated__ attribute+++def test_deprecated_function_has_pep702_attribute() -> None:+ """Test that deprecated functions have `__deprecated__` attribute."""++ @deprecated(since="2.0.0", removal="3.0.0", alternative="new_function")+ def old_function() -> str:+ """Original doc."""+ return "old"++ assert hasattr(old_function, "__deprecated__")+ assert old_function.__deprecated__ == "Use new_function instead."+++def test_deprecated_function_with_alternative_import_has_pep702_attribute() -> None:+ """Test `__deprecated__` with `alternative_import`."""++ @deprecated(+ since="2.0.0", removal="3.0.0", alternative_import="new_module.new_function"+ )+ def old_function() -> str:+ """Original doc."""+ return "old"++ assert hasattr(old_function, "__deprecated__")+ assert old_function.__deprecated__ == "Use new_module.new_function instead."+++def test_deprecated_function_without_alternative_has_pep702_attribute() -> None:+ """Test `__deprecated__` without alternative shows `'Deprecated.'`."""++ @deprecated(since="2.0.0", removal="3.0.0")+ def old_function() -> str:+ """Original doc."""+ return "old"++ assert hasattr(old_function, "__deprecated__")+ assert old_function.__deprecated__ == "Deprecated."+++def test_deprecated_class_has_pep702_attribute() -> None:+ """Test that deprecated classes have `__deprecated__` attribute (PEP 702)."""++ @deprecated(since="2.0.0", removal="3.0.0", alternative="NewClass")+ class OldClass:+ def __init__(self) -> None:+ """Original doc."""++ assert hasattr(OldClass, "__deprecated__")+ assert OldClass.__deprecated__ == "Use NewClass instead."+++def test_deprecated_class_without_alternative_has_pep702_attribute() -> None:+ """Test `__deprecated__` on class without alternative."""++ @deprecated(since="2.0.0", removal="3.0.0")+ class OldClass:+ def __init__(self) -> None:+ """Original doc."""++ assert hasattr(OldClass, "__deprecated__")+ assert OldClass.__deprecated__ == "Deprecated."+++def test_deprecated_property_has_pep702_attribute() -> None:+ """Test that deprecated properties have `__deprecated__` attribute (PEP 702).++ Note: When using @property over @deprecated (which is what works in practice),+ the `__deprecated__` attribute is set on the property's underlying `fget` function.+ """++ class MyClass:+ @property+ @deprecated(since="2.0.0", removal="3.0.0", alternative="new_property")+ def old_property(self) -> str:+ """Original doc."""+ return "old"++ prop = MyClass.__dict__["old_property"]+ # The __deprecated__ attribute is on the underlying fget function+ assert hasattr(prop.fget, "__deprecated__")+ assert prop.fget.__deprecated__ == "Use new_property instead."