New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Function Docstrings Obscured By Decorators That Return Protocols #5840
Comments
I don't think there's a "correct" answer here. I can point to cases where either choice is correct. The current behavior is at least internally consistent. If a callable object has a You can omit the docstring for the |
For reference, I've updated the description to note that Jedi appears to implement the behavior I'd like given the example I provided.
Perhaps I'm not on the latest version, but in my example, the docstring is not displayed even though I'd definitely be satisfied with this behavior though. For whatever reason I'm just not seeing it in my example. |
Great. Thanks for digging into the issue. I Look forward to having it fixed! |
when we rework how we do doc string this sprint, we should make sure all features that use doc string use same code to make sure we have consistent behavior regardless where it is shown to users. currently, we have slightly different code depends on each features. |
Current Behavior
When implementing decorators it's often convenient to use a
Protocol
andParamSpec
to annotate the type they return. However, using aProtocol
causes Pylance to hide the docstring of the decorated function even though, in most cases where aProtocol
is generalized by aParamSpec
, it would make sense to display the docstring of the function theParamSpec
came from.Consider the example below:
Here, Pylance just shows the type of
foo
. One could argue that this is sensible given that the decorator changed the type offoo
. That might imply that the foo's docstring wouldn't necessarily be meaningful anymore. However, if that's true, Pylance isn't consistent in its behavior since, if we change this decorator to useConcatenate
instead of aProtocol
, the docstring is preserved:Expected Behavior
When Pylance encounters decorators of the form:
Pylance should preserve the docstrings of the functions it decorates. Further, the details of
__call__
should not matter beyond the fact that it uses theParamSpec
. So for example, any of the following should still preserve docstrings:Given the same example above Jedi chooses to display the docstring of the decorated function:
Open Questions
It's a little unclear whether any
Protocol
instances that are generalized by a function'sParamSpec
should adopt the docstring of that function. Perhaps only aProtocol
that implements a__call__
that uses theParamSpec
should have this behavior.For example, it might not make sense to copy the docstring in a case like:
It's not particularly clear what the best thing to do in this situation is.
The text was updated successfully, but these errors were encountered: