Clarify + validate python_version

[brandonchinn178]

The Python docs for python_version say:

Specifies the Python version used to parse and check the target program. The string should be in the format MAJOR.MINOR – for example 3.9. The default is the version of the Python interpreter used to run mypy.

My understanding was that you could even target a newer version of Python than the one that installed mypy, and that mypy implemented its own Python parser or something. But it seems like python_version only supports specifying older Python versions; i.e. only enables restricting syntax, not enabling syntax.

But what was even more confusing was that specifying --python-version 3.100 didn't show any errors.

I think the following changes would be good:

1. Clarify the documentation to say that python_version is upper bounded to the version of Python running mypy
2. Error if python_version is greater than the version of Python running mypy

[cdce8p]

At the moment, Mypy still relies on the cpython parser. Thus new typing syntax (like PEP 695) is generally only available once support for all older Python versions is dropped.

However as I understand it, the --python-version flag is mainly intended for sys.version_info guards. Those work regardless. E.g. while running myoy with Python 3.9, you could still use --python-version 3.14 to type check if sys.version_info >= (3, 14) guards. Mypy will also use it to emit errors for syntax which isn't supported yet, i.e. while running mypy with 3.14 and using --python-version 3.9 should emit errors for PEP 695 syntax.

My general recommendation is to run mypy itself with the latest (by your project) supported Python version and then use --python-version to specific the lowest supported version.

[brandonchinn178]

Mypy still relies on the cpython parser

E.g. while running myoy with Python 3.9, you could still use --python-version 3.14 to type check if sys.version_info >= (3, 14) guards

These two statements are at odds with each other. Because mypy is using the CPython parser that's running mypy, it cannot even attempt to parse newer Python syntax, even if it's hidden behind a guard.

$ python3.9 -m venv venv
$ venv/bin/pip install mypy

$ cat test.py
import sys
if sys.version_info >= (3, 11):
    def foo[T](x: T) -> T:
        return x

$ venv/bin/mypy test.py
test.py:3: error: Invalid syntax  [syntax]

$ venv/bin/mypy test.py --python-version 3.14
test.py:3: error: Invalid syntax; you likely need to run mypy using Python 3.14 or newer  [syntax]

There is almost no benefit to running mypy with a version newer than the version of Python that's running it, so we might as well error immediately on any newer version. It would also allow us to provide slightly more sensical error messages than this slightly confusing error message:

$ venv/bin/mypy test.py --python-version 3.100
test.py:3: error: Invalid syntax; you likely need to run mypy using Python 3.100 or newer  [syntax]

My general recommendation is to run mypy itself with the latest (by your project) supported Python version and then use --python-version to specific the lowest supported version.

Yes, I understand that that's the general workflow - run mypy on the latest Python version possible and restrict backwards with --python-version. What I'm saying here is that that's not obvious from the docs, which has no restrictions on whether --python-version can be used for newer versions.

[cdce8p]

Mypy still relies on the cpython parser
E.g. while running myoy with Python 3.9, you could still use --python-version 3.14 to type check if sys.version_info >= (3, 14) guards

These two statements are at odds with each other. Because mypy is using the CPython parser that's running mypy, it cannot even attempt to parse newer Python syntax, even if it's hidden behind a guard.

As I've said: "Thus new typing syntax (like PEP 695) is generally only available once support for all older Python versions is dropped.". Your example isn't how if sys.version_info guards are used though. Just take a look at typeshed
https://github.com/search?q=repo%3Apython%2Ftypeshed+%22if+sys.version_info%22&type=code

There is almost no benefit to running mypy with a version newer than the version of Python that's running it, so we might as well error immediately on any newer version.

Typeshed uses that each year for the time stubs for a new Python version are added until mypy actually supports that one.

Yes, I understand that that's the general workflow - run mypy on the latest Python version possible and restrict backwards with --python-version. What I'm saying here is that that's not obvious from the docs, which has no restrictions on whether --python-version can be used for newer versions.

Yes it has no restriction and I don't think that should be changed. IMO the most that should be done here is maybe add a note to the documentation.

[A5rocks]

I think this issue isn't a good solution to the problem. Libraries need to support all Python parsers, but can gate imports behind version checks -- this is exactly the same use case as mypy!

I would love it if mypy had a nicer parser and could in fact ship grammars for whatever versions it wants. I also think that's unlikely ATM. But I think that's the better solution that is an improvement on all fronts. (we can probably assume having a grammar == having typeshed support, so it doesn't make sense to parse for an unsupported grammar.)