holoviz
Enable intellisense for arguments to widgets, panes, layouts etc.
One challenge when using Panel and the rest of the HoloViz ecosystem is the lack of useful intellisense in a modern editor and IDE.
Panel
No help on input arguments. Means you will have to remember or look up things. This slows you down and adds mental strain
Streamlit
Provides much more help when you need it.
Additional Context
I believe there are ways to inherit docs/ arguments from parent classes. I believe some frameworks have code we could copy.
Alternatively we would have to add custom constructors all over the Panel code.
Kind of frustrated by this, we explicitly enabled signatures on Parameterized class constructors which should be the accepted way to declare the accepted kwargs. Anyone know what Intellisense uses to extract the signature?
Assuming you're using Pylance as your language server, it's primarily based on type hints. If you believe you implemented them appropriately and it still isn't working then please open an issue at https://github.com/microsoft/pylance-release so the team can look into it.
If you're using Jedi then please open an issue at https://github.com/davidhalter/jedi .
Maybe adding a py.typed file might help https://blog.whtsky.me/tech/2021/dont-forget-py.typed-for-your-typed-python-package/
Maybe we should look into what, Django models, attrs, data classes, traits, pydantic etc do? They must have solved this problem?
For attrs at least, they implemented https://github.com/microsoft/pyright/blob/main/specs/dataclass_transforms.md which I believe is in the process of becoming a proposed PEP. It's documented at https://www.attrs.org/en/stable/extending.html?highlight=pyright#pyright .
I've created a Feature Request with Param because it has to be solved there https://github.com/holoviz/param/issues/587. I would suggest continuing the discussion there. Thanks.
I now have some very preliminary code to automatically generate stubs. But then you start to wonder have many arguments we should show in the __init__ method. And how they should be sorted ??
Relevance: Sorted by order in the class mro() and order of instantiation
I like the relevance sort. But the number of arguments is overwhelming and means it can be difficult to see anything of the docstring.
Alphabetic
Not very useful and overwhelming.
Relevance and restricted to max 7 (?) arguments. Rest is **params
Useful. But then the Stub generating code would relate to Panel objects while I would like Stub generating code that works for all code having param.Parameterized classes.
Relevance and restricted to non Widget, Pane and Layout parameters
(no example inserted)
Any opinion here @maximlt ?
Thanks for starting on that. MRO order is a decent but not perfect proxy for relevance so I think I'd want to stick with that by default. I would not set quite such a low limit since some of the benefit is tab completion (or am I wrong about that?). I think I'd want to ship this stub generation code in Param. Lastly I think it's reasonable if you could define an explicit attribute that declares which parameters show up in the stub.
Mypy ships with stubgen. A generator to create stubs. I was thinking that this is aparam_stubgen. To create stubs for Parameterized classes and packages of these. Could also live in its own package ??
As far as I can see you can both put stubs into seperate folder or package. Or you can make it create .pyi files in the same folder or package. For example adding the slider.pyi next to the slider.py file. We need to find out what we would like to do ??
I can also see now that I can create stubs and get type hints that some docs is missing from Panel and maybe the order of some widgets could be changed to bring the most relevant to the top of the attention.
Put my experimental code here https://github.com/holoviz/panel/pull/3132 to facilitate the learning and discussion.
I took a second look at https://github.com/microsoft/pyright/blob/main/specs/dataclass_transforms.md that will enable mypy, VS code/ pyright and other static analysis tools to understand dataclass like frameworks like attrs, Pydantic etc.
If this becomes an adopted standard, then I believe its worth investigating if Param should not adopt to this standard. The problem is that I believe it would require a few "breaking changes". But on the other hand it is the path of "modern Python" to work great with static type analysis tools.
It turns out that VS Code tooltips are much more capable of showing Markdown based docstring than Restructured Text based. And HoloViews is using Restructured Text. I guess for historical reasons and because it works with Sphinx.
I've filled a FR for better Restructured Text based tooltips in VS Code here https://github.com/microsoft/pyright/issues/2944.
For now I will probably implement some sort of minimum conversion of ReST to Markdown, so that the stub files will be Markdown based and useful.
But there is actually a general problem regarding docstrings here for the Python community. If they are nicely formatted in your environment you can be much more productive. VS Code works formats Markdown to some level, Jupyter does not really format docstrings and make them useful, Sphinx works best with RestructuredText docstrings (?). And a lot of very popular python packages have ReST based docstrings.
I'd strongly prefer to move everything to Markdown instead of RST, and Sphinx generally now has much better support for Markdown in various contexts previously requiring RST, so I'd really hope that will be feasible. I'm happy for this sort of support to be in Param rather than a separate module; should be available to all!
Should push on Jupyter to render markdown docstrings nicely in that case.
I'm not sure which context is being referred to here; in code cells? In ?? help? In any case as long as it doesn't format it at all, Markdown is more readable than RST even without any formatting.
I'm referring to ? output in Jupyter. it does not render.
In vs code this would look like
That sounds like an orthogonal issue, then; current rendering as plain text isn't affected by what formatting we use in docstrings, with markdown being at least as readable as any other alternative. But yes, if Jupyter did render the Markdown, this proposal would end up even more impactful!