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 89.91935% with 25 lines in your changes missing coverage. Please review.

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

[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]

I think one way forward is to (i) separate the aliases from the function parsing, (ii) provide a mapping table on the docs, (iii) maybe deprecate it later. The first step would fix the busy static inference here and help some with the setup. It will also be easier to deprecate (or add) aliases.

I don't want to remove stuff that is already there unless it is necessary, but some of these functions have crazy number of parameters. What do you think?

[gepcel]

I think with steps (i) separate the aliases from the function parsing, (ii) provide a mapping table on the docs, that will give us more time to think about deprecation, and maybe even better, it might even make deprecation less necessary.

[gepcel]

Although I mentioned that I use aliases frequently, I probably only use a small fraction of them. However, my point is that with all 944 aliases available, different users can always pick different aliases they like best—and what suits for one person may not be the same for another. After all those long times, deperating them all will make people confusing too, because, some names they are using are aliases without them knowing it.

When we speak of alias names, we tend to assume that there is a single official name—the one that all aliases are ultimately converted to internally in the codebase. Everything else are just shortcuts that get mapped away.

However, if you go through all those official name and their aliases, you'll quickly notice that they aren't all chosen by the same logic, and are more subjective. This lack of consistency and the fact of subjective can itself become a source of confusion.

For Ultraplot (and Proplot before it), one of the goals has always been to make daily plotting easier. This is achieved not only through the format philosophy, but also through the alias system, which plays a crucial role in that ease of use.

[cvanelteren]

I agree with that the aim should be to make plotting easier. I have tried to convince people to use ultraplot as I think it is great, but people get kinda lost in the many options that one is faced with -- the aliases don't help there. Tutorials will help ofc, but I dunno myself on exactly what magic bullet would help understanding all the keywords that are there. Potentially a rule would help. Like linewidth to lw is sensible but width to figwidth is less clear if the usage is something outside Figure.format or whatever. They can also bloat clean signatures, like what this PR shows a bit.

I think separating them so that they do exist, but the user can see a cleaned function description may work. This, combined with a map of the available aliases, would then give the best of both worlds I think.

[gepcel]

I think separating them so that they do exist, but the user can see a cleaned function description may work. This, combined with a map of the available aliases, would then give the best of both worlds I think.

I agree, as I said, maybe starting by less alias in documents, less confusing for new uses. Let them keep exising by separating for people get used to them.

[cvanelteren]

I think that is a good way forward tbh.

[munechika-koyo]

I think separating them so that they do exist, but the user can see a cleaned function description may work. This, combined with a map of the available aliases, would then give the best of both worlds I think.

I also agree.
Reducing the time required to review the documents (only seeing docstrings or annotations from assisting tools) would help users focus on coding tasks.

[cvanelteren]

Merged #818 with this PR and it shows for example the complete like this now (basedpyright):

[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.