Add type stubs for python code

[maurosilber]

Hi, thanks for this package.

I added type stubs based on https://pyo3.rs/v0.23.3/python-typing-hints,
that provides autocomplete and type checking in VS Code.

There are other changes that I made on top of this branch, updating the type hints.

[Armavica]

Hi, thank you for adding this, I meant to do it for a long time!
I am curious why you added the docstrings, were they not extracted from the rust file for you?

For example, I removed the docstrings from the stubs file, I modified them in the rust file to make sure that I am seeing the correct ones, and after rebuilding the package I am getting this:

[maurosilber]

They do not appear for me in VSCode using Pylance.

I tried removing some docstrings from the .pyi, creating a wheel and installing it in a new environment. Pylance only shows the docstrings included in the .pyi file.

In the wheel, the docstrings generated from maturin are (probably) inside the binary .so file. I don't think that Pylance would get them from there, but I may have something misconfigured. In your screenshot, how does it know that it is a "rust annotation"? 🤔

[Armavica]

They do not appear for me in VSCode using Pylance.

Is this a VSCode extension? I'm not finding it, perhaps because I am using VSCodium?
On VSCodium I installed what looked like the most popular extension, called Python (ms-python).
I'll try with VSCode and Pylance.

In your screenshot, how does it know that it is a "rust annotation"? 🤔

I added (rust annotation) myself to the lib.rs file in order to make sure I was seeing this one (and not an old cached one).

To be complete about the steps that make it work for me:

1. Remove a docstring from the stubs file
2. Change the corresponding docstring in the lib.rs file (to check that it is indeed taken from this file)
3. Run maturin develop in a terminal
4. Close and reopen VSCodium

[Armavica]

For context it also works with the lib.rs docstrings in my regular editor, helix, with the pylsp language server:

[maurosilber]

Pylance is the default language support for Python in Visual Studio Code and is shipped as part of that extension as an optional dependency.

Ok, I tried changing the language server from Pylance to Jedi (the other one that is included in the VSCode Python extension, and that is also used by pylsp) and now it detects the docstrings from "rust". I think the difference lies in that Jedi gets the docstrings from runtime (running Gillespie.__doc__ or something like that), while Pylance gets them from source without running any python code.

[Armavica]

Yes I confirm that it doesn't work with Pylance and VSCode. I uninstalled Pylance (but kept the Python extension), and now it's working:

[Armavica]

How painful is using Jedi instead of Pylance? My concern about duplicating the docstrings is that they could get out of sync, so I would tend to avoid it if possible, but if we can easily autogenerate this file including docstrings, that could be an option.

[maurosilber]

Yes, I didn't like this solution either for that reason. They seem to be working on generating them automatically: PyO3/pyo3#2454

Regarding the Jedi vs Pylance, I think the ecosystem is shifting towards the Pylance approach of not running Python code for the language server. I believe the ruff language server will do the same if it starts providing autocomplete features (they are currently working on adding a static type checker).

[Armavica]

Ok, then let's merge this now because it is a clear improvement and so that I can look at your other PRs, and I will create an issue to keep this in mind. Thank you!