Merge branch 'master' into ruff-core-preview-2

Author: mdrxy

libs/core/langchain_core/_api/beta_decorator.py

@@ -63,6 +63,9 @@ def beta(
         addendum : str, optional
             Additional text appended directly to the final message.
 
+    Returns:
+        A decorator which can be used to mark functions or classes as beta.
+
     Examples:
 
         .. code-block:: python

libs/core/langchain_core/_api/deprecation.py

@@ -129,6 +129,9 @@ def deprecated(
         package: str, optional
             The package of the deprecated object.
 
+    Returns:
+        A decorator to mark a function or class as deprecated.
+
     Examples:
 
         .. code-block:: python
@@ -545,6 +548,15 @@ def rename_parameter(
     is passed 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.
+        removal: The version in which the old parameter will be removed.
+        old: The old parameter name.
+        new: The new parameter name.
+
+    Returns:
+        A decorator indicating that a parameter was renamed.
+
     Example:
 
         .. code-block:: python

libs/core/langchain_core/_api/path.py

@@ -12,7 +12,15 @@
 def get_relative_path(
     file: Union[Path, str], *, relative_to: Path = PACKAGE_DIR
 ) -> str:
-    """Get the path of the file as a relative path to the package directory."""
+    """Get the path of the file as a relative path to the package directory.
+
+    Args:
+        file: The file path to convert.
+        relative_to: The base path to make the file path relative to.
+
+    Returns:
+        The relative path as a string.
+    """
     if isinstance(file, str):
         file = Path(file)
     return str(file.relative_to(relative_to))
@@ -24,7 +32,16 @@ def as_import_path(
     suffix: Optional[str] = None,
     relative_to: Path = PACKAGE_DIR,
 ) -> str:
-    """Path of the file as a LangChain import exclude langchain top namespace."""
+    """Path of the file as a LangChain import exclude langchain top namespace.
+
+    Args:
+        file: The file path to convert.
+        suffix: An optional suffix to append to the import path.
+        relative_to: The base path to make the file path relative to.
+
+    Returns:
+        The import path as a string.
+    """
     if isinstance(file, str):
         file = Path(file)
     path = get_relative_path(file, relative_to=relative_to)

libs/core/langchain_core/_import_utils.py

@@ -17,6 +17,13 @@ def import_attr(
         module_name: The name of the module to import from. If None, the attribute
             is imported from the package itself.
         package: The name of the package where the module is located.
+
+    Raises:
+        ImportError: If the module cannot be found.
+        AttributeError: If the attribute does not exist in the module or package.
+
+    Returns:
+        The imported attribute.
     """
     if module_name == "__module__" or module_name is None:
         try:

libs/core/langchain_core/agents.py

@@ -86,7 +86,8 @@ def is_lc_serializable(cls) -> bool:
     def get_lc_namespace(cls) -> list[str]:
         """Get the namespace of the langchain object.
 
-        Default is ["langchain", "schema", "agent"].
+        Returns:
+            ``["langchain", "schema", "agent"]``
         """
         return ["langchain", "schema", "agent"]
 
@@ -155,14 +156,15 @@ def __init__(self, return_values: dict, log: str, **kwargs: Any):
 
     @classmethod
     def is_lc_serializable(cls) -> bool:
-        """Return whether or not the class is serializable."""
+        """Return True as this class is serializable."""
         return True
 
     @classmethod
     def get_lc_namespace(cls) -> list[str]:
         """Get the namespace of the langchain object.
 
-        Default namespace is ["langchain", "schema", "agent"].
+        Returns:
+            ``["langchain", "schema", "agent"]``
         """
         return ["langchain", "schema", "agent"]
 

libs/core/langchain_core/callbacks/base.py

@@ -922,7 +922,7 @@ def __init__(
         self.inheritable_metadata = inheritable_metadata or {}
 
     def copy(self) -> Self:
-        """Copy the callback manager."""
+        """Return a copy of the callback manager."""
         return self.__class__(
             handlers=self.handlers.copy(),
             inheritable_handlers=self.inheritable_handlers.copy(),

libs/core/langchain_core/callbacks/manager.py

@@ -88,8 +88,8 @@ def trace_as_chain_group(
         Must have ``LANGCHAIN_TRACING_V2`` env var set to true to see the trace in
         LangSmith.
 
-    Returns:
-        CallbackManagerForChainGroup: The callback manager for the chain group.
+    Yields:
+        The callback manager for the chain group.
 
     Example:
         .. code-block:: python
@@ -170,8 +170,8 @@ async def atrace_as_chain_group(
         metadata (dict[str, Any], optional): The metadata to apply to all runs.
             Defaults to None.
 
-    Returns:
-        AsyncCallbackManager: The async callback manager for the chain group.
+    Yields:
+        The async callback manager for the chain group.
 
     .. note:
         Must have ``LANGCHAIN_TRACING_V2`` env var set to true to see the trace in
@@ -519,15 +519,12 @@ def on_text(
         self,
         text: str,
         **kwargs: Any,
-    ) -> Any:
+    ) -> None:
         """Run when a text is received.
 
         Args:
             text (str): The received text.
             **kwargs (Any): Additional keyword arguments.
-
-        Returns:
-            Any: The result of the callback.
         """
         if not self.handlers:
             return
@@ -607,16 +604,12 @@ async def on_text(
         self,
         text: str,
         **kwargs: Any,
-    ) -> Any:
+    ) -> None:
         """Run when a text is received.
 
         Args:
             text (str): The received text.
             **kwargs (Any): Additional keyword arguments.
-
-        Returns:
-            Any: The result of the callback.
-
         """
         if not self.handlers:
             return
@@ -914,16 +907,12 @@ def on_chain_error(
             **kwargs,
         )
 
-    def on_agent_action(self, action: AgentAction, **kwargs: Any) -> Any:
+    def on_agent_action(self, action: AgentAction, **kwargs: Any) -> None:
         """Run when agent action is received.
 
         Args:
             action (AgentAction): The agent action.
             **kwargs (Any): Additional keyword arguments.
-
-        Returns:
-            Any: The result of the callback.
-
         """
         if not self.handlers:
             return
@@ -938,16 +927,12 @@ def on_agent_action(self, action: AgentAction, **kwargs: Any) -> Any:
             **kwargs,
         )
 
-    def on_agent_finish(self, finish: AgentFinish, **kwargs: Any) -> Any:
+    def on_agent_finish(self, finish: AgentFinish, **kwargs: Any) -> None:
         """Run when agent finish is received.
 
         Args:
             finish (AgentFinish): The agent finish.
             **kwargs (Any): Additional keyword arguments.
-
-        Returns:
-            Any: The result of the callback.
-
         """
         if not self.handlers:
             return
@@ -1033,16 +1018,12 @@ async def on_chain_error(
             **kwargs,
         )
 
-    async def on_agent_action(self, action: AgentAction, **kwargs: Any) -> Any:
+    async def on_agent_action(self, action: AgentAction, **kwargs: Any) -> None:
         """Run when agent action is received.
 
         Args:
             action (AgentAction): The agent action.
             **kwargs (Any): Additional keyword arguments.
-
-        Returns:
-            Any: The result of the callback.
-
         """
         if not self.handlers:
             return
@@ -1057,16 +1038,12 @@ async def on_agent_action(self, action: AgentAction, **kwargs: Any) -> Any:
             **kwargs,
         )
 
-    async def on_agent_finish(self, finish: AgentFinish, **kwargs: Any) -> Any:
+    async def on_agent_finish(self, finish: AgentFinish, **kwargs: Any) -> None:
         """Run when agent finish is received.
 
         Args:
             finish (AgentFinish): The agent finish.
             **kwargs (Any): Additional keyword arguments.
-
-        Returns:
-            Any: The result of the callback.
-
         """
         if not self.handlers:
             return
@@ -1562,6 +1539,8 @@ def on_retriever_start(
             parent_run_id (UUID, optional): The ID of the parent run. Defaults to None.
             **kwargs (Any): Additional keyword arguments.
 
+        Returns:
+            The callback manager for the retriever run.
         """
         if run_id is None:
             run_id = uuid.uuid4()
@@ -1608,6 +1587,9 @@ def on_custom_event(
             data: The data for the adhoc event.
             run_id: The ID of the run. Defaults to None.
 
+        Raises:
+            ValueError: If additional keyword arguments are passed.
+
         .. versionadded:: 0.2.14
 
         """
@@ -1710,8 +1692,8 @@ def __init__(
         self.parent_run_manager = parent_run_manager
         self.ended = False
 
+    @override
     def copy(self) -> CallbackManagerForChainGroup:
-        """Copy the callback manager."""
         return self.__class__(
             handlers=self.handlers.copy(),
             inheritable_handlers=self.inheritable_handlers.copy(),
@@ -2099,6 +2081,9 @@ async def on_custom_event(
             data: The data for the adhoc event.
             run_id: The ID of the run. Defaults to None.
 
+        Raises:
+            ValueError: If additional keyword arguments are passed.
+
         .. versionadded:: 0.2.14
         """
         if not self.handlers:
@@ -2249,7 +2234,7 @@ def __init__(
         self.ended = False
 
     def copy(self) -> AsyncCallbackManagerForChainGroup:
-        """Copy the async callback manager."""
+        """Return a copy the async callback manager."""
         return self.__class__(
             handlers=self.handlers.copy(),
             inheritable_handlers=self.inheritable_handlers.copy(),
@@ -2385,6 +2370,9 @@ def _configure(
         local_metadata (Optional[dict[str, Any]], optional): The local metadata.
             Defaults to None.
 
+    Raises:
+        RuntimeError: If `LANGCHAIN_TRACING` is set but `LANGCHAIN_TRACING_V2` is not.
+
     Returns:
         T: The configured callback manager.
     """
@@ -2557,6 +2545,10 @@ async def adispatch_custom_event(
               this is not enforced.
         config: Optional config object. Mirrors the async API but not strictly needed.
 
+    Raises:
+        RuntimeError: If there is no parent run ID available to associate
+            the event with.
+
     Example:
 
         .. code-block:: python
@@ -2678,6 +2670,10 @@ def dispatch_custom_event(
               this is not enforced.
         config: Optional config object. Mirrors the async API but not strictly needed.
 
+    Raises:
+        RuntimeError: If there is no parent run ID available to associate
+            the event with.
+
     Example:
 
         .. code-block:: python

libs/core/langchain_core/callbacks/usage.py

@@ -101,6 +101,9 @@ def get_usage_metadata_callback(
         name (str): The name of the context variable. Defaults to
             ``'usage_metadata_callback'``.
 
+    Yields:
+        The usage metadata callback.
+
     Example:
         .. code-block:: python
 

libs/core/langchain_core/chat_history.py

@@ -109,6 +109,9 @@ async def aget_messages(self) -> list[BaseMessage]:
 
         In general, fetching messages may involve IO to the underlying
         persistence layer.
+
+        Returns:
+            The messages.
         """
         from langchain_core.runnables.config import run_in_executor