What is the policy regarding contributing type annotations?

[nathanjmcdougall]

Hi,

What is the policy for contributing to type annotations? Are such contributions welcome?

My motivation for having high-quality type annotations is as follows:

• When using pins-python, type annotations can improve the user experience for editors that use type-based syntax highlighting.
• Type annotations can improve the user experience for users who are using type checking tools such as mypy.
• When contributing to pins-python, type annotations serve as a form of documentation that make it easier to understand the codebase. I am currently trying to get my head around things 😄   Some considerations:
• Perhaps a pre-requisite is that a type checker is configured for the project (to ensure annotations are actually correct). Would you be open to this?
• Some functions e.g. pins.versions.version_setup are currently unannotated but annotating them would introduce a cyclic dependency which could not be fixed without from future import __annotations__ or refactoring. Personally, I think refactoring in such cases can introduce clarity but there are definitely trade-offs. It would be good to know if this sort of refactoring is "off limits".
• Some functions such as pins.boards.BaseBoard.pin_versions could have more narrowly scoped types using @overload to differentiate cases. You may find the complexity this introduces to be unacceptable, it would be good to know if this is the case.

[isabelizimm]

This is an interesting question 👀 some thoughts:

• from future import __annotations__ is a big thumbs up from me! Totally fine to use that here.
• Step 1 (or Step 0, depending on your indexing) would indeed be all the setup for a type checker. I have a preference for pyright as it is what I have used in other projects and find it pleasant enough to work with, but if you have strong feelings on why that isn't the right fit, I'd be interested to hear them!
• Re: @overload: I would say that, in general, I am not opposed to overloading. My biggest concern is that (as far as I know?), overloads must be repeated each time there is a subclass. One place this might get a little hairy is BaseBoard.pin_write/BoardRsConnect.pin_write. It could be the case that there's an elegant way I've woefully missed out on, but that was the first place that came to mind that has the potential to be painful due to overloads. BUT other places like BaseBoard.pin_versions could certainly benefit from @overload in a way that might be less repetitive.

I'm less concerned with "everything must be typed perfectly to appease a type checker" and more interested in "types are added to relieving developer/user pain." It's a subtle difference, sometimes the statements overlap, and unfortunately not clear direction, but to give some context to my worldview. 🌷 BUT I would say, setting up a type checker would be accepted/appreciated and then going one file/part of a file at a time after that is a reasonable way to start solving this!

[nathanjmcdougall]

Great, I agree with all of that 😃

I especially agree with this approach:

I'm less concerned with "everything must be typed perfectly to appease a type checker" and more interested in "types are added to relieving developer/user pain."

With the right configuration hopefully a balance can be struck.