Make hvPlot tooltips useful in modern editors and IDEs

[MarcSkovMadsen]

Request

Make sure tooltips shown in modern Editors and IDEs like VS Code and PyCharm are available and useful.

Motivation

I'm trying to help a user of hvPlot here https://discourse.holoviz.org/t/linked-plot-is-exceedingly-slow/3966. I am a user of VS Code. Its just a very slow process helping the user because I need to search and read things on the hvPlot website instead of being able to stay in my editor.

The issue is that the tooltips shown by VS Code are either empty or not useful. My guess is that its because no one has ever considered to make sure the docstrings of hvPlot works in modern editors and IDEs.

The consequence is that hvPlot is much, much harder to learn and work with than it has to be for editor and IDE users.

For me personally the consequence is that it is hard to either introduce a colleague to hvPlot using their favorite tool or hand over existing code. If you just get a code base, you open it in your editor and IDE. And if you don't know it, its key that you can get information and help immediately.

As hvPlot is recommended as the entry point for HoloViews and the rest of the Holoviz ecosystem it should be the most polished and easy to use framework. But in many ways its actually less polished than the rest of the ecosystem currently.

Examples

hvplot

hvplot has no tooltip

hvplot.pandas

hvplot.pandas has no tooltip

.hvplot

.hvplot has no tooltip

.hvplot.scatter

.hvplot.scatter has no tooltip.

[maximlt]

I agree that better docstrings and documentation is required.

I am a user of VS Code. Its just a very slow process helping the user because I need to search and read things on the hvPlot website instead of being able to stay in my editor.

Of course the more you can stay working in your editor the better. However don't forget that because of the flat API of the .plot() API of Pandas, which applies to the .hvplot() API of hvPlot, the provided methods accept a large number of arguments, and this by design. See for instance the tooltip of Pandas df.plot.scatter(), which doesn't list all the kwargs it accepts.

In most cases then you will have to go to Pandas website and look for what kwargs you can pass. The same applies to hvPlot, even more so as it provides more powerful arguments for which a simple explanation in a tooltip may not be enough to be understood properly (e.g. rasterize).

Also note that Pandas docstring doesn't link to the reference page and the Examples section doesn't display plots. Even projects like Pandas with about 100M downloads/month have difficulties to make this right.

hvPlot and I think the HoloViz tools in general have been optimized to work well in Jupyter Notebooks. Jupyter Notebooks are also modern editors, and this is where I expect most users currently are. hvPlot docstrings work better there, even more so as they are dynamically adapted the activated backend (e.g. bokeh or matplotlib or plotly) to provide an appropriate list of styling options.

There are of course users like you who use hvPlot to write code in a Python script in VSCode or PyCharm, and I expect more and more people will use the notebook support offered by VSCode. The experience of these users should be taken more into account.

[MarcSkovMadsen]

Thanks @maximlt . I agree with the above. I will try to make some example PRs to show what can be done, how and the value it creates.

[maximlt]

Ok cool! Make sure it doesn't affect the experience of the Jupyter notebooks users though 🙃

[MarcSkovMadsen]

Regarding Matplotlib documentation. They have the advantage of huge user base and community. So they don't need to get their documentation nearly as right as HoloViz do. Matplotlib is a standard and benchmark that people will spend the effort to learn just because its recommend and documented in many, many places. hvPlot and HoloViews is starting in a different place.

[MarcSkovMadsen]

I will try to keep the Jupyter experience. The problem is that I cannot install jupyterlab and test as conda simply cannot resolve the environment for jupyterlab. At least on Python 3.6 that I installed as described in the developer docs.

[maximlt]

Well if you've pip installed hvPlot then you might as well just install jupyterlab with pip.

[MarcSkovMadsen]

Yep. Gave up and just made a normal virtual environment and used pip. It works.

[MarcSkovMadsen]

I've tried jupyter lab for hvplot with both TAB and SHIFT+TAB completion but I don't get any nice help as you show above.

How do I get what you see @maximlt ?

[maximlt]

Is df really a Pandas DataFrame in your code snippet?

And yes that was with Shift + Tab.

[MarcSkovMadsen]

My mistake. Thanks.

[MarcSkovMadsen]

I've added some example module level docstrings. But hvplot will not be easy to get nicely working in vs code because of the way its implemented using monkey patching. Static type checkers do not understand that. So right now I cannot see how we will ever be able to provide tooltips for df.hvplot or df.hvplot.scatter.

The alternative would be to a add a description on how to best work with hvplot in VS Code and other IDEs to be able to navigate and use hvplot efficiently.

[maximlt]

Yep right, I don't think tools like Pylance can now cover that, and I'm also not sure that these tools cover the case when a library uses the API offered by Pandas or Xarray to register an accessor.

What we could say to those users is that instead of calling df.hvplot() they can directly use the hvPlot class to wrap the dataframe and then will get autocompletion working in a script:

I have duplicated suggestions in the screenshot above, it might be my environment that is partially broken. Do you also get these duplicates?

[MarcSkovMadsen]

Yeah. I think hvPlot could be useful. I was in doubt whether it just worked on Pandas. But it seems to work on more data sources. Here its xarray.

I'm thinking that it would be nice one day to describe how to best use hvPlot, HoloViews and Panel in different editors and IDEs. Then hvPlot might be the way to go in a .py file in VS Code. It just needs more info in the docstrings.

Here is one example why use in editors and IDEs would be a good idea to document. https://twitter.com/cetier1/status/1551294024354373632