Deprecate type comment support?

[ethanhs]

I've kicked off a discussion on typing-sig, as some of you have already seen, to talk about deprecating and eventually removing type comments.

Currently, the ast module takes type_comments=True to enable parsing any type comment.

I am proposing that this argument emit deprecation warnings with Python 3.12 and 3.13. With Python 3.14 type_comments=True will be removed, and all type comments except for # type: ignore will be treated as normal comments. (# type: ignore will always parse as its own node in the parser).

There is a complication: ast.parse also accepts feature_version. 3.11 is not EOL until 2027, so if someone wanted to parse code written targeting 3.11 with a mypy running on, say 3.14, that would not work under my proposal. I believe that this is acceptable, because the user would have 2 reasonable alternatives: 1) type check their code targeting 3.11 with mypy running on 3.11 2) update to type annotations, which they will need to do eventually anyway, and would have 3 years to do so already.

I think the existing tooling such as libcst, pyupgrade, com2ann, etc make the upgrade relatively straight forward.

I'd be interested to hear what others think mypy should do in regards to removing support for type comments (or if we should at all!)

[gvanrossum]

Remind us of what's the best tool to convert type comments to type annotations?

[ethanhs]

I've successfully used Ivan's com2ann, though I believe it may not cover every edge case such as tuple assignment. There is also a libcst codemod (a CST rewriter as far as I can tell) which I haven't tried before, but apparently is more comprehensive.

[JukkaL]

Based on the typing-sig discussion, lots of packages still have some type comments. Every project that has supported Python 3.5 at some point and hasn't used com2ann or similar tool (or manually updated type comments) seems quite likely to have some type comments lying around, since variable annotations were introduced in Python 3.6. I think that we should give users a lot of time to update their code, since type comments are still very common, and getting rid of them adds some friction. (At Dropbox we have mostly moved away from type comments, but we still have some that haven't been migrated.)

A particular trickiness is that users will generally want to use from __future__ import annotations if they are migrating from type comments, to support forward references without string literal escapes. I'm not sure if any tools can deal with string literal escaping automatically. The future import is not supported by Python 3.6, and Python 3.6 is still quite popular according to PyPI stats (example). This might partially explain why so many projects are still using type comments, but it's just a guess.

There is also the question of what will replace from __future__ import annotations. Anybody currently using type comments and not using the future import may have to perform two (fairly easy, arguably) migrations in the next several years -- first move to type annotations and from __future__ import annotations, and later move on to whatever will replace it.

To be honest, my preference would be to only deprecate type comments after we are confident that only a small minority of projects are still using them. This probably wouldn't be the case by the Python 3.11 release date. Even better, it would be nice if users were able to migrate to something that can reasonably be believed to be a long-term solution. If a replacement for from __future__ import annotations will be included in 3.12 (that's the earliest possible release), this could imply that we'd deprecate type comments when most people are no longer using 3.11! The deprecation period would be way too long, I think, so the latter idea doesn't seem practical.

Finally, it would be nice if there was a well-documented tool to migrate all type comments automatically. I've heard about a LibCST codemod, but I don't actually know where to find it or how to use it, and com2ann doesn't cover all use cases, right?