From 5517ef37fb30b5cf7677d4571d4fe90b200477ff Mon Sep 17 00:00:00 2001 From: weiii668 <1120232373@bit.edu.cn> Date: Wed, 31 Dec 2025 11:58:00 +0800 Subject: [PATCH] docs(core): add docstrings to internal helper functions (#34525) Co-authored-by: weiii668 Co-authored-by: Mason Daugherty Co-authored-by: Mason Daugherty --- libs/core/langchain_core/_api/__init__.py | 19 ++++++++++++++++ libs/core/langchain_core/indexing/api.py | 11 ++++++++++ libs/core/langchain_core/utils/json.py | 22 +++++++++++++++++++ libs/core/langchain_core/utils/json_schema.py | 16 ++++++++++++++ libs/core/langchain_core/utils/mustache.py | 21 +++++++++++++++++- libs/core/langchain_core/utils/usage.py | 21 ++++++++++++++++++ .../langchain_core/vectorstores/__init__.py | 19 ++++++++++++++++ 7 files changed, 128 insertions(+), 1 deletion(-) diff --git a/libs/core/langchain_core/_api/__init__.py b/libs/core/langchain_core/_api/__init__.py index 54de1d18b77..12296ca3630 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 65d04381630..da3c54fd63f 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 308c2740457..14ff8a4239d 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 72f56fc2efa..11475accb0b 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 8134355a500..cce84753a2f 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 b60b173cdf4..47e483a5555 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 560a0d16788..1da27459d6b 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__)