Feature: add signature exposure for static inference

[cvanelteren]

Ultraplot does a lot of runtime composition (lazy loading, dynamic dispatch, and shared doc merging), which makes static analysis difficult because analyzers see only source-level declarations, not the final runtime-expanded API. The lazy loader compounds this by delaying object/materialization of the public surface. On top of that, _obfuscate_parameters historically replaced visible signatures with compact (**kwargs) forms to keep docs manageable, which also removed concrete parameter metadata from inspect.signature, so tools like Pylance had less to work with for hovers/call tips.

So the concrete problem was a combo of:

1. runtime indirection (lazy loading),
2. runtime signature/docstring composition, and
3. signature obfuscation for docs at the callable object level.

This PR separates the two processes by keeping a copy for the docs themselves while using a process that static analysers like Pylance can work with.

[codecov]

Codecov Report

❌ Patch coverage is 87.56757% with 23 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
ultraplot/tests/test_stubs.py	76.31%	13 Missing and 5 partials ⚠️
ultraplot/tests/test_docstring_helpers.py	93.33%	3 Missing ⚠️
ultraplot/internals/docstring.py	92.30%	0 Missing and 1 partial ⚠️
ultraplot/tests/test_kwargs_helpers.py	87.50%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[cvanelteren]

Does this work @munechika-koyo ?

[cvanelteren]

TODO: get an editor with pylance

[munechika-koyo]

I checked how the static type-checking tool (pyrefly in my case) behaves in the PR environment.
The results are below:

Since the docstrings are dynamically created when importing ultraplot at runtime, is it difficult for such tools to handle this information statically?

[cvanelteren]

From my understanding yes. Custom stubs would work but that is very not handy to maintain.

[cvanelteren]

So had a bit more digging. The solution it seems is that one would have to generate and comit the stubs to the repo in order for it to work with the static viewer properly. This is also how mpl does it.

[munechika-koyo]

It's true that management costs might go up, but that seems like the better option for generating stubs in a runtime environment, for example, using mypy's stubgen tool.

[cvanelteren]

Can you check the editor with the stubs added? (30k jeezzzz)

[munechika-koyo]

In my environment with pyrefly, I couldn't see the correct generated docstrings on hover because it prioritizes using docstrings in *.py files, not .pyi files.
I submitted the issue to pyrefly: facebook/pyrefly#4803.

Anyway, there appear to be many Incomplete types in .pyi files.

UltraPlot/ultraplot/constructor.pyi

Line 118 in f2571e1

def Colormap(*args: Incomplete, name: Incomplete=None, listmode: Incomplete='perceptual', filemode: Incomplete='continuous', discrete: Incomplete=False, cycle: Incomplete=None, save: Incomplete=False, save_kw: Incomplete=None, **kwargs: Incomplete) -> Incomplete:

Were they caused by automatic generation?
Is it possible to fix the types for them?

[cvanelteren]

Most of the codebase is not type annotated yet and the automatic inference fallsback to Incomplete I think

[cvanelteren]

Wouldn't this solve all the issues: https://marketplace.visualstudio.com/items?itemName=KiidxAtlas.python-hover

[munechika-koyo]

Looks like it doesn't solve it...

[cvanelteren]

hmm annoying. help ofc works fine

[cvanelteren]

I added a dynamic inspector prior to dumping the stubs to expand the stubs, does this work @munechika-koyo ?