Repository navigation
Distributing type stubs #1072
Description
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!
Activity
justuskilianwolff commentedon Sep 16, 2025
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 commentedon Sep 17, 2025
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 commentedon Sep 20, 2025
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 commentedon Sep 22, 2025
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 commentedon Oct 6, 2025
@jonathanberthias (and @justuskilianwolff :) ), can you please give me a sort of work plan for what is coming next, to have an overview?
jonathanberthias commentedon Oct 7, 2025
Here is a high-level task list:
stubtest(Runstubtestto check stubs are complete #1141).Sorry if this list is a bit raw, I might polish it a little as I get through the items. I think doing the first 3 steps is important to reach a state where the type annotations bring a lot of value to users, the following steps are more focused on maintainability.
If the question is whether we should wait for some of these before cutting a release, I think we shouldn't. This process can be done in parallel to new features, and it won't be done before a long time. And type annotations can't break user code, they should just help the dev experience for the time being - though at some point there might be type errors in user code, but that's the goal 😉
justuskilianwolff commentedon Oct 8, 2025
Happy to support where support is needed! :)
Joao-Dionisio commentedon Oct 23, 2025
Hey @jonathanberthias, just letting you know that a new minor SCIP will release in about a week or so, meaning that a new PySCIPOpt release will come hopefully soon after. Just letting you know, in case there's something related to this that you feel would be nice to have in this release.
jonathanberthias commentedon Oct 24, 2025
Thanks for the heads up @Joao-Dionisio! I'll probably just check again that all methods exist in the stubs since a lot of PRs have been merged recently, but other than that I think actually filling in the stubs with useful information can wait for the next releases.
Joao-Dionisio commentedon Jan 13, 2026
Hey @jonathanberthias , added checkboxes to your comment, to keep track of the progress. Keep up the great work!
Joao-Dionisio commentedon Apr 2, 2026
Hey @jonathanberthias ! Is this still something you're working on, or are planning to pick up again?
jonathanberthias commentedon Apr 4, 2026
Hi @Joao-Dionisio, yes absolutely! Life has been very busy for the past few months, but I still hope to get some time to come back to this. I see there has been a lot of activity on the repo which adds some complexity to the task, I'll have to figure out a way to get up to speed 😄
justuskilianwolff commentedon May 13, 2026
@jonathanberthias if you need any support please lmk
jonathanberthias commentedon May 17, 2026
Hi, for an update, my current focus is on being able to run
stubgen-pyxon this repo!If this approach works, it means all type information will be sourced from the
*.pxifiles so we won't need to manually update the stubs. The downside is that it means we need a lot more type annotations in the*.pxifiles as currently there are very few explicit types.You can see what gets generated currently in my fork: https://github.com/jonathanberthias/PySCIPOpt/blob/stubgen-pyx/src/pyscipopt/scip.pyi
The file is not valid yet, I've opened a couple issues to try to get them fixed: jon-edward/stubgen-pyx#20 and jon-edward/stubgen-pyx#22.
supersonic-copycat commentedon Jul 17, 2026
@jonathanberthias, thank you for your great work!
When I installed PySCIPOpt I got quite disappointed -- almost all methods, parameters, etc were stuffed with
Incomplete. Now it is much better, but there are still things to be done. Since I'm going to use SCIP, I'd like to help you. I started to look at code and get kind of confused. Is there kind of roadmap or something?jonathanberthias commentedon Sep 6, 2026
Hi @supersonic-copycat! Thanks for the kind words. Sorry for the radio silence on my end; life has been busy and I should have given an update sooner.
To answer your question: yes, please feel free to contribute to the stubs directly if any area interests you. There are still many untyped methods, the work on the expression arithmetic #1231 should make it easier to annotate them faithfully.
At this point, there is no specific area that should be worked on, rather any method with
Incompletetypes should be looked at and given concrete type annotations. Your experience can be valuable here, you can work on typing the methods you use and where you found incomplete annotations, as I assume that means those are the most useful to get correct first.Joao-Dionisio commentedon Oct 8, 2026
Hey @jonathanberthias , can you please update and/or refine the task list in #1072 (comment)?
jonathanberthias commentedon Oct 17, 2026
Sorry I missed this comment in notification noise. I've just updated the list to better reflect past changes and what is left. I believe we can consider this feature request as "done".
There are still some things that can be improved, but most of the value of type stubs is already available. For the remaining work, I will likely open specialized issues since they require decisions and potentially changes to the runtime package.
Joao-Dionisio commentedon Oct 17, 2026
Alright, @jonathanberthias , you're the man! Thank you so much for single-handedly bringing in so much value to PySCIPOpt!! And I'm super happy to see you keep contributing for as long as you're willing! 🫶