Skip to content

docs: remove phantom parameters from two public docstrings (#2392) - #2640

Open
syzsunshine219 wants to merge 2 commits into
mainfrom
codex/maintainer-edit-pr-2591-20261119
Open

syzsunshine219 wants to merge 2 commits into
mainfrom
codex/maintainer-edit-pr-2591-20261119

Conversation

@syzsunshine219

Copy link
Copy Markdown
Collaborator

The source branch for the change proposed in #2591 now lives in MemTensor/MemOS, so repository writers can contribute fixes through the normal upstream branch permissions.

The code and commit authors are unchanged. This PR retains target branch main and exact source head 46c9b9fd37d7806ed3386727d9bcd8082b297a21 from #2591.

Previous discussion and review remain in #2591. Review and checks must be re-evaluated for this replacement PR; no previous approval or new test result is asserted by this migration.

Previous PR description and implementation details

Restores the change proposed in #2493 for review against main after its former base branch, dev-v2.0.36, was deleted. The source commits and authors are preserved.

Source head: 46c9b9fd37d7806ed3386727d9bcd8082b297a21

This PR is open for review. Review and CI against the current base are pending; validation claims in the original description below refer to the earlier snapshot. The original discussion and evidence remain in #2493.


Original change description

Summary

Two public docstrings documented parameters that the AST no longer exposes.

AST-verified mismatches

  1. RedisPersistentUserManager.__init__(host, port, password, db, decode_responses) — the docstring’s Args section started with user_id (str, optional): User ID. Defaults to root., but user_id is not a parameter (it is a leftover from an earlier API). Dropped.
  2. concat_original_source(graph_results, rerank_source) — the docstring documented merge_field (List[str]), 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 parameters documented, with their actual semantics.

Regression guard

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 (so it sees the real signature even when the function is wrapped by @require_python_package), extracts the parameter list from the AST, extracts the Args: block parameter names from the docstring, and asserts the two sets match. Any future divergence in either direction fails the test loudly.

Verification

PYTHONPATH=src pytest tests/test_docstring_signature_parity.py -v
============================== 2 passed in 5.97s ==============================

Ruff: ruff format --check and ruff check both clean on touched files (0 new findings vs main).

Out of scope

  • No new dependencies
  • No public API / OpenAPI contract changes
  • No DB schema, migration, or graph model changes
  • No Makefile / pyproject.toml / pre-commit / GitHub workflow changes
  • Docs-only

Closes #2392

RerankerGuo and others added 2 commits November 4, 2026 21:58
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.
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.
@syzsunshine219 syzsunshine219 added the area:core MOS 编排层 / 框架底座 / 跨模块问题 label Nov 19, 2026
@Memtensor-AI Memtensor-AI added the status:in-progress Someone or AI is working on it | 人工或 AI 正在处理 label Nov 19, 2026
@Memtensor-AI

Copy link
Copy Markdown
Collaborator

🤖 Open Code Review

Target: PR #2640
Task: abefc4ba5bb34ad6
Base: main
Head: codex/maintainer-edit-pr-2591-20261119
Head SHA: 46c9b9fd37d7806ed3386727d9bcd8082b297a21

✅ OpenCodeReview: Review complete: 0 finding(s) across 2 selected item(s).

Generated by cloud-assistant via Open Code Review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:core MOS 编排层 / 框架底座 / 跨模块问题 status:in-progress Someone or AI is working on it | 人工或 AI 正在处理

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants