MAINT Migration from mypy to ty

[maifeeulasad]

Description

closes #1313

Tests and Documentation

[maifeeulasad]

Note 1: There is no pre commit hook for ty as of today (2026.01.17)

"We don't plan on adding this right now because ty is still at a very early, experimental stage and we don't want to give the impression that it's ready for serious production use yet. When we're closer to feature-complete, however, we'll absolutely be adding this." - Alex Waygood

ref:

• pre-commit hook for ty astral-sh/ty#269 (comment)

[maifeeulasad]

Note 2: await outside func/async function

We are getting errors saying

• error[invalid-syntax]: *await* statement outside of a function
• error[invalid-syntax]: *await* outside of an asynchronous function

It is something under discussion there:

Interesting. What are the options we have here?

Keep it a rule
Introduce parser options (per file?)
Always allow
-- Micha Reiser

And then we got reply saying:

I don't think this is a realistic option for non-notebook files: for the vast majority of Python code this is a syntax error; we should definitely flag it by default for non-notebooks.

I'm not totally familiar with the situation for notebooks, honestly, as I've never seriously used notebooks. I can't tell you whether top-level awaits are allowed by default in notebooks or if it's only if some settings are enabled. I believe they're much more common in notebooks than in regular Python source code, however. For notebooks, we may want it to be an opt-in diagnostic rather than an opt-out diagnostic.

And even for regular Python source code, we'll want this to be at least suppressible on a per-file basis. Although it's pretty rare to use ast.PyCF_ALLOW_TOP_LEVEL_AWAIT for non-notebooks, it is possible.

I don't have strong opinions on how we make this diagnostic suppressible -- whether it stays as a linter rule or if you add per-file parser options.
-- Alex Waygood

I think it will take quite a while to get this feature.

ref:

• Allow top-level await in modules compiled with ast.PyCF_ALLOW_TOP_LEVEL_AWAIT astral-sh/ruff#17395 (comment)
• Allow top-level await in modules compiled with ast.PyCF_ALLOW_TOP_LEVEL_AWAIT astral-sh/ruff#17395 (comment)

[maifeeulasad]

Here is existing mypy configuration:

[tool.mypy]
plugins = []
ignore_missing_imports = true
strict = false
follow_imports = "silent"
strict_optional = false
disable_error_code = ["empty-body"]
exclude = ["doc/code/"]

And here is what I am migrating into:

[tool.ty]
[tool.ty.rules]
unresolved-import = "ignore"
possibly-missing-attribute = "ignore"
unused-ignore-comment = "ignore"
[tool.ty.analysis]
respect-type-ignore-comments = true
[tool.ty.src]
exclude = ["doc/code/"]

And here is my mapping, or the reason:

mypy flag	visible behavior	ty rule
ignore_missing_imports = true	no import errors	unresolved-import = "ignore"
strict_optional = false	None tolerated	possibly-missing-attribute = "ignore"
disable_error_code = ["empty-body"]	empty bodies allowed	no equivalence
legacy mypy behavior	allow unused # type: ignore	unused-ignore-comment = "ignore"

Open for discussion, if I am missing something. Just wanted to clarify.

ref:

• https://docs.astral.sh/ty/reference/rules/#unresolved-import
• https://docs.astral.sh/ty/reference/rules/#possibly-missing-attribute
• Any equivalent to disable_error_code = ["empty-body"] astral-sh/ty#2544 (comment)
• https://docs.astral.sh/ty/reference/rules/#unused-ignore-comment

[romanlutz]

Note 1: There is no pre commit hook for ty as of today (2026.01.17)

"We don't plan on adding this right now because ty is still at a very early, experimental stage and we don't want to give the impression that it's ready for serious production use yet. When we're closer to feature-complete, however, we'll absolutely be adding this." - Alex Waygood

ref:

• pre-commit hook for ty astral-sh/ty#269 (comment)

Yes, I wrote that, but the purpose of this item would be to replace mypy with ty including in pre-commit.

[romanlutz]

Note 2: await outside func/async function

We are getting errors saying

• error[invalid-syntax]: *await* statement outside of a function

• error[invalid-syntax]: *await* outside of an asynchronous function

It is something under discussion there:

Interesting. What are the options we have here?

Keep it a rule

Introduce parser options (per file?)

Always allow

-- Micha Reiser

And then we got reply saying:

I don't think this is a realistic option for non-notebook files: for the vast majority of Python code this is a syntax error; we should definitely flag it by default for non-notebooks.

I'm not totally familiar with the situation for notebooks, honestly, as I've never seriously used notebooks. I can't tell you whether top-level awaits are allowed by default in notebooks or if it's only if some settings are enabled. I believe they're much more common in notebooks than in regular Python source code, however. For notebooks, we may want it to be an opt-in diagnostic rather than an opt-out diagnostic.

And even for regular Python source code, we'll want this to be at least suppressible on a per-file basis. Although it's pretty rare to use ast.PyCF_ALLOW_TOP_LEVEL_AWAIT for non-notebooks, it is possible.

I don't have strong opinions on how we make this diagnostic suppressible -- whether it stays as a linter rule or if you add per-file parser options.

-- Alex Waygood

I think it will take quite a while to get this feature.

ref:

• Allow top-level await in modules compiled with ast.PyCF_ALLOW_TOP_LEVEL_AWAIT astral-sh/ruff#17395 (comment)

• Allow top-level await in modules compiled with ast.PyCF_ALLOW_TOP_LEVEL_AWAIT astral-sh/ruff#17395 (comment)

Every py file under /doc can have await outside functions so those should be ignored there (only there!)

[maifeeulasad]

@romanlutz that is something I am working on. I will share related links soon.

I am also trying to write rules for ty, which are available in mypy but not in ty. Hope we will be able to do 1-to-1 migration.

[romanlutz]

@maifeeulasad let me know if you need any help 🙂