Provide type hints for type checkers and language servers

[Daverball]

While there are a lot of modules in this package, since the common interface is very simple from a type system perspective I think it would introduce little to no additional maintenance burden to include type hints and the majority of the initial hints could be added automatically for the common interface using something like sed or awk.

If there's any interest in maintaining inline type hints I'd be happy to create a pull request, if you'd rather not, I can go the typeshed route instead. I've already contributed type hints for various third party packages including Chameleon, WebOb, WTForms, uWSGI and gevent, just to name a few.

[arthurdejong]

Hi,

Sorry for not replying sooner. How would this look like? Currently python-stdnum still supports Python 2.7 (support will probably be dropped per Jan 2025).

Also, can you describe what the benefit would be of type hints (for python-stdnum but also for users of the library)? Are there particular classes of bugs that are more easily found and fixed or is it mostly for API documentation purposes?

Thanks,

[Daverball]

Hi, no worries.

There's type comments that work with Python 2.7, that can easily be automatically converted to inline type annotations using something like pyupgrade later on. Here's an example from sentry's python client for how that would look like:
https://github.com/getsentry/sentry-python/blob/25de71e5f7f4de0540eafdbaf8ca26f1b9e9b438/sentry_sdk/client.py#L157-L165

But we could also just defer the inclusion of type hints until 2025 and maintain a separate stub package in typeshed until then. There's automated tooling to merge external stubs into inline annotations, so there would not be a lot of transition work required there either.

In the case of this specific package the benefit in safety is in all likelihood very small, considering how simple the API is, but it might catch some problematic corner cases in the implementations here or there that would otherwise have only been caught by rigorous unit testing. The main benefit I see in language servers telling you what kind of objects the functions expect, but the API documentation would of course be improved as well by the inclusion of the type hint.