Skip to content

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

Open
syzsunshine219 wants to merge 2 commits into
MemTensor:mainfrom
RerankerGuo:fix/issue-2392-docstring-phantoms
Open

syzsunshine219 wants to merge 2 commits into
MemTensor:mainfrom
RerankerGuo:fix/issue-2392-docstring-phantoms

Conversation

@syzsunshine219

@syzsunshine219 syzsunshine219 commented Nov 9, 2026 •

Copy link
Copy Markdown
Collaborator

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
…#2392)

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 MemTensor#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.
@Memtensor-AI Memtensor-AI added area:core MOS 编排层 / 框架底座 / 跨模块问题 status:in-progress Someone or AI is working on it | 人工或 AI 正在处理 labels Nov 9, 2026
@syzsunshine219
syzsunshine219 marked this pull request as ready for review November 9, 2026 15:48
@Memtensor-AI

Copy link
Copy Markdown
Collaborator

🤖 Open Code Review

Target: PR #2591
Task: 9075edeff51b064b
Base: main
Head: fix/issue-2392-docstring-phantoms
Head SHA: 46c9b9fd37d7806ed3386727d9bcd8082b297a21

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

Generated by cloud-assistant via Open Code Review.

@Memtensor-AI

Copy link
Copy Markdown
Collaborator

✅ Automated Test Results: PASSED

Required tests passed (2/2 executed, 0 skipped). Duration: 20s [advisory, non-gating] AI-generated tests on branch test/auto-gen-9075edeff51b064b-20261110002307: 99/101 passed, 2 failed — these do NOT affect the PR verdict; review the branch manually.

Branch: fix/issue-2392-docstring-phantoms

Tested source: 46c9b9fd37d7806ed3386727d9bcd8082b297a21
Tested base: 3a16e5fe3048a209f722806f4123fa2e533588fd
Tested commit: c130968f9ace914e64adcd89418b60b3ec53682c
These results apply only to this immutable source/base snapshot.

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.

4 participants