Skip to content

The agent engineering platform.

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

weiii6685517ef37fb30
diff --git a/libs/core/langchain_core/_api/__init__.py b/libs/core/langchain_core/_api/__init__.py
index 54de1d18b7..12296ca363 100644
--- a/libs/core/langchain_core/_api/__init__.py
+++ b/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__)
diff --git a/libs/core/langchain_core/indexing/api.py b/libs/core/langchain_core/indexing/api.py
index 65d0438163..da3c54fd63 100644
--- a/libs/core/langchain_core/indexing/api.py
+++ b/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:
diff --git a/libs/core/langchain_core/utils/json.py b/libs/core/langchain_core/utils/json.py
index 308c274045..14ff8a4239 100644
--- a/libs/core/langchain_core/utils/json.py
+++ b/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)
diff --git a/libs/core/langchain_core/utils/json_schema.py b/libs/core/langchain_core/utils/json_schema.py
index 72f56fc2ef..11475accb0 100644
--- a/libs/core/langchain_core/utils/json_schema.py
+++ b/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 = (
diff --git a/libs/core/langchain_core/utils/mustache.py b/libs/core/langchain_core/utils/mustache.py
index 8134355a50..cce84753a2 100644
--- a/libs/core/langchain_core/utils/mustache.py
+++ b/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
diff --git a/libs/core/langchain_core/utils/usage.py b/libs/core/langchain_core/utils/usage.py
index b60b173cdf..47e483a555 100644
--- a/libs/core/langchain_core/utils/usage.py
+++ b/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)
diff --git a/libs/core/langchain_core/vectorstores/__init__.py b/libs/core/langchain_core/vectorstores/__init__.py
index 560a0d1678..1da27459d6 100644
--- a/libs/core/langchain_core/vectorstores/__init__.py
+++ b/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__)