Distributing type stubs

[jonathanberthias]

Is your feature request related to a problem? Please describe.

Since this library is packaged as an extension module, type checkers and LSPs are not able to inspect the source code to extract type information. This makes it harder to discover available functions and methods as the IDEs cannot help.

A few months ago, I started working on type stubs for pyscipopt: https://github.com/jonathanberthias/scip-stubs. I haven't caught up with the latest changes yet but it shouldn't be too much work to update. If I install this stub package in the environment, then I get:

Describe the solution you'd like

There are 2 ways to distribute the stub files: they can either be part of the package itself as additional files, or they can be distributed in a separate package, conventionally named pkg-stubs.

The main difference between the 2 approaches is the development flow. If the stubs are part of the package, then users don't need to install an additional package and they get completion, docstrings in the IDE, type checking, etc. for free. However, it puts more burden on the contributors and maintainers as for each change, one has to ensure the stubs reflect the implementation by modifying both the source files and the stub files. It also means a new version of the library must be released for changes to stubs to be available.

If the stubs are packaged separately, there is more freedom to release on a separate schedule. For instance, the type stubs package for pyscipopt 5.6.0 could be versioned 5.6.0.0, and if a fix is needed, then 5.6.0.1 can be released. The downside is that the stubs are not in the same repo as the source, increasing the chances that they are out of sync. As an example, to test the stubs, I had to copy most of the tutorials from this repo to have some reference code. If the stubs were in this repo, the code would test the stubs automatically.

I don't have a clear preference for either model. I think it is up to you to decide which model suits your workflow best. In any case, I will gladly share the stubs I have already written and those I will add in the future, either by contributing to this repo or by publishing a separate package.

For reference, scipy have a separate repo for stubs: https://github.com/scipy/scipy-stubs, whereas gurobipy ship the type stubs with the package directly.

Happy to discuss this further if you need additional information!

[justuskilianwolff]

Would join in on this request! This would be amazing, since I stumbled across this as well and started to set up my own stub files yesterday (because I wouldn't find any existing ones). So thank you a lot for your contribution @jonathanberthias!:)

I do agree, that having an official source would be a great addition to pyscipopt.

[Joao-Dionisio]

Hey @jonathanberthias . Holy moly, is this useful!!

As I shared on the repo recently, unfortunately I won't be able to follow this very closely, but it's a great great great addition to pyscipopt.

My only concern is having to manually update every time a new function is added. Is there really not a proper way to do this automatically that is compatible with us? If not, I guess a script that scraps the files wouldn't be too bad...

Regarding your question, I'm all in favor of adding it to the package directly! The loss of flexibility is just relevant if the stubs need to be manually updated, right?

[jonathanberthias]

That's great to read @Joao-Dionisio, thanks a lot for your support! I guess I'll try to break things down into small focused PRs so that it's easy to follow, though it might take some time to get all the stubs clean and useful.

Regarding automation, there are some tools such as stubtest that check the stubs define the same functions and arguments as the runtime package. It's really good to get a broad coverage though it doesn't ensure the type annotations are correct. But it'll definitely be part of the setup for stubs, such that it will warn if a function is added to the implementation but not to the stubs. I also had a script to copy over the docstrings so that they show up in the editor, so that part can be fully automated.

[Joao-Dionisio]

Music to my ears, @jonathanberthias :)

Maybe a good initial PR would contain the most basic modeling methods (adding a variable/constraint, etc. etc.), as I guess inexperienced people would benefit the most from this.

[Joao-Dionisio]

@jonathanberthias (and @justuskilianwolff :) ), can you please give me a sort of work plan for what is coming next, to have an overview?