Improve type-hinting for contributors

[abn]

Been pondering this for a while now. One of the hindrances I have had working with the code base has been a lack of type hinting. I have for better or worse grown a bit accustomed to PyCharm's type-hinting, for example here. It does support reStructuredText based type hinting. However, I find it is a bit lacking. The documentation coverage in this code base is rather good so no complaints there.

Not sure how best to go with this. One one had using anything not rst might not work with how we do docs today. But on the other hand, type hinting does allow for a better maintainable code base.

@cablehead would love your take on this one.

I'd be interested in considering something along the lines of typeshed. This does adhere to PEP-3107 and PEP-484.

Open to hear from others on this one.

[cablehead]

I'm all for anything that makes development easier!

I'm trying to understand the trade offs. If I'm reading right, the current way of documenting (rst based) isn't a good mix with the best way to do type hinting?

If that's the case, what does it look like to transition our documentation over to the better type hint method?