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,

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.

@arthurdejong One other challenge with inline type hints will probably be that current type checkers and typeshed only support Python versions that aren't EOL, there's still some support for 3.8 in type checkers, but it will likely be gone by summer and there is no support for 3.6 and 3.7. So unless you're happy to drop support for Python 3.8 and below, we will need to weigh the costs of maintaining support for these versions.

Maintaining compatibility with an old version of mypy that supports 3.6 at the same time as the latest version of mypy may prove challenging, although hopefully there are so few standard library dependencies, that we don't run into any compatibility issues.

Thankfully mypy 1.5.1 isn't so old that I expect a ton of behavioral discrepancies, although there are some error codes that have been renamed/added/removed, so we wouldn't be able to use targeted type: ignore comments and instead would have to rely on blanket type: ignore comments, potentially without enabling the detection of unused ignore comments, since it may only be unused with one of the versions. But that would still be potentially noisy for downstream users. So we had better hope there isn't a need for type ignore comments.

Alternatively we could decide to no worry about supporting type hints in older Python versions. We would still need to make sure to document which things need to be imported from typing_extensions rather than typing. Since the latest version of mypy will not be able to complain about things in typing that aren't yet available in 3.6. Although given how simple most of the functions are, we may not even really need to ever import from typing at runtime anyways and instead can provide our own types module that gives access to the few things we want to support.

Also currently you're not putting a version gate into setup.py, even though you don't test with any Python version below 3.6. In this case using annotations would set a hard limit to 3.5 or 3.6 if we want to write modern, more readable type hints using from __future__ import annotations. If the goal is to not restrict EOL Python 3 versions at all, then we would have to use type comments like I showed above. Although the risk there is that the support may be dropped at any time, since that style of type annotation is technically deprecated. Newer type checkers are likely to not implement support for this feature at all. So then the only choice you would have is to ship stub files alongside the source code, which would need to be checked by stubtest so they stay in sync. So at that point it might be easier to delegate to typeshed, since they provide infrastructure for shipping stubs and making sure they stay in sync.

If you decide that hard-dropping support for anything below 3.6 or 3.9 is acceptable for the benefit of inline type hints, I'd be happy to work on a PR, so you can see how that would look. I don't expect it to be a lot of work, since a lot of the function definitions have the same signature, so the type hints can be generated automatically.