Feature: add signature exposure for static inference

[cvanelteren]

UltraPlot does a lot of runtime composition (lazy loading, dynamic dispatch, shared doc merging, and compact documentation signatures), which makes static analysis difficult because analyzers see only source-level declarations rather than the final runtime-expanded API.

This PR now takes a single-source approach:

1. Runtime call signatures remain visible instead of being replaced for documentation.
2. The checked-in .py files remain the only authored API representation.
3. Reusable docstring snippets stay DRY in the existing snippet registry.
4. During wheel builds, those snippets are materialized into literal docstrings in the copied build tree.
5. Installed wheels therefore expose ordinary Python docstrings to Pylance without shipping or maintaining generated .pyi files.
6. CI builds an isolated wheel and verifies that registered placeholders are fully expanded and that no generated stubs are shipped.

Editable/source installs keep the existing runtime docstring expansion behavior; normal wheel installs get statically visible expanded docstrings.

[codecov]

Codecov Report

❌ Patch coverage is 92.85714% with 9 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
ultraplot/axes/cartesian.py	37.50%	5 Missing ⚠️
ultraplot/tests/test_docstring_helpers.py	94.11%	3 Missing ⚠️
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 ?

[cvanelteren]

Note there is another small issue that proplot clearly intended the docs to be used as a replacement. So many of the docstrings are near novels.

[cvanelteren]

Nvm I noticed I broker a bunch of stuff for myself now. I will fix that first before I ping again.

[cvanelteren]

Ok I got the tool complete to work again in zed:

[cvanelteren]

@munechika-koyo can you check this PR again. At least on basedpyright is working now.

[munechika-koyo]

pyrefly is now handling the issue of prioritizing pyi's docstrings , so I will confirm it after the change is released.
However, I presume it should be fine if other tools like basedpyright work well.

[cvanelteren]

Need to explore if there is not another way. Potentially we would need to get rid of how the docstrings are expanded.

[munechika-koyo]

OK, to avoid adding way too many files, it may be better to offer the "stub" package instead, like scipy-stubs.

[cvanelteren]

I preferably don't want to manually keep track of the stubs. I can automate it for deving through workflows but it will still be annoying as autocommits would need to be pulled back down to sync up (or regenerated). The major issue is that ProPlot was using DRY principles to weave in docstrings that are fine for run time inspection but not for these static inspectors. Redoing all the doc strings violates that principle, but that would gain having the doc strings where they actually belong (in the function description). What I don't like right now is that the doc strings are defined early on in the document and not where the function actually sits, but I recognize the complexity of the dynamic and DRY stuff

[munechika-koyo]

I presume the dynamic strategy in this library is key from the perspective of API simplicity at runtime. (e.g. format() method associated with different classes.)
Meanwhile, statically typed implementations in Python seem to be growing increasingly popular, which makes the dynamic one more difficult.

If it is hard to build the stub files into the CI automation, what about moving it into the pre-CD workflow?
I understand it's dangerous since we don't confirm stubs in advance, but we can at least check them using the stubtest command.

Anyway, we probably need to find the best way to automate stub creation in CI.

[cvanelteren]

pre-commit.ci autofix

[cvanelteren]

I have added the stubs for wheel releases -- this way users have it while not needing to add the stubs in the dev version.