Add type hints

[kasium]

❓ I'm submitting a ...

• 🐞 bug report
• 🐣 feature request
• ❓ question about the decisions made in the repository

🐣 Describe the solution you'd like
It would be great to see the python 3.5+ type hints in the repository, especially for the Server api.

📋 Describe alternatives you've considered
Adding type stubs to typeshed (https://github.com/python/typeshed/tree/master/stubs).
If you think this makes more sense, that's possible. But I first wanted to ask here.

[webknjaz]

I'd love to see type hints here in Cheroot and in CherryPy. The next major release is supposed to be dropping py2 so it's possible to use native syntax. OTOH, we could also try pyi files or comment-based hints for something to be available in the 8.x stream. PR is welcome :)

[kasium]

@webknjaz Let me try to add some more context and ideas

• type comments: very limited syntax but python 2 compatible. I guess it's not worth the effort due the deprecation of python 2
• pyi files: would then be part of typeshed I guess? However, I prefer native support, because you don't forget to adapt the types when you code. In addition, mypy can then also help you during development.

I'm happy to file a PR adding mypy and some utility stuff. I can also try to add some types by my own but I guess help of the actual core developers will be needed. In addition it should be decided, if you would like to type your whole codebase or only the public API.

That's btw just my view, so please feel free to add yours 😄

[webknjaz]

• type comments: very limited syntax but python 2 compatible. I guess it's not worth the effort due the deprecation of python 2

There's more to it. We were thinking about keeping the 8.x for bugfixes. This means that we'd need to backport things from the newer versions. Active use of the newer syntax would mean the need to manually resolve conflicts, which adds to the maintainance burden. OTOH if the code base is similar enough, git cherry-pick will be able to apply patches cleanly, meaning that we could just rely on the backporting bot to do this.
So from this perspective, it's totally worth the effort. This is the main reason I proposed this.

• pyi files: would then be part of typeshed I guess? However, I prefer native support, because you don't forget to adapt the types when you code. In addition, mypy can then also help you during development.

No, pyi files can also live in the project next to their counterparts.

I'm happy to file a PR adding mypy and some utility stuff. I can also try to add some types by my own but I guess help of the actual core developers will be needed. In addition it should be decided, if you would like to type your whole codebase or only the public API.

You can count on me for reviews. Also, the mypy integration should go to the pre-commit.com config FYI.

Oh, and a bonus though: it'd be interesting to also use all of the other type checkers that exist, at least in the CI. Because the users or Pyro or other stuff would get different results compared to the mypy users and we need to be compliant with all of these.

[kasium]

Sorry for the late reply. I agree with you, pyi files seem to be the best solution. If it's fine for you, I'll try to add some base hints for e.g. the Server and then let's see

[webknjaz]

Sounds good. Note that I'm on vacation and may be unable to review for a week or two.

[kasium]

So, the first part was now merged. However, certain parts are missing:

• Add typing to _compat (Add types for _compat.py #491)
• Add typing to tests (?)
• Activate "warn_usused_ignore" (needed because of differences in py2 and py3)
• Add stubtest ( Configure stubtest hook for stub testing #415 )
• Add py.typed file and add it to the distribution (Add py.typed file #406)
• Improve the stubs (add missing types and remove Any's)

[kasium]

@webknjaz can you please share your opinion about typing in tests. Personally I do that in my projects, but I use inline types (a: int= 2). However, having a pyi file which types the tests seems weird to me, since each time you add a test, you need also to add types for it.

[webknjaz]

@kasium can we go for inline type comments in tests?

[kasium]

@webknjaz aren't they also execute in python2? If yes, type comments would be the only way since the syntax is py3 only

[webknjaz]

That's exactly what I was suggesting.

[kasium]

@webknjaz what should we do with private methods? If they are not part of the pyi files, mypy complains in tests

[webknjaz]

In that case — yes.

[kasium]

@webknjaz I'll try to work on the open points in the next time

[webknjaz]

Sure, no hurry. Thanks!

[mgrabovsky]

Hi, is there something left to be done here? Which files specifically need to be annotated?

[kasium]

@mgrabovsky I guess this is done

[webknjaz]

@kasium it seems like there's something in your TODO comment at #384 (comment) that could be imrpoved.

@mgrabovsky if you want to contribute improvements, you could look at replacing the Any types in stubs with more accurate values and maybe explore adding type stubs for tests.

[kasium]

Ah right. Thanks 👍

Yes, the types could be improved but else the item is finished