MAINT, ENH: Upgrade and document numpy.who()

[pezcore]

Background

Numpy's who() function is a great, very useful function that prints out a table of useful information about the ndarrays in a dictionary, But is is not documented on the reference docs. New users should definitely be made aware of its existence and use cases in the online numpy reference documentation.

Also this function can be reimplemented to be much more useful by providing a lot more useful information about the ndarrays in tabular format. I propose the output printed by who() should be something more like this

data_pointer   type    flags   name       shape           nbytes
================================================================
0X5569FC22A280 <i8     CFOWA   a          (5,)            40
0X5569FC22A2A0 <i8     CFWA    b          (1,)            8
0X5569FC6112C0 <M8[h]  COWA    c          (4, 6)          192
0X5569FC31AF80 |b1     COWA    testvar    (10, 34)        340

This tells the user a lot more valuable information about the relationships and properties of the variables I have an implementation i wrote in mind that gets this table from a dict containing ndarrays

[PacificGilly]

I thought the reference docs are created automatically from the doc strings inside each function?

Also, there is an indirect reference to numpy.who() from the scipy.misc.who() function

https://docs.scipy.org/doc/scipy/reference/generated/scipy.misc.who.html

I like your proposed format, a lot more helpful!

[eric-wieser]

I'm not sure who really belongs in numpy in the first place - it sounds more suited to ipython, or some other interactive environment.

Edit: IPython provides %whos, which does basically the same thing (source here: https://github.com/ipython/ipython/blob/a2685d78f2403f84e6cb915ae11a4f6033ccc5f6/IPython/core/magics/namespace.py#L345-L470)

[pezcore]

@pacificgilly1992

I thought the reference docs are created automatically from the doc strings inside each function?

That is true, but for some reason who() doesn't make it into the docs on https://docs.scipy.org/doc/numpy/reference/.

Also, there is an indirect reference to numpy.who() from the scipy.misc.who() function

scipy.misc.who() is a deprecated reference to numpy.who() and scipy is not part of numpy, so the fact that it exists in scipy does not help the fact that who() is an important part of numpy that is currently undocumented in numpy.

[mattip]

While the reference docs are generated from the docstrings, the mapping is not automatic. Other functions from np.lib.utils.py.__all__ are missing, the only ones I found were in the help routines We should either deprecate them or add them to the one of the indices so they appears in the online docs.

So now we have at least two issues - incomplete documentation/possible future deprecations, and a suggested improvement to np.who.

[pezcore]

@eric-wieser

who() does belong in numpy. It is an important inspection tool for ndarrays that developers need to use to get a quick summary of shape and type information about ndarrays at runtime. Support for interactive programming and inspection is in scope for numpy's use-cases, and arguably and extremely valuable one. Third party providers of interactive environments should not be responsible for dealing directly with the internal data structure of ndarray.