langchain-core 0.3.79__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,15 +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.
+    """Check if asyncio.create_task accepts a `context` arg.
 
     Returns:
-        bool: True if ``asyncio.create_task`` accepts a context argument, False
-            otherwise.
+        True if `asyncio.create_task` accepts a context argument, `False` otherwise.
     """
-    return accepts_context(asyncio.create_task)
+    return sys.version_info >= (3, 11)
 
 
 def coro_with_context(
@@ -139,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.
@@ -343,7 +340,7 @@ 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
@@ -358,15 +355,14 @@ class GetLambdaSource(ast.NodeVisitor):
             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)
@@ -378,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
@@ -409,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)
@@ -452,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
@@ -520,31 +516,31 @@ 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
@@ -555,14 +551,14 @@ class ConfigurableField(NamedTuple):
 
     id: str
     """The unique identifier of the field."""
-    name: Optional[str] = None
-    """The name of the field. Defaults to None."""
-    description: Optional[str] = None
-    """The description of the field. Defaults to None."""
-    annotation: Optional[Any] = None
-    """The annotation of the field. Defaults to None."""
+    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. Defaults to False."""
+    """Whether the field is shared."""
 
     @override
     def __hash__(self) -> int:
@@ -578,12 +574,12 @@ class ConfigurableFieldSingleOption(NamedTuple):
     """The options for the field."""
     default: str
     """The default value for the field."""
-    name: Optional[str] = None
-    """The name of the field. Defaults to None."""
-    description: Optional[str] = None
-    """The description of the field. Defaults to None."""
+    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. Defaults to False."""
+    """Whether the field is shared."""
 
     @override
     def __hash__(self) -> int:
@@ -599,21 +595,21 @@ class ConfigurableFieldMultiOption(NamedTuple):
     """The options for the field."""
     default: Sequence[str]
     """The default values for the field."""
-    name: Optional[str] = None
-    """The name of the field. Defaults to None."""
-    description: Optional[str] = None
-    """The description of the field. Defaults to None."""
+    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. Defaults to 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):
@@ -623,16 +619,16 @@ class ConfigurableFieldSpec(NamedTuple):
     """The unique identifier of the field."""
     annotation: Any
     """The annotation of the field."""
-    name: Optional[str] = None
-    """The name of the field. Defaults to None."""
-    description: Optional[str] = None
-    """The description of the field. Defaults to None."""
+    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. Defaults to None."""
+    """The default value for the field. """
     is_shared: bool = False
-    """Whether the field is shared. Defaults to False."""
-    dependencies: Optional[list[str]] = None
-    """The dependencies of the field. Defaults to None."""
+    """Whether the field is shared."""
+    dependencies: list[str] | None = None
+    """The dependencies of the field. """
 
 
 def get_unique_config_specs(
@@ -644,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.
@@ -671,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.
 
@@ -731,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
@@ -749,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

langchain_core/stores.py

@@ -11,9 +11,7 @@ from collections.abc import AsyncIterator, Iterator, Sequence
 from typing import (
     Any,
     Generic,
-    Optional,
     TypeVar,
-    Union,
 )
 
 from typing_extensions import override
@@ -49,55 +47,53 @@ class BaseStore(ABC, Generic[K, V]):
     which will usually be more efficient by saving on round trips to the store.
 
     Examples:
-
-        .. code-block:: python
-
-            from langchain.storage import BaseStore
-
-
-            class MyInMemoryStore(BaseStore[str, int]):
-                def __init__(self) -> None:
-                    self.store: dict[str, int] = {}
-
-                def mget(self, keys: Sequence[str]) -> list[int | None]:
-                    return [self.store.get(key) for key in keys]
-
-                def mset(self, key_value_pairs: Sequence[tuple[str, int]]) -> None:
-                    for key, value in key_value_pairs:
-                        self.store[key] = value
-
-                def mdelete(self, keys: Sequence[str]) -> None:
-                    for key in keys:
-                        if key in self.store:
-                            del self.store[key]
-
-                def yield_keys(self, prefix: str | None = None) -> Iterator[str]:
-                    if prefix is None:
-                        yield from self.store.keys()
-                    else:
-                        for key in self.store.keys():
-                            if key.startswith(prefix):
-                                yield key
-
+        ```python
+        from langchain.storage import BaseStore
+
+
+        class MyInMemoryStore(BaseStore[str, int]):
+            def __init__(self) -> None:
+                self.store: dict[str, int] = {}
+
+            def mget(self, keys: Sequence[str]) -> list[int | None]:
+                return [self.store.get(key) for key in keys]
+
+            def mset(self, key_value_pairs: Sequence[tuple[str, int]]) -> None:
+                for key, value in key_value_pairs:
+                    self.store[key] = value
+
+            def mdelete(self, keys: Sequence[str]) -> None:
+                for key in keys:
+                    if key in self.store:
+                        del self.store[key]
+
+            def yield_keys(self, prefix: str | None = None) -> Iterator[str]:
+                if prefix is None:
+                    yield from self.store.keys()
+                else:
+                    for key in self.store.keys():
+                        if key.startswith(prefix):
+                            yield key
+        ```
     """
 
     @abstractmethod
-    def mget(self, keys: Sequence[K]) -> list[Optional[V]]:
+    def mget(self, keys: Sequence[K]) -> list[V | None]:
         """Get the values associated with the given keys.
 
         Args:
-            keys (Sequence[K]): A sequence of keys.
+            keys: A sequence of keys.
 
         Returns:
             A sequence of optional values associated with the keys.
             If a key is not found, the corresponding value will be None.
         """
 
-    async def amget(self, keys: Sequence[K]) -> list[Optional[V]]:
+    async def amget(self, keys: Sequence[K]) -> list[V | None]:
         """Async get the values associated with the given keys.
 
         Args:
-            keys (Sequence[K]): A sequence of keys.
+            keys: A sequence of keys.
 
         Returns:
             A sequence of optional values associated with the keys.
@@ -110,14 +106,14 @@ class BaseStore(ABC, Generic[K, V]):
         """Set the values for the given keys.
 
         Args:
-            key_value_pairs (Sequence[tuple[K, V]]): A sequence of key-value pairs.
+            key_value_pairs: A sequence of key-value pairs.
         """
 
     async def amset(self, key_value_pairs: Sequence[tuple[K, V]]) -> None:
         """Async set the values for the given keys.
 
         Args:
-            key_value_pairs (Sequence[tuple[K, V]]): A sequence of key-value pairs.
+            key_value_pairs: A sequence of key-value pairs.
         """
         return await run_in_executor(None, self.mset, key_value_pairs)
 
@@ -126,42 +122,40 @@ class BaseStore(ABC, Generic[K, V]):
         """Delete the given keys and their associated values.
 
         Args:
-            keys (Sequence[K]): A sequence of keys to delete.
+            keys: A sequence of keys to delete.
         """
 
     async def amdelete(self, keys: Sequence[K]) -> None:
         """Async delete the given keys and their associated values.
 
         Args:
-            keys (Sequence[K]): A sequence of keys to delete.
+            keys: A sequence of keys to delete.
         """
         return await run_in_executor(None, self.mdelete, keys)
 
     @abstractmethod
-    def yield_keys(
-        self, *, prefix: Optional[str] = None
-    ) -> Union[Iterator[K], Iterator[str]]:
+    def yield_keys(self, *, prefix: str | None = None) -> Iterator[K] | Iterator[str]:
         """Get an iterator over keys that match the given prefix.
 
         Args:
-            prefix (str): The prefix to match.
+            prefix: The prefix to match.
 
         Yields:
-            Iterator[K | str]: An iterator over keys that match the given prefix.
+            An iterator over keys that match the given prefix.
             This method is allowed to return an iterator over either K or str
             depending on what makes more sense for the given store.
         """
 
     async def ayield_keys(
-        self, *, prefix: Optional[str] = None
-    ) -> Union[AsyncIterator[K], AsyncIterator[str]]:
+        self, *, prefix: str | None = None
+    ) -> AsyncIterator[K] | AsyncIterator[str]:
         """Async get an iterator over keys that match the given prefix.
 
         Args:
-            prefix (str): The prefix to match.
+            prefix: The prefix to match.
 
         Yields:
-            Iterator[K | str]: An iterator over keys that match the given prefix.
+            The keys that match the given prefix.
             This method is allowed to return an iterator over either K or str
             depending on what makes more sense for the given store.
         """
@@ -184,28 +178,12 @@ class InMemoryBaseStore(BaseStore[str, V], Generic[V]):
         """Initialize an empty store."""
         self.store: dict[str, V] = {}
 
-    def mget(self, keys: Sequence[str]) -> list[Optional[V]]:
-        """Get the values associated with the given keys.
-
-        Args:
-            keys (Sequence[str]): A sequence of keys.
-
-        Returns:
-            A sequence of optional values associated with the keys.
-            If a key is not found, the corresponding value will be None.
-        """
+    @override
+    def mget(self, keys: Sequence[str]) -> list[V | None]:
         return [self.store.get(key) for key in keys]
 
-    async def amget(self, keys: Sequence[str]) -> list[Optional[V]]:
-        """Async get the values associated with the given keys.
-
-        Args:
-            keys (Sequence[str]): A sequence of keys.
-
-        Returns:
-            A sequence of optional values associated with the keys.
-            If a key is not found, the corresponding value will be None.
-        """
+    @override
+    async def amget(self, keys: Sequence[str]) -> list[V | None]:
         return self.mget(keys)
 
     @override
@@ -217,32 +195,24 @@ class InMemoryBaseStore(BaseStore[str, V], Generic[V]):
     async def amset(self, key_value_pairs: Sequence[tuple[str, V]]) -> None:
         return self.mset(key_value_pairs)
 
+    @override
     def mdelete(self, keys: Sequence[str]) -> None:
-        """Delete the given keys and their associated values.
-
-        Args:
-            keys (Sequence[str]): A sequence of keys to delete.
-        """
         for key in keys:
             if key in self.store:
                 del self.store[key]
 
+    @override
     async def amdelete(self, keys: Sequence[str]) -> None:
-        """Async delete the given keys and their associated values.
-
-        Args:
-            keys (Sequence[str]): A sequence of keys to delete.
-        """
         self.mdelete(keys)
 
-    def yield_keys(self, prefix: Optional[str] = None) -> Iterator[str]:
+    def yield_keys(self, prefix: str | None = None) -> Iterator[str]:
         """Get an iterator over keys that match the given prefix.
 
         Args:
-            prefix (str, optional): The prefix to match. Defaults to None.
+            prefix: The prefix to match.
 
         Yields:
-            Iterator[str]: An iterator over keys that match the given prefix.
+            The keys that match the given prefix.
         """
         if prefix is None:
             yield from self.store.keys()
@@ -251,14 +221,14 @@ class InMemoryBaseStore(BaseStore[str, V], Generic[V]):
                 if key.startswith(prefix):
                     yield key
 
-    async def ayield_keys(self, prefix: Optional[str] = None) -> AsyncIterator[str]:
+    async def ayield_keys(self, prefix: str | None = None) -> AsyncIterator[str]:
         """Async get an async iterator over keys that match the given prefix.
 
         Args:
-            prefix (str, optional): The prefix to match. Defaults to None.
+            prefix: The prefix to match.
 
         Yields:
-            AsyncIterator[str]: An async iterator over keys that match the given prefix.
+            The keys that match the given prefix.
         """
         if prefix is None:
             for key in self.store:
@@ -277,21 +247,19 @@ class InMemoryStore(InMemoryBaseStore[Any]):
             the key-value pairs.
 
     Examples:
-
-        .. code-block:: python
-
-            from langchain.storage import InMemoryStore
-
-            store = InMemoryStore()
-            store.mset([("key1", "value1"), ("key2", "value2")])
-            store.mget(["key1", "key2"])
-            # ['value1', 'value2']
-            store.mdelete(["key1"])
-            list(store.yield_keys())
-            # ['key2']
-            list(store.yield_keys(prefix="k"))
-            # ['key2']
-
+        ```python
+        from langchain.storage import InMemoryStore
+
+        store = InMemoryStore()
+        store.mset([("key1", "value1"), ("key2", "value2")])
+        store.mget(["key1", "key2"])
+        # ['value1', 'value2']
+        store.mdelete(["key1"])
+        list(store.yield_keys())
+        # ['key2']
+        list(store.yield_keys(prefix="k"))
+        # ['key2']
+        ```
     """
 
 
@@ -303,21 +271,19 @@ class InMemoryByteStore(InMemoryBaseStore[bytes]):
             the key-value pairs.
 
     Examples:
-
-        .. code-block:: python
-
-            from langchain.storage import InMemoryByteStore
-
-            store = InMemoryByteStore()
-            store.mset([("key1", b"value1"), ("key2", b"value2")])
-            store.mget(["key1", "key2"])
-            # [b'value1', b'value2']
-            store.mdelete(["key1"])
-            list(store.yield_keys())
-            # ['key2']
-            list(store.yield_keys(prefix="k"))
-            # ['key2']
-
+        ```python
+        from langchain.storage import InMemoryByteStore
+
+        store = InMemoryByteStore()
+        store.mset([("key1", b"value1"), ("key2", b"value2")])
+        store.mget(["key1", "key2"])
+        # [b'value1', b'value2']
+        store.mdelete(["key1"])
+        list(store.yield_keys())
+        # ['key2']
+        list(store.yield_keys(prefix="k"))
+        # ['key2']
+        ```
     """