From e9500c359ead2b974cdce71c95d6fcbeef0842ee Mon Sep 17 00:00:00 2001 From: RerankerGuo Date: Tue, 13 Oct 2026 21:55:31 +0800 Subject: [PATCH 1/2] docs: remove phantom parameters from two public docstrings (#2392) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two public docstrings documented parameters that the AST no longer exposes: 1. `RedisPersistentUserManager.__init__` listed `user_id (str, optional):` as the first Args entry, but the signature is `(host, port, password, db, decode_responses)` — `user_id` is a leftover from an earlier API. Removed the phantom line. 2. `concat_original_source` listed `merge_field (List[str]): List of fields to merge`, which is actually a local variable inside the function, and omitted the real `rerank_source` parameter (the comma-separated metadata field names that the function actually accepts). Rewrote the docstring with both `graph_results` and `rerank_source` documented, with their actual semantics. To prevent the same kind of drift from sneaking back in, this commit also adds tests/test_docstring_signature_parity.py: it parses each function's source file, extracts the parameter list from the AST, extracts the `Args:` block parameter names from the docstring, and asserts the two sets match. The check works around the `@require_python_package` decorator that rewrites `__code__`, so it sees the real `__init__` signature rather than the wrapper's. Docs-only functional change; the parity test is the regression guard. Fixes #2392. --- .../mem_user/redis_persistent_user_manager.py | 1 - src/memos/reranker/concat.py | 15 +- tests/test_docstring_signature_parity.py | 134 ++++++++++++++++++ 3 files changed, 145 insertions(+), 5 deletions(-) create mode 100644 tests/test_docstring_signature_parity.py diff --git a/src/memos/mem_user/redis_persistent_user_manager.py b/src/memos/mem_user/redis_persistent_user_manager.py index 48c89c663..ef6502ced 100644 --- a/src/memos/mem_user/redis_persistent_user_manager.py +++ b/src/memos/mem_user/redis_persistent_user_manager.py @@ -32,7 +32,6 @@ def __init__( """Initialize the Redis persistent user manager. Args: - user_id (str, optional): User ID. Defaults to "root". host (str): Redis server host. Defaults to "localhost". port (int): Redis server port. Defaults to 6379. password (str): Redis password. Defaults to "". diff --git a/src/memos/reranker/concat.py b/src/memos/reranker/concat.py index b39496a1c..ed790c3c9 100644 --- a/src/memos/reranker/concat.py +++ b/src/memos/reranker/concat.py @@ -72,12 +72,19 @@ def concat_original_source( rerank_source: str | None = None, ) -> list[str]: """ - Merge memory items with original dialogue. + Merge memory items with their original source fields. + Args: - graph_results (list[TextualMemoryItem]): List of memory items with embeddings. - merge_field (List[str]): List of fields to merge. + graph_results (list[TextualMemoryItem] | list[dict]): Memory items to + merge; may be either pydantic ``TextualMemoryItem`` instances or + pre-serialised dicts (e.g. from a cache or MCP payload). + rerank_source (str | None): Comma-separated metadata field names to + treat as the source. When ``None`` (the default) the ``sources`` + field on each item is used. + Returns: - list[str]: List of memory and concat orginal memory. + list[str]: One merged string per input item, with the referenced + source content appended to the memory text. """ merge_field = [] merge_field = ["sources"] if rerank_source is None else rerank_source.split(",") diff --git a/tests/test_docstring_signature_parity.py b/tests/test_docstring_signature_parity.py new file mode 100644 index 000000000..605ec62ea --- /dev/null +++ b/tests/test_docstring_signature_parity.py @@ -0,0 +1,134 @@ +"""Regression tests for issue #2392. + +Two public docstrings documented parameters that the AST no longer exposes +(``user_id`` on ``RedisPersistentUserManager.__init__``, ``merge_field`` on +``concat_original_source``). These tests fail loudly if anyone re-introduces +the mismatch by either: + +- editing the body to add a parameter the docstring doesn't mention, or +- editing the docstring to claim a parameter the body no longer accepts. + +The check parses the source file directly (so it sees the real signature +even when the function is wrapped by a decorator like +``@require_python_package``). +""" + +from __future__ import annotations + +import ast +import re + +from pathlib import Path + +from memos.mem_user.redis_persistent_user_manager import RedisPersistentUserManager +from memos.reranker.concat import concat_original_source + + +REPO_ROOT = Path(__file__).resolve().parents[1] + + +def _function_def_in_class(func, file_path: Path) -> ast.FunctionDef | None: + """Parse the source file and return the ``__init__``/``def`` whose name + matches ``func.__name__``. For class methods the search is scoped to the + class whose name matches ``func.__qualname__.split('.')[-2]``; for module + functions it falls back to module-scope search. + """ + tree = ast.parse(file_path.read_text(encoding="utf-8")) + qualname_parts = func.__qualname__.split(".") + target_class = qualname_parts[-2] if len(qualname_parts) >= 2 else None + target_name = func.__name__ + + if target_class is not None: + for node in ast.walk(tree): + if isinstance(node, ast.ClassDef) and node.name == target_class: + for item in node.body: + if isinstance(item, ast.FunctionDef) and item.name == target_name: + return item + return None + + for node in ast.walk(tree): + if isinstance(node, ast.FunctionDef) and node.name == target_name: + return node + return None + + +def _function_def_for_module_func(func, file_path: Path) -> ast.FunctionDef | None: + """Locate a module-level function by name.""" + tree = ast.parse(file_path.read_text(encoding="utf-8")) + for node in tree.body: + if isinstance(node, ast.FunctionDef) and node.name == func.__name__: + return node + return None + + +def _signature_param_names(func) -> set[str]: + # Walk back from func.__module__ to find the actual source file. This + # works around decorators like ``@require_python_package`` that rewrite + # ``__code__`` (so ``func.__code__.co_filename`` no longer points to the + # original module). + import importlib + + module = importlib.import_module(func.__module__) + file_path = Path(getattr(module, "__file__", str(REPO_ROOT))) + if not file_path.is_absolute(): + file_path = REPO_ROOT / file_path + qualname_parts = func.__qualname__.split(".") + if len(qualname_parts) >= 2: + node = _function_def_in_class(func, file_path) + else: + node = _function_def_for_module_func(func, file_path) + if node is None: + return set() + args = node.args + params: set[str] = set() + params.update(p.arg for p in args.posonlyargs) + params.update(p.arg for p in args.args) + params.update(p.arg for p in args.kwonlyargs) + # ``self``/``cls`` never appear in the Args docstring block; drop them. + params.discard("self") + params.discard("cls") + return params + + +def _docstring_param_names(func) -> set[str]: + doc = func.__doc__ or "" + args_match = re.search(r"Args:\s*\n(.*?)(?:\n\s*\n|\n\s*Returns:|\n\s*Raises:|\Z)", doc, re.DOTALL) + if not args_match: + return set() + block = args_match.group(1) + names: set[str] = set() + for line in block.splitlines(): + m = re.match(r"\s*(\w+)\s*\(", line) + if m: + names.add(m.group(1)) + return names + + +def _diff_report(func) -> tuple[set[str], set[str]]: + sig = _signature_param_names(func) + doc = _docstring_param_names(func) + return sig - doc, doc - sig + + +class TestDocstringSignatureParity: + def test_redis_persistent_user_manager_init(self): + only_in_sig, only_in_doc = _diff_report(RedisPersistentUserManager.__init__) + assert not only_in_sig, ( + f"RedisPersistentUserManager.__init__ has parameters missing from " + f"the docstring's Args block: {sorted(only_in_sig)}" + ) + assert not only_in_doc, ( + f"RedisPersistentUserManager.__init__ docstring lists parameters " + f"that are not in the signature: {sorted(only_in_doc)}" + ) + + def test_concat_original_source(self): + only_in_sig, only_in_doc = _diff_report(concat_original_source) + assert not only_in_sig, ( + f"concat_original_source has parameters missing from the docstring: " + f"{sorted(only_in_sig)}" + ) + assert not only_in_doc, ( + f"concat_original_source docstring lists parameters that are not in " + f"the signature: {sorted(only_in_doc)}" + ) From 46c9b9fd37d7806ed3386727d9bcd8082b297a21 Mon Sep 17 00:00:00 2001 From: RerankerGuo <121015044+RerankerGuo@users.noreply.github.com> Date: Tue, 27 Oct 2026 23:19:52 +0800 Subject: [PATCH 2/2] test: fail loudly on missing AST def and drop dead fallback branch ruff format rejected the over-long re.search line in test_docstring_signature_parity.py, failing every build-matrix job at the Ruff checks step; the file is now formatted. An AST-lookup miss previously degraded to an empty signature set, which made both parity diffs empty by construction so the assertions could never fail. Raise AssertionError instead so the 'fail loudly' contract in the module docstring holds. The module-scope fallback branch in _function_def_in_class was unreachable (the helper is only called for dotted qualnames) and is removed. --- tests/test_docstring_signature_parity.py | 26 +++++++++++++----------- 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/tests/test_docstring_signature_parity.py b/tests/test_docstring_signature_parity.py index 605ec62ea..aa5966704 100644 --- a/tests/test_docstring_signature_parity.py +++ b/tests/test_docstring_signature_parity.py @@ -27,11 +27,10 @@ REPO_ROOT = Path(__file__).resolve().parents[1] -def _function_def_in_class(func, file_path: Path) -> ast.FunctionDef | None: +def _function_def_in_class(func, file_path: Path) -> ast.FunctionDef: """Parse the source file and return the ``__init__``/``def`` whose name - matches ``func.__name__``. For class methods the search is scoped to the - class whose name matches ``func.__qualname__.split('.')[-2]``; for module - functions it falls back to module-scope search. + matches ``func.__name__``, scoped to the class whose name matches + ``func.__qualname__.split('.')[-2]``. """ tree = ast.parse(file_path.read_text(encoding="utf-8")) qualname_parts = func.__qualname__.split(".") @@ -44,15 +43,10 @@ class whose name matches ``func.__qualname__.split('.')[-2]``; for module for item in node.body: if isinstance(item, ast.FunctionDef) and item.name == target_name: return item - return None - - for node in ast.walk(tree): - if isinstance(node, ast.FunctionDef) and node.name == target_name: - return node return None -def _function_def_for_module_func(func, file_path: Path) -> ast.FunctionDef | None: +def _function_def_for_module_func(func, file_path: Path) -> ast.FunctionDef: """Locate a module-level function by name.""" tree = ast.parse(file_path.read_text(encoding="utf-8")) for node in tree.body: @@ -78,7 +72,13 @@ def _signature_param_names(func) -> set[str]: else: node = _function_def_for_module_func(func, file_path) if node is None: - return set() + # A silent empty-set return here would make both diff sets empty by + # construction, so the parity assertions below could never fail — + # the opposite of the "fail loudly" contract in the module docstring. + raise AssertionError( + f"Could not locate an AST definition for {func.__qualname__} in {file_path}; " + "docstring/signature parity was not actually verified" + ) args = node.args params: set[str] = set() params.update(p.arg for p in args.posonlyargs) @@ -92,7 +92,9 @@ def _signature_param_names(func) -> set[str]: def _docstring_param_names(func) -> set[str]: doc = func.__doc__ or "" - args_match = re.search(r"Args:\s*\n(.*?)(?:\n\s*\n|\n\s*Returns:|\n\s*Raises:|\Z)", doc, re.DOTALL) + args_match = re.search( + r"Args:\s*\n(.*?)(?:\n\s*\n|\n\s*Returns:|\n\s*Raises:|\Z)", doc, re.DOTALL + ) if not args_match: return set() block = args_match.group(1)