Repository navigation
docs: remove phantom parameters from two public docstrings (#2392) - #2591
syzsunshine219 wants to merge 2 commits into
Conversation
…#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.
🤖 Open Code ReviewTarget: PR #2591 ✅ OpenCodeReview: Review complete: 0 finding(s) across 2 selected item(s). Generated by cloud-assistant via Open Code Review. |
✅ Automated Test Results: PASSEDRequired 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: Tested source: |
Restores the change proposed in #2493 for review against
mainafter its former base branch,dev-v2.0.36, was deleted. The source commits and authors are preserved.Source head:
46c9b9fd37d7806ed3386727d9bcd8082b297a21This 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
RedisPersistentUserManager.__init__(host, port, password, db, decode_responses)— the docstring’sArgssection started withuser_id (str, optional): User ID. Defaults to root., butuser_idis not a parameter (it is a leftover from an earlier API). Dropped.concat_original_source(graph_results, rerank_source)— the docstring documentedmerge_field (List[str]), which is actually a local variable inside the function, and omitted the realrerank_sourceparameter (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 theArgs:block parameter names from the docstring, and asserts the two sets match. Any future divergence in either direction fails the test loudly.Verification
Ruff:
ruff format --checkandruff checkboth clean on touched files (0 new findings vsmain).Out of scope
Closes #2392