Fix: In packages/griffelib/src/griffe/_internal/merger.py,... - #483
Closed
M001N wants to merge 1 commit into
Closed
Conversation
…ocstrings#447) _merge_stubs_docstring() only filled in a docstring when the runtime object had none at all, so an auto-generated placeholder docstring from dynamic/runtime inspection (e.g. a SWIG/pybind11 C-level signature string) was never replaced by the real, human-authored docstring from a .pyi stub. Now it also overwrites when the object's analysis is 'dynamic', while still leaving genuine statically-analyzed docstrings untouched. Also propagate an overload's docstring onto the base function when merging overload-only stub methods, for the same dynamic/missing docstring cases.
Member
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Problem
mkdocstrings/griffe issue reference: #447
Root Cause
In packages/griffelib/src/griffe/_internal/merger.py, _merge_stubs_docstring(obj, stubs) used
if not obj.docstring and stubs.docstring-- it treated 'has any docstring' as sufficient reason to keep the runtime object's docstring, without checking whether that docstring was genuinely authored (obj.analysis == 'static'/None) versus an auto-generated placeholder from runtime inspection (obj.analysis == 'dynamic'), even though griffe's Object model already tracks this via theanalysis: Literal['static','dynamic'] | Noneattribute (set by the inspector for dynamically-analyzed members). Separately, _merge_overload_annotations(function, overloads) merged parameter/return type annotations from @overload stub signatures onto the base function but never propagated any overload's docstring onto it.Testing
PASS - all 9 tests in test_merger.py pass (3 new + 6 existing); full suite (minus unrelated test_api.py which fails to import due to missing optional 'mkdocstrings' dependency in this environment, and test_git.py which fails due to a missing pytest-git plugin fixture, both pre-existing/unrelated to this change) shows 1742 passed, 22 skipped, 0 failures caused by this change.
Related Issue
#447