docs(core): add docstrings to internal helper functions (#34525)

Co-authored-by: weiii668 <your-email@example.com>
Co-authored-by: Mason Daugherty <github@mdrxy.com>
Co-authored-by: Mason Daugherty <mason@langchain.dev>

libs/core/langchain_core/_api/__init__.py

@@ -58,6 +58,20 @@ _dynamic_imports = {
 
 
 def __getattr__(attr_name: str) -> object:
+    """Dynamically import and return an attribute from a submodule.
+
+    This function enables lazy loading of API functions from submodules, reducing
+    initial import time and circular dependency issues.
+
+    Args:
+        attr_name: Name of the attribute to import.
+
+    Returns:
+        The imported attribute object.
+
+    Raises:
+        AttributeError: If the attribute is not a valid dynamic import.
+    """
     module_name = _dynamic_imports.get(attr_name)
     result = import_attr(attr_name, module_name, __spec__.parent)
     globals()[attr_name] = result
@@ -65,4 +79,9 @@ def __getattr__(attr_name: str) -> object:
 
 
 def __dir__() -> list[str]:
+    """Return a list of available attributes for this module.
+
+    Returns:
+        List of attribute names that can be imported from this module.
+    """
     return list(__all__)

libs/core/langchain_core/indexing/api.py

@@ -242,6 +242,17 @@ def _delete(
     vector_store: VectorStore | DocumentIndex,
     ids: list[str],
 ) -> None:
+    """Delete documents from a vector store or document index by their IDs.
+
+    Args:
+        vector_store: The vector store or document index to delete from.
+        ids: List of document IDs to delete.
+
+    Raises:
+        IndexingException: If the delete operation fails.
+        TypeError: If the `vector_store` is neither a `VectorStore` nor a
+            `DocumentIndex`.
+    """
     if isinstance(vector_store, VectorStore):
         delete_ok = vector_store.delete(ids)
         if delete_ok is not None and delete_ok is False:

libs/core/langchain_core/utils/json.py

@@ -13,6 +13,14 @@ if TYPE_CHECKING:
 
 
 def _replace_new_line(match: re.Match[str]) -> str:
+    """Replace newline characters in a regex match with escaped sequences.
+
+    Args:
+        match: Regex match object containing the string to process.
+
+    Returns:
+        String with newlines, carriage returns, tabs, and quotes properly escaped.
+    """
     value = match.group(2)
     value = re.sub(r"\n", r"\\n", value)
     value = re.sub(r"\r", r"\\r", value)
@@ -162,6 +170,20 @@ _json_strip_chars = " \n\r\t`"
 def _parse_json(
     json_str: str, *, parser: Callable[[str], Any] = parse_partial_json
 ) -> Any:
+    """Parse a JSON string, handling special characters and whitespace.
+
+    Strips whitespace, newlines, and backticks from the start and end of the string,
+    then processes special characters before parsing.
+
+    Args:
+        json_str: The JSON string to parse.
+        parser: Optional custom parser function.
+
+            Defaults to `parse_partial_json`.
+
+    Returns:
+        Parsed JSON object.
+    """
     # Strip whitespace,newlines,backtick from the start and end
     json_str = json_str.strip(_json_strip_chars)
 

libs/core/langchain_core/utils/json_schema.py

@@ -10,6 +10,22 @@ if TYPE_CHECKING:
 
 
 def _retrieve_ref(path: str, schema: dict) -> list | dict:
+    """Retrieve a referenced object from a JSON schema using a path.
+
+    Resolves JSON schema references (e.g., `'#/definitions/MyType'`) by traversing the
+    schema structure.
+
+    Args:
+        path: Reference path starting with `'#'` (e.g., `'#/definitions/MyType'`).
+        schema: The JSON schema dictionary to search in.
+
+    Returns:
+        A deep copy of the referenced object (dict or list).
+
+    Raises:
+        ValueError: If the path does not start with `'#'`.
+        KeyError: If the reference path is not found in the schema.
+    """
     components = path.split("/")
     if components[0] != "#":
         msg = (

libs/core/langchain_core/utils/mustache.py

@@ -352,7 +352,26 @@ def _get_key(
     def_ldel: str,
     def_rdel: str,
 ) -> Any:
-    """Return a key from the current scope."""
+    """Retrieve a value from the current scope using a dot-separated key path.
+
+    Traverses through nested dictionaries and lists using dot notation.
+
+    Supports special key `'.'` to return the current scope.
+
+    Args:
+        key: Dot-separated key path (e.g., `'user.name'` or `'.'` for current scope).
+        scopes: List of scope dictionaries to search through.
+        warn: Whether to log a warning when a key is not found.
+        keep: Whether to return the original template tag when key is not found.
+        def_ldel: Left delimiter for template (used when keep is `True`).
+        def_rdel: Right delimiter for template (used when keep is `True`).
+
+    Returns:
+        The value found at the key path.
+
+            If not found, returns the original template tag when keep is `True`,
+            otherwise returns an empty string.
+    """
     # If the key is a dot
     if key == ".":
         # Then just return the current scope

libs/core/langchain_core/utils/usage.py

@@ -12,6 +12,27 @@ def _dict_int_op(
     depth: int = 0,
     max_depth: int = 100,
 ) -> dict:
+    """Apply an integer operation to corresponding values in two dictionaries.
+
+    Recursively combines two dictionaries by applying the given operation to integer
+    values at matching keys.
+
+    Supports nested dictionaries.
+
+    Args:
+        left: First dictionary to combine.
+        right: Second dictionary to combine.
+        op: Binary operation function to apply to integer values.
+        default: Default value to use when a key is missing from a dictionary.
+        depth: Current recursion depth (used internally).
+        max_depth: Maximum recursion depth (to prevent infinite loops).
+
+    Returns:
+        A new dictionary with combined values.
+
+    Raises:
+        ValueError: If `max_depth` is exceeded or if value types are not supported.
+    """
     if depth >= max_depth:
         msg = f"{max_depth=} exceeded, unable to combine dicts."
         raise ValueError(msg)

libs/core/langchain_core/vectorstores/__init__.py

@@ -24,6 +24,20 @@ _dynamic_imports = {
 
 
 def __getattr__(attr_name: str) -> object:
+    """Dynamically import and return an attribute from a submodule.
+
+    This function enables lazy loading of vectorstore classes from submodules, reducing
+    initial import time and circular dependency issues.
+
+    Args:
+        attr_name: Name of the attribute to import.
+
+    Returns:
+        The imported attribute object.
+
+    Raises:
+        AttributeError: If the attribute is not found in `_dynamic_imports`.
+    """
     module_name = _dynamic_imports.get(attr_name)
     result = import_attr(attr_name, module_name, __spec__.parent)
     globals()[attr_name] = result
@@ -31,4 +45,9 @@ def __getattr__(attr_name: str) -> object:
 
 
 def __dir__() -> list[str]:
+    """Return a list of available attributes for this module.
+
+    Returns:
+        List of attribute names that can be imported from this module.
+    """
     return list(__all__)