The help of numpy.random.choice is not complete

[Vincent0706]

I found the help information of numpy.random.choice is not complete. It only have the function declaration.

[erictraut]

I presume that you're looking for a docstring or other documentation?

The type information and docstrings come from numpy itself. If you right-click on choice and select "Go To Declaration", you'll see which file this information comes from. In the latest release of numpy, choice is declared in a type stub file numpy/random/mtrand.pyi. Unfortunately, it doesn't include any docstrings, so pylance has nothing to display. You may want to file a bug (or better yet, a PR) in the numpy github repo.

[Vincent0706]

Thank you, I have reported to numpy.

[bashtage]

Putting type information only in pyi files is standard. docstrings are not incorporated in these files generally. Other IDEs, e.g., PyCharm, can seamlessly incorporate pyi information with standard docstrings. I don't expect NumPy, or many other projects that have compiled code and use pti for typing, will move their docstrings away from the code into type stub files.

Related to numpy/numpy#20809

[Vincent0706]

numpy/numpy#20809 (comment)
According to this, it seems to be pylance's or python-extention's problem.

[BvB93]

numpy/numpy#20809 (comment)
According to this, it seems to be pylance's or python-extention's problem.

Following up on this comment: the issue seems to be limited to functions that are purely C- or Cython-based, lacking any wrapper of some sort written in pure-python.

[bashtage]

@BvB93 Do the examples of functions with python wrappers have docstrings and typing information together. or is the docstring in the .py file and the typing in a .pyi?

[Vincent0706]

I don't know what is python wrappers. But in numpy 1.20.3 version, I right-click on choice and select "Go To Declaration". I can't found any docstrings or typing information.

[BvB93]

@BvB93 Do the examples of functions with python wrappers have docstrings and typing information together. or is the docstring in the .py file and the typing in a .pyi?

The docstrings and annotations are always split between .py/.pyx and .pyi files.
Just to give a few more examples from my previous point:

Shows docstrings

• np.atleast_2d: Pure python function
• np.bincount: C-based function with some form of python wrapper

Does not show docstrings

• np.random.choice: Cython function
• np.array: C-based function without a python wrapper

[bashtage]

I see. bincount's python wrapper is

https://github.com/numpy/numpy/blob/8dbd507fb6c854b362c26a0dd056cd04c9c10f25/numpy/core/multiarray.py#L884

while it's type information is here

https://github.com/numpy/numpy/blob/e2d35064df262efa6eb7dfe5bfc43160c73cf685/numpy/core/multiarray.pyi#L417

[erictraut]

Pylance will find and display docstrings for functions and classed declared in ".pyi" files if it can find the same symbol in a corresponding ".py" file. In the case of np.random.choice, there is no corresponding ".py" file though. When functions are implemented in a language other than Python, there is no static way to access the docstring if it's not in the ".pyi" file. As such, it is recommended that the ".pyi" include the docstring. Refer to this guidance for more details.

[bschnurr]

This issue has been fixed in version 2022.1.3, which we've just released. You can find the changelog here: CHANGELOG.md