Display metadata from typing.Annotated for function parameters

[SSmJaE]

Currently, we can use a google or other style function docstring to document parameters that we can see when using the function,
but it has these disadvantages

1. The documentation of the parameters is not together with the parameters, sometimes it is difficult to quickly find the documentation in the docstring of the function
2. While you can use some extensions to automatically generate docstrings, you need to sync it every time you change the parameter definition

Since after PEP 593, python now supports typing.Annotated to provide metadata, why not display the metadata by the way, but only the type of the parameter?

suppose we have this function definition

def test_func(arg: Annotated[int, "some document for this arg", ValueRange(100, 200)]):
    pass

what i want is
from

to

I know that when I hold down the Ctrl key I can find the full definition, but if we can see the metadata (including some "documentation") just hover over the parameter, It will be better in actual use.

Related discussion

• https://stackoverflow.com/questions/8820276/docstring-for-variable
• https://stackoverflow.com/questions/68454202/how-to-use-maxlen-of-typing-annotation-of-python-3-9

[erictraut]

Annotated isn't typically used for documentation. It's intended for user-specific (or tool-specific) metadata, and the interpretation is specific to the use case. General-purpose type checkers and language servers should therefore not interpret its meaning. Other than validating that it's syntactically correct, pylance/pyright don't pay any attention to Annotated type arguments beyond the first one, which correspond to the annotated type. As you pointed out, you can hold down the Ctrl key to see the full definition .

[SSmJaE]

ok, thanks for your reply

[SSmJaE]

By the way, what is the best practice for adding docstrings to parameters in vscode?

[erictraut]

There isn't a single standard for function/method docstrings in Python, but there are several popular conventions. Pylance supports the following:

    1. Epytext:
         @param param1: description
    2. reST:
         :param param1: description
    3. Google (variant 1):
         Args:
             param1: description
    4. Google (variant 2):
         Args:
             param1 (type): description

If you use one of these forms, you'll see the documentation text for the current parameter as you type a call signature.