langchain-core 0.4.0.dev0__py3-none-any.whl → 1.0.0__py3-none-any.whl

langchain_core/runnables/utils.py

@@ -5,8 +5,9 @@ from __future__ import annotations
 import ast
 import asyncio
 import inspect
+import sys
 import textwrap
-from collections.abc import Mapping, Sequence
+from collections.abc import Callable, Mapping, Sequence
 from contextvars import Context
 from functools import lru_cache
 from inspect import signature
@@ -14,15 +15,13 @@ from itertools import groupby
 from typing import (
     TYPE_CHECKING,
     Any,
-    Callable,
     NamedTuple,
-    Optional,
     Protocol,
+    TypeGuard,
     TypeVar,
-    Union,
 )
 
-from typing_extensions import TypeGuard, override
+from typing_extensions import override
 
 # Re-export create-model for backwards compatibility
 from langchain_core.utils.pydantic import create_model  # noqa: F401
@@ -57,7 +56,7 @@ async def gated_coro(semaphore: asyncio.Semaphore, coro: Coroutine) -> Any:
         return await coro
 
 
-async def gather_with_concurrency(n: Union[int, None], *coros: Coroutine) -> list:
+async def gather_with_concurrency(n: int | None, *coros: Coroutine) -> list:
     """Gather coroutines with a limit on the number of concurrent coroutines.
 
     Args:
@@ -82,7 +81,7 @@ def accepts_run_manager(callable: Callable[..., Any]) -> bool:  # noqa: A002
         callable: The callable to check.
 
     Returns:
-        bool: True if the callable accepts a run_manager argument, False otherwise.
+        `True` if the callable accepts a run_manager argument, `False` otherwise.
     """
     try:
         return signature(callable).parameters.get("run_manager") is not None
@@ -97,7 +96,7 @@ def accepts_config(callable: Callable[..., Any]) -> bool:  # noqa: A002
         callable: The callable to check.
 
     Returns:
-        bool: True if the callable accepts a config argument, False otherwise.
+        `True` if the callable accepts a config argument, `False` otherwise.
     """
     try:
         return signature(callable).parameters.get("config") is not None
@@ -112,7 +111,7 @@ def accepts_context(callable: Callable[..., Any]) -> bool:  # noqa: A002
         callable: The callable to check.
 
     Returns:
-        bool: True if the callable accepts a context argument, False otherwise.
+        `True` if the callable accepts a context argument, `False` otherwise.
     """
     try:
         return signature(callable).parameters.get("context") is not None
@@ -120,10 +119,13 @@ def accepts_context(callable: Callable[..., Any]) -> bool:  # noqa: A002
         return False
 
 
-@lru_cache(maxsize=1)
 def asyncio_accepts_context() -> bool:
-    """Cache the result of checking if asyncio.create_task accepts a ``context`` arg."""
-    return accepts_context(asyncio.create_task)
+    """Check if asyncio.create_task accepts a `context` arg.
+
+    Returns:
+        True if `asyncio.create_task` accepts a context argument, `False` otherwise.
+    """
+    return sys.version_info >= (3, 11)
 
 
 def coro_with_context(
@@ -134,7 +136,7 @@ def coro_with_context(
     Args:
         coro: The coroutine to await.
         context: The context to use.
-        create_task: Whether to create a task. Defaults to False.
+        create_task: Whether to create a task.
 
     Returns:
         The coroutine with the context.
@@ -160,14 +162,11 @@ class IsLocalDict(ast.NodeVisitor):
         self.keys = keys
 
     @override
-    def visit_Subscript(self, node: ast.Subscript) -> Any:
+    def visit_Subscript(self, node: ast.Subscript) -> None:
         """Visit a subscript node.
 
         Args:
             node: The node to visit.
-
-        Returns:
-            Any: The result of the visit.
         """
         if (
             isinstance(node.ctx, ast.Load)
@@ -180,14 +179,11 @@ class IsLocalDict(ast.NodeVisitor):
             self.keys.add(node.slice.value)
 
     @override
-    def visit_Call(self, node: ast.Call) -> Any:
+    def visit_Call(self, node: ast.Call) -> None:
         """Visit a call node.
 
         Args:
             node: The node to visit.
-
-        Returns:
-            Any: The result of the visit.
         """
         if (
             isinstance(node.func, ast.Attribute)
@@ -210,14 +206,11 @@ class IsFunctionArgDict(ast.NodeVisitor):
         self.keys: set[str] = set()
 
     @override
-    def visit_Lambda(self, node: ast.Lambda) -> Any:
+    def visit_Lambda(self, node: ast.Lambda) -> None:
         """Visit a lambda function.
 
         Args:
             node: The node to visit.
-
-        Returns:
-            Any: The result of the visit.
         """
         if not node.args.args:
             return
@@ -225,14 +218,11 @@ class IsFunctionArgDict(ast.NodeVisitor):
         IsLocalDict(input_arg_name, self.keys).visit(node.body)
 
     @override
-    def visit_FunctionDef(self, node: ast.FunctionDef) -> Any:
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
         """Visit a function definition.
 
         Args:
             node: The node to visit.
-
-        Returns:
-            Any: The result of the visit.
         """
         if not node.args.args:
             return
@@ -240,14 +230,11 @@ class IsFunctionArgDict(ast.NodeVisitor):
         IsLocalDict(input_arg_name, self.keys).visit(node)
 
     @override
-    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> Any:
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
         """Visit an async function definition.
 
         Args:
             node: The node to visit.
-
-        Returns:
-            Any: The result of the visit.
         """
         if not node.args.args:
             return
@@ -264,14 +251,11 @@ class NonLocals(ast.NodeVisitor):
         self.stores: set[str] = set()
 
     @override
-    def visit_Name(self, node: ast.Name) -> Any:
+    def visit_Name(self, node: ast.Name) -> None:
         """Visit a name node.
 
         Args:
             node: The node to visit.
-
-        Returns:
-            Any: The result of the visit.
         """
         if isinstance(node.ctx, ast.Load):
             self.loads.add(node.id)
@@ -279,14 +263,11 @@ class NonLocals(ast.NodeVisitor):
             self.stores.add(node.id)
 
     @override
-    def visit_Attribute(self, node: ast.Attribute) -> Any:
+    def visit_Attribute(self, node: ast.Attribute) -> None:
         """Visit an attribute node.
 
         Args:
             node: The node to visit.
-
-        Returns:
-            Any: The result of the visit.
         """
         if isinstance(node.ctx, ast.Load):
             parent = node.value
@@ -321,42 +302,33 @@ class FunctionNonLocals(ast.NodeVisitor):
         self.nonlocals: set[str] = set()
 
     @override
-    def visit_FunctionDef(self, node: ast.FunctionDef) -> Any:
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
         """Visit a function definition.
 
         Args:
             node: The node to visit.
-
-        Returns:
-            Any: The result of the visit.
         """
         visitor = NonLocals()
         visitor.visit(node)
         self.nonlocals.update(visitor.loads - visitor.stores)
 
     @override
-    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> Any:
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
         """Visit an async function definition.
 
         Args:
             node: The node to visit.
-
-        Returns:
-            Any: The result of the visit.
         """
         visitor = NonLocals()
         visitor.visit(node)
         self.nonlocals.update(visitor.loads - visitor.stores)
 
     @override
-    def visit_Lambda(self, node: ast.Lambda) -> Any:
+    def visit_Lambda(self, node: ast.Lambda) -> None:
         """Visit a lambda function.
 
         Args:
             node: The node to visit.
-
-        Returns:
-            Any: The result of the visit.
         """
         visitor = NonLocals()
         visitor.visit(node)
@@ -368,33 +340,29 @@ class GetLambdaSource(ast.NodeVisitor):
 
     def __init__(self) -> None:
         """Initialize the visitor."""
-        self.source: Optional[str] = None
+        self.source: str | None = None
         self.count = 0
 
     @override
-    def visit_Lambda(self, node: ast.Lambda) -> Any:
+    def visit_Lambda(self, node: ast.Lambda) -> None:
         """Visit a lambda function.
 
         Args:
             node: The node to visit.
-
-        Returns:
-            Any: The result of the visit.
         """
         self.count += 1
         if hasattr(ast, "unparse"):
             self.source = ast.unparse(node)
 
 
-def get_function_first_arg_dict_keys(func: Callable) -> Optional[list[str]]:
+def get_function_first_arg_dict_keys(func: Callable) -> list[str] | None:
     """Get the keys of the first argument of a function if it is a dict.
 
     Args:
         func: The function to check.
 
     Returns:
-        Optional[list[str]]: The keys of the first argument if it is a dict,
-            None otherwise.
+        The keys of the first argument if it is a dict, None otherwise.
     """
     try:
         code = inspect.getsource(func)
@@ -406,14 +374,14 @@ def get_function_first_arg_dict_keys(func: Callable) -> Optional[list[str]]:
         return None
 
 
-def get_lambda_source(func: Callable) -> Optional[str]:
+def get_lambda_source(func: Callable) -> str | None:
     """Get the source code of a lambda function.
 
     Args:
         func: a Callable that can be a lambda function.
 
     Returns:
-        str: the source code of the lambda function.
+        the source code of the lambda function.
     """
     try:
         name = func.__name__ if func.__name__ != "<lambda>" else None
@@ -437,7 +405,7 @@ def get_function_nonlocals(func: Callable) -> list[Any]:
         func: The function to check.
 
     Returns:
-        list[Any]: The nonlocal variables accessed by the function.
+        The nonlocal variables accessed by the function.
     """
     try:
         code = inspect.getsource(func)
@@ -480,7 +448,7 @@ def indent_lines_after_first(text: str, prefix: str) -> str:
         prefix: Used to determine the number of spaces to indent.
 
     Returns:
-        str: The indented text.
+        The indented text.
     """
     n_spaces = len(prefix)
     spaces = " " * n_spaces
@@ -496,6 +464,9 @@ class AddableDict(dict[str, Any]):
 
         Args:
             other: The other dictionary to add.
+
+        Returns:
+            A dictionary that is the result of adding the two dictionaries.
         """
         chunk = AddableDict(self)
         for key in other:
@@ -514,6 +485,9 @@ class AddableDict(dict[str, Any]):
 
         Args:
             other: The other dictionary to be added to.
+
+        Returns:
+            A dictionary that is the result of adding the two dictionaries.
         """
         chunk = AddableDict(other)
         for key in self:
@@ -542,53 +516,49 @@ class SupportsAdd(Protocol[_T_contra, _T_co]):
 Addable = TypeVar("Addable", bound=SupportsAdd[Any, Any])
 
 
-def add(addables: Iterable[Addable]) -> Optional[Addable]:
+def add(addables: Iterable[Addable]) -> Addable | None:
     """Add a sequence of addable objects together.
 
     Args:
         addables: The addable objects to add.
 
     Returns:
-        Optional[Addable]: The result of adding the addable objects.
+        The result of adding the addable objects.
     """
-    final: Optional[Addable] = None
+    final: Addable | None = None
     for chunk in addables:
         final = chunk if final is None else final + chunk
     return final
 
 
-async def aadd(addables: AsyncIterable[Addable]) -> Optional[Addable]:
+async def aadd(addables: AsyncIterable[Addable]) -> Addable | None:
     """Asynchronously add a sequence of addable objects together.
 
     Args:
         addables: The addable objects to add.
 
     Returns:
-        Optional[Addable]: The result of adding the addable objects.
+        The result of adding the addable objects.
     """
-    final: Optional[Addable] = None
+    final: Addable | None = None
     async for chunk in addables:
         final = chunk if final is None else final + chunk
     return final
 
 
 class ConfigurableField(NamedTuple):
-    """Field that can be configured by the user.
-
-    Parameters:
-        id: The unique identifier of the field.
-        name: The name of the field. Defaults to None.
-        description: The description of the field. Defaults to None.
-        annotation: The annotation of the field. Defaults to None.
-        is_shared: Whether the field is shared. Defaults to False.
-    """
+    """Field that can be configured by the user."""
 
     id: str
-
-    name: Optional[str] = None
-    description: Optional[str] = None
-    annotation: Optional[Any] = None
+    """The unique identifier of the field."""
+    name: str | None = None
+    """The name of the field. """
+    description: str | None = None
+    """The description of the field. """
+    annotation: Any | None = None
+    """The annotation of the field. """
     is_shared: bool = False
+    """Whether the field is shared."""
 
     @override
     def __hash__(self) -> int:
@@ -596,24 +566,20 @@ class ConfigurableField(NamedTuple):
 
 
 class ConfigurableFieldSingleOption(NamedTuple):
-    """Field that can be configured by the user with a default value.
-
-    Parameters:
-        id: The unique identifier of the field.
-        options: The options for the field.
-        default: The default value for the field.
-        name: The name of the field. Defaults to None.
-        description: The description of the field. Defaults to None.
-        is_shared: Whether the field is shared. Defaults to False.
-    """
+    """Field that can be configured by the user with a default value."""
 
     id: str
+    """The unique identifier of the field."""
     options: Mapping[str, Any]
+    """The options for the field."""
     default: str
-
-    name: Optional[str] = None
-    description: Optional[str] = None
+    """The default value for the field."""
+    name: str | None = None
+    """The name of the field. """
+    description: str | None = None
+    """The description of the field. """
     is_shared: bool = False
+    """Whether the field is shared."""
 
     @override
     def __hash__(self) -> int:
@@ -621,56 +587,48 @@ class ConfigurableFieldSingleOption(NamedTuple):
 
 
 class ConfigurableFieldMultiOption(NamedTuple):
-    """Field that can be configured by the user with multiple default values.
-
-    Parameters:
-        id: The unique identifier of the field.
-        options: The options for the field.
-        default: The default values for the field.
-        name: The name of the field. Defaults to None.
-        description: The description of the field. Defaults to None.
-        is_shared: Whether the field is shared. Defaults to False.
-    """
+    """Field that can be configured by the user with multiple default values."""
 
     id: str
+    """The unique identifier of the field."""
     options: Mapping[str, Any]
+    """The options for the field."""
     default: Sequence[str]
-
-    name: Optional[str] = None
-    description: Optional[str] = None
+    """The default values for the field."""
+    name: str | None = None
+    """The name of the field. """
+    description: str | None = None
+    """The description of the field. """
     is_shared: bool = False
+    """Whether the field is shared."""
 
     @override
     def __hash__(self) -> int:
         return hash((self.id, tuple(self.options.keys()), tuple(self.default)))
 
 
-AnyConfigurableField = Union[
-    ConfigurableField, ConfigurableFieldSingleOption, ConfigurableFieldMultiOption
-]
+AnyConfigurableField = (
+    ConfigurableField | ConfigurableFieldSingleOption | ConfigurableFieldMultiOption
+)
 
 
 class ConfigurableFieldSpec(NamedTuple):
-    """Field that can be configured by the user. It is a specification of a field.
-
-    Parameters:
-        id: The unique identifier of the field.
-        annotation: The annotation of the field.
-        name: The name of the field. Defaults to None.
-        description: The description of the field. Defaults to None.
-        default: The default value for the field. Defaults to None.
-        is_shared: Whether the field is shared. Defaults to False.
-        dependencies: The dependencies of the field. Defaults to None.
-    """
+    """Field that can be configured by the user. It is a specification of a field."""
 
     id: str
+    """The unique identifier of the field."""
     annotation: Any
-
-    name: Optional[str] = None
-    description: Optional[str] = None
+    """The annotation of the field."""
+    name: str | None = None
+    """The name of the field. """
+    description: str | None = None
+    """The description of the field. """
     default: Any = None
+    """The default value for the field. """
     is_shared: bool = False
-    dependencies: Optional[list[str]] = None
+    """Whether the field is shared."""
+    dependencies: list[str] | None = None
+    """The dependencies of the field. """
 
 
 def get_unique_config_specs(
@@ -682,7 +640,7 @@ def get_unique_config_specs(
         specs: The config specs.
 
     Returns:
-        list[ConfigurableFieldSpec]: The unique config specs.
+        The unique config specs.
 
     Raises:
         ValueError: If the runnable sequence contains conflicting config specs.
@@ -709,12 +667,12 @@ class _RootEventFilter:
     def __init__(
         self,
         *,
-        include_names: Optional[Sequence[str]] = None,
-        include_types: Optional[Sequence[str]] = None,
-        include_tags: Optional[Sequence[str]] = None,
-        exclude_names: Optional[Sequence[str]] = None,
-        exclude_types: Optional[Sequence[str]] = None,
-        exclude_tags: Optional[Sequence[str]] = None,
+        include_names: Sequence[str] | None = None,
+        include_types: Sequence[str] | None = None,
+        include_tags: Sequence[str] | None = None,
+        exclude_names: Sequence[str] | None = None,
+        exclude_types: Sequence[str] | None = None,
+        exclude_tags: Sequence[str] | None = None,
     ) -> None:
         """Utility to filter the root event in the astream_events implementation.
 
@@ -769,8 +727,7 @@ def is_async_generator(
         func: The function to check.
 
     Returns:
-        TypeGuard[Callable[..., AsyncIterator]: True if the function is
-            an async generator, False otherwise.
+        `True` if the function is an async generator, `False` otherwise.
     """
     return inspect.isasyncgenfunction(func) or (
         hasattr(func, "__call__")  # noqa: B004
@@ -787,8 +744,7 @@ def is_async_callable(
         func: The function to check.
 
     Returns:
-        TypeGuard[Callable[..., Awaitable]: True if the function is async,
-            False otherwise.
+        `True` if the function is async, `False` otherwise.
     """
     return asyncio.iscoroutinefunction(func) or (
         hasattr(func, "__call__")  # noqa: B004