Add annotation stubs for PyGraph and PyDiGraph

[IvanIsCoding]

Related to #352

This PR adds type annotation stubs, it contains .pyi files with type annotations. I started by annotating the PyGraph and PyDiGraph files, as well as the custom types.

I tried to follow the PEP 561 convetion: we include .pyi files in the same directory as our Python code. Note that this is a first step in annotations: they are partial, we can add more as we go

We also test the annotations using mypy.stubtest. This was the most reliable approach. For now, we ignore missing stubs and focus only on the functions imported from Rust code

Some items we need to handle because the PR has been open for long:

• Add custom return types that were added after the PR was created

[coveralls]

Pull Request Test Coverage Report for Build 2778787088

• 0 of 0 changed or added relevant lines in 0 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage increased (+0.008%) to 97.14%

---

Totals
Change from base Build 2778191284:	0.008%
Covered Lines:	12499
Relevant Lines:	12867

---

💛 - Coveralls

[IvanIsCoding]

FWIW, this typo has been on our code base for 2 years. mypy caught it

[IvanIsCoding]

We need to keep using the latest version until python/mypy#14041 is out

[jakelishman]

I think this was released as of Mypy 1.0 a couple of weeks ago.

[IvanIsCoding]

Alright, this is ready for review after so long. mypy.stubtest checks that the stubs in this PR are identical to the text_signature from our Rust code and that the return types are valid.

Some things might be missing (e.g. all functions from rustworkx.rustworkx), but this is a good start to support annotations

[jakelishman]

This looks good to merge to me! Fantastic work, Ivan - I know I'm not one of the actual retworkx devs so it's a bit weird coming from me, but still!

I left a question or two inline (mostly for future reference), and maybe one place where's the possibility for marginally better typing, but nothing that actually needs action on this PR. I'd recommend to merge it now before it gets out-of-date again - it's been a great effort since the correct typing here is quite complex with the extra constraints on the Self type, and some of the additional co-/contra-/in- variant typing.

[jakelishman]

I was a little surprised to learn that PyO3 won't convert Iterable as a valid conversion type for Vec<_>, but you're definitely correct with the hint here. I guess maybe PyO3 didn't want to do conversions that require multiple reallocations.

[IvanIsCoding]

PyO3 has some weird quirks with iterations (e.g. #614 that broke us) so sometimes I just accept the Vec<_> conversion and if it is not in our tests it is not "canonical"

[jakelishman]

Numpy technically provide stronger type hints now, and Unpack+TypeVarTuple give some sort of way of specifying ndarray shapes / dtypes. Unless you particularly want to look into that right now, though, I'd not worry about it in favour of just landing this PR.

[jakelishman]

Again, this could be done later if you'd rather just land the PR:

I think there's a way to teach type checkers that the return type is dependent on the types of one of the arguments. It's made more complex because of the default value of the argument, so I don't precisely know the correct syntax, but it's something like

@typing.overload
def to_dot(self, /, ..., filename: None = ...) -> str: ...
@typing.overload
def to_dot(self, /, ..., filename: str = ...) -> None: ...
def to_dot(self, /, ..., filename = None): ...

I don't remember exactly how you sort out the syntax in a typing stub to combine the overload with the default value, but it's something along those lines.

[IvanIsCoding]

I like this, I will try implementing it

[jakelishman]

I think this was released as of Mypy 1.0 a couple of weeks ago.

[mtreinish]

This LGTM, thanks for adding this and sticking with it so long! It will be great to finally merge this as the longest open PR we've ever had in rustworkx :)