2828from langchain_core ._api .internal import is_caller_internal
2929
3030
31+ def _build_deprecation_message (
32+ * ,
33+ alternative : str = "" ,
34+ alternative_import : str = "" ,
35+ ) -> str :
36+ """Build a simple deprecation message for `__deprecated__` attribute.
37+
38+ Args:
39+ alternative: An alternative API name.
40+ alternative_import: A fully qualified import path for the alternative.
41+
42+ Returns:
43+ A deprecation message string for IDE/type checker display.
44+ """
45+ if alternative_import :
46+ return f"Use { alternative_import }
47+ if alternative :
48+ return f"Use { alternative }
49+ return "Deprecated."
50+
51+
3152class LangChainDeprecationWarning (DeprecationWarning ):
3253 """A class for issuing deprecation warnings for LangChain users."""
3354
@@ -81,60 +102,57 @@ def deprecated(
81102) -> Callable [[T ], T ]:
82103 """Decorator to mark a function, a class, or a property as deprecated.
83104
84- When deprecating a classmethod, a staticmethod, or a property, the
85- `@deprecated` decorator should go *under* `@classmethod` and
86- `@staticmethod` (i.e., `deprecated` should directly decorate the
87- underlying callable), but *over* `@property`.
105+ When deprecating a classmethod, a staticmethod, or a property, the `@deprecated`
106+ decorator should go *under* `@classmethod` and `@staticmethod` (i.e., `deprecated`
107+ should directly decorate the underlying callable), but *over* `@property`.
88108
89- When deprecating a class `C` intended to be used as a base class in a
90- multiple inheritance hierarchy, `C` *must* define an `__init__` method
91- (if `C` instead inherited its `__init__` from its own base class, then
92- `@deprecated` would mess up `__init__` inheritance when installing its
93- own (deprecation-emitting) `C.__init__`).
109+ When deprecating a class `C` intended to be used as a base class in a multiple
110+ inheritance hierarchy, `C` *must* define an `__init__` method (if `C` instead
111+ inherited its `__init__` from its own base class, then `@deprecated` would mess up
112+ `__init__` inheritance when installing its own (deprecation-emitting) `C.__init__`).
94113
95- Parameters are the same as for `warn_deprecated`, except that *obj_type*
96- defaults to 'class' if decorating a class, 'attribute' if decorating a
97- property, and 'function' otherwise.
114+ Parameters are the same as for `warn_deprecated`, except that *obj_type* defaults to
115+ 'class' if decorating a class, 'attribute' if decorating a property, and 'function'
116+ otherwise.
98117
99118 Args:
100- since:
101- The release at which this API became deprecated.
102- message:
103- Override the default deprecation message. The %(since)s,
104- %(name)s, %(alternative)s, %(obj_type)s, %(addendum)s,
105- and %(removal)s format specifiers will be replaced by the
119+ since: The release at which this API became deprecated.
120+ message: Override the default deprecation message.
121+
122+ The `%(since)s`, `%(name)s`, `%(alternative)s`, `%(obj_type)s`,
123+ `%(addendum)s`, and `%(removal)s` format specifiers will be replaced by the
106124 values of the respective arguments passed to this function.
107- name:
108- The name of the deprecated object.
109- alternative:
110- An alternative API that the user may use in place of the
111- deprecated API. The deprecation warning will tell the user
112- about this alternative if provided.
113- alternative_import:
114- An alternative import that the user may use instead.
115- pending:
116- If `True`, uses a `PendingDeprecationWarning` instead of a
117- DeprecationWarning. Cannot be used together with removal.
118- obj_type:
119- The object type being deprecated.
120- addendum:
121- Additional text appended directly to the final message.
122- removal:
123- The expected removal version. With the default (an empty
124- string), a removal version is automatically computed from
125- since. Set to other Falsy values to not schedule a removal
126- date. Cannot be used together with pending.
127- package:
128- The package of the deprecated object.
125+ name: The name of the deprecated object.
126+ alternative: An alternative API that the user may use in place of the deprecated
127+ API.
128+
129+ The deprecation warning will tell the user about this alternative if
130+ provided.
131+ alternative_import: An alternative import that the user may use instead.
132+ pending: If `True`, uses a `PendingDeprecationWarning` instead of a
133+ `DeprecationWarning`.
134+
135+ Cannot be used together with removal.
136+ obj_type: The object type being deprecated.
137+ addendum: Additional text appended directly to the final message.
138+ removal: The expected removal version.
139+
140+ With the default (an empty string), a removal version is automatically
141+ computed from since. Set to other Falsy values to not schedule a removal
142+ date.
143+
144+ Cannot be used together with pending.
145+ package: The package of the deprecated object.
129146
130147 Returns:
131148 A decorator to mark a function or class as deprecated.
132149
133- ```python
134- @deprecated("1.4.0")
135- def the_function_to_deprecate():
136- pass
137- ```
150+ Example:
151+ ```python
152+ @deprecated("1.4.0")
153+ def the_function_to_deprecate():
154+ pass
155+ ```
138156 """
139157 _validate_deprecation_params (
140158 removal , alternative , alternative_import , pending = pending
@@ -223,6 +241,11 @@ def warn_if_direct_instance(
223241 obj .__init__ = functools .wraps (obj .__init__ )( # type: ignore[misc]
224242 warn_if_direct_instance
225243 )
244+ # Set __deprecated__ for PEP 702 (IDE/type checker support)
245+ obj .__deprecated__ = _build_deprecation_message ( # type: ignore[attr-defined]
246+ alternative = alternative ,
247+ alternative_import = alternative_import ,
248+ )
226249 return obj
227250
228251 elif isinstance (obj , FieldInfoV1 ):
@@ -315,12 +338,15 @@ def __set_name__(self, owner: type | None, set_name: str) -> None:
315338
316339 def finalize (wrapper : Callable [..., Any ], new_doc : str ) -> T : # noqa: ARG001
317340 """Finalize the property."""
318- return cast (
319- "T" ,
320- _DeprecatedProperty (
321- fget = obj .fget , fset = obj .fset , fdel = obj .fdel , doc = new_doc
322- ),
341+ prop = _DeprecatedProperty (
342+ fget = obj .fget , fset = obj .fset , fdel = obj .fdel , doc = new_doc
323343 )
344+ # Set __deprecated__ for PEP 702 (IDE/type checker support)
345+ prop .__deprecated__ = _build_deprecation_message ( # type: ignore[attr-defined]
346+ alternative = alternative ,
347+ alternative_import = alternative_import ,
348+ )
349+ return cast ("T" , prop )
324350
325351 else :
326352 _name = _name or cast ("type | Callable" , obj ).__qualname__
@@ -343,6 +369,11 @@ def finalize(wrapper: Callable[..., Any], new_doc: str) -> T:
343369 """
344370 wrapper = functools .wraps (wrapped )(wrapper )
345371 wrapper .__doc__ = new_doc
372+ # Set __deprecated__ for PEP 702 (IDE/type checker support)
373+ wrapper .__deprecated__ = _build_deprecation_message ( # type: ignore[attr-defined]
374+ alternative = alternative ,
375+ alternative_import = alternative_import ,
376+ )
346377 return cast ("T" , wrapper )
347378
348379 old_doc = inspect .cleandoc (old_doc or "" ).strip ("\n " )
@@ -398,7 +429,7 @@ def finalize(wrapper: Callable[..., Any], new_doc: str) -> T:
398429
399430@contextlib .contextmanager
400431def suppress_langchain_deprecation_warning () -> Generator [None , None , None ]:
401- """Context manager to suppress LangChainDeprecationWarning."""
432+ """Context manager to suppress ` LangChainDeprecationWarning` ."""
402433 with warnings .catch_warnings ():
403434 warnings .simplefilter ("ignore" , LangChainDeprecationWarning )
404435 warnings .simplefilter ("ignore" , LangChainPendingDeprecationWarning )
@@ -421,35 +452,33 @@ def warn_deprecated(
421452 """Display a standardized deprecation.
422453
423454 Args:
424- since:
425- The release at which this API became deprecated.
426- message:
427- Override the default deprecation message. The %(since)s,
428- %(name)s, %(alternative)s, %(obj_type)s, %(addendum)s,
429- and %(removal)s format specifiers will be replaced by the
455+ since: The release at which this API became deprecated.
456+ message: Override the default deprecation message.
457+
458+ The `%(since)s`, `%(name)s`, `%(alternative)s`, `%(obj_type)s`,
459+ `%(addendum)s`, and `%(removal)s` format specifiers will be replaced by the
430460 values of the respective arguments passed to this function.
431- name:
432- The name of the deprecated object.
433- alternative:
434- An alternative API that the user may use in place of the
435- deprecated API. The deprecation warning will tell the user
436- about this alternative if provided.
437- alternative_import:
438- An alternative import that the user may use instead.
439- pending:
440- If `True`, uses a `PendingDeprecationWarning` instead of a
441- DeprecationWarning. Cannot be used together with removal.
442- obj_type:
443- The object type being deprecated.
444- addendum:
445- Additional text appended directly to the final message.
446- removal:
447- The expected removal version. With the default (an empty
448- string), a removal version is automatically computed from
449- since. Set to other Falsy values to not schedule a removal
450- date. Cannot be used together with pending.
451- package:
452- The package of the deprecated object.
461+ name: The name of the deprecated object.
462+ alternative: An alternative API that the user may use in place of the
463+ deprecated API.
464+
465+ The deprecation warning will tell the user about this alternative if
466+ provided.
467+ alternative_import: An alternative import that the user may use instead.
468+ pending: If `True`, uses a `PendingDeprecationWarning` instead of a
469+ `DeprecationWarning`.
470+
471+ Cannot be used together with removal.
472+ obj_type: The object type being deprecated.
473+ addendum: Additional text appended directly to the final message.
474+ removal: The expected removal version.
475+
476+ With the default (an empty string), a removal version is automatically
477+ computed from since. Set to other Falsy values to not schedule a removal
478+ date.
479+
480+ Cannot be used together with pending.
481+ package: The package of the deprecated object.
453482 """
454483 if not pending :
455484 if not removal :
@@ -534,8 +563,8 @@ def rename_parameter(
534563 """Decorator indicating that parameter *old* of *func* is renamed to *new*.
535564
536565 The actual implementation of *func* should use *new*, not *old*. If *old* is passed
537- to *func*, a DeprecationWarning is emitted, and its value is used, even if *new* is
538- also passed by keyword.
566+ to *func*, a ` DeprecationWarning` is emitted, and its value is used, even if *new*
567+ is also passed by keyword.
539568
540569 Args:
541570 since: The version in which the parameter was renamed.
0 commit comments