Yep, I’ll add a section with that. I’ve only seen variations of docstrings, in comments or so.
@erictraut thanks for the very detailed feedback, super useful, great to see you here.
I wish PyCharm and Jedi would also chime in, it would be ideal to build this having in mind all the interested parties, as much as possible.
I think this makes sense, and is the most correct/exact… nevertheless…
You’re right that it would technically make more sense to have this document just that specific symbol.
On the other hand, I think a possibly common use case could be wanting to share the same doc for the same parameter in multiple functions. And I can only imagine doing that with an alias.
Or for example, if there was a
TypedDict for the params, e.g.:
class Params(TypedDict): first_name: Annotated[str, Doc("User's first name")] last_name: Annotated[str, Doc("User's last name")] age: Annotated[int, Doc("User's age")] def create(**kwargs: Params): ... def update(id: int, **kwargs: Params): ...
I would like to imagine tools/editors could show in the tooltip for each keyword argument parameter the respective doc string.
And if users are expected to interact with just
update(), I don’t think they would easily end up hovering over
Params to get their tooltips.
So, on one side, I agree that what makes more logical sense is that it could only document that specific symbol. On the other hand, allowing them to transfer in some way would solve some use cases.
…still, I was thinking that adding that logic of transferring the doc from an alias to a parameter could be too involved for implementers (you) so I marked it as non-required. But you’re actually the one to tell me… what would be doable? Do you see a way this use case could be solved?
If not, or if the logic just doesn’t match and there’s no way to solve it, I would be happy to just update it to say it just documents whatever is the specific symbol it is attached to.
In any case, after clarifying that better in the “spec” part, I will remove the “Additional Scenarios” part. It was intended as clarifications and I can see it has only added confusion.
Yep, thanks. I just updated the implementation in the
typing_extensions PR and will update the PEP once a couple of other related PRs are done. It’s now gonna be just a
Doc class, with a single positional-only argument.
I would definitely prefer Markdown, but I thought that would be even more debated than this already is.
From what I’ve seen, seasoned experts (most here) are much more familiar and happy with reST, and most “newcomers” (including me) have not been able to get the hang of reST and have always preferred Markdown. So I would personally definitely prefer that. But I was delaying that to another PEP with its potentially long discussion…
Now, if no one is particularly opposed to default to Markdown (apart from being opposed to this PEP in general), I would make it the default.
Another option is to have another
Doc() parameter with the language name, the same way we annotate here in Discuss a fenced code block. But then that’s even more stuff in this PEP that could be controversial, so, not sure.
Another option is to adopt another convention for this, like fenced code blocks, of saying that in a multi-line string, if the first characters are not a new line, those define the language. E.g.
"""markdown Here's the **content** """
…but that lands in microsyntax as well, so, not sure.
If no one opposes directly to Markdown (specifically) I’ll make it the default in the PEP.
Indeed, this is one of the cool things I have wanted/expected, I do several things with
ParamSpec (e.g. Asyncer’s
asyncify) and it would be very helpful to be able to transfer the tooltips/help from one function to the wrapped/decorated one.
I’ll add a note about it.
I’ll add it.
Indeed, Click is great. I built Typer on top of it, to add pretty much this that I’m proposing, on top of Click.
Thanks for chiming in! (and for the early feedback months ago). …when mentioning VS Code and opinions I was actually referring to Pylance/Pyright, and Eric already replied above.
This is good to know.
I can imagine if people do that, they are also using
from __future__ import annotations (or in the future when PEP 649 is already in).
This problem would also apply for libraries re-using this at runtime (e.g. FastAPI, Pydantic). Although, in those cases, the interest in using those libraries would be enough to update the code to not run into that. But maybe if they are using Sphinx they would also have interest in making that work…
Do you see a way this could be solved? Or anything that could be said in the spec about that that would make things easier for Sphinx?
I should probably add that, around backwards compatibility with previous versions of Python (that would only work at runtime for newer versions), and return types.
I think I should add a specific note about it, that a docstring should have higher priority than parameter docs, e.g. if choosing only one OR the other, a docstring should win.
That wouldn’t change how people would use it, which I can’t foresee, but at least show the intention of the PEP.