Log a warning message if we can detect that ty Python version doesn't match active environment Python version

[alex]

Summary

In pyca/cryptography we have code like:

if sys.version_info >= (3, 11):
    import tomllib
else:
    import tomli as tomllib

This produces errors like:

error[unresolved-import]: Cannot resolve imported module `tomli`
  --> noxfile.py:21:12
   |
19 |     import tomllib
20 | else:
21 |     import tomli as tomllib
   |            ^^^^^^^^^^^^^^^^
22 |
23 | nox.options.reuse_existing_virtualenvs = True
   |
info: Searched in the following paths during module resolution:
info:   1. /Users/alex_gaynor/projects/cryptography/src (first-party code)
info:   2. /Users/alex_gaynor/projects/cryptography (first-party code)
info:   3. vendored://stdlib (stdlib typeshed stubs vendored by ty)
info:   4. /Users/alex_gaynor/projects/cryptography/.nox/flake/lib/python3.14/site-packages (site-packages)
info:   5. /Users/alex_gaynor/projects/cryptography/vectors (editable install)
info: make sure your Python environment is properly configured: https://docs.astral.sh/ty/modules/#python-environment
info: rule `unresolved-import` is enabled by default

As far as I can tell what's happening is: ty is in a Python 3.14 venv, so tomli isn't installed. However, ty infers that it should run for Python 3.8 from my project's requires-python.

Therefore it type-checks the import tomli path and is said that the package isn't installed.

I'm not quite sure what the right behavior is, but the current behavior is perplexing and its not clear how to fix :-)

Version

ty 0.0.1-alpha.29 (0c3cae4 2025-11-28)

[AlexWaygood]

Often the solution to this kind of thing is to declare tomli as a dev-dependency, so that for type-checking it's always installed, even if it's not always installed at runtime. This is similar to the way you might specify a stubs package as a dev-dependency for type-checking purposes, even though you don't use those stubs at runtime. Mypy has this exact problem when type-checking itself, for example: https://github.com/python/mypy/blob/ad0f41eea63ef227739b66f08afbb67544597d79/test-requirements.in#L14

[alex]

I think in practice we don't see this issue on mypy because it uses the python interpreter's version, rather than the inferring it from pyproject.toml?

[AlexWaygood]

that's what mypy does by default, yes. You can specify --python-version=3.14 manually on the command line if you want to override ty's default behaviour -- but our default assumption is different to mypy's. Our default is to assume that you would like your project to type-check on the lowest version of Python your project supports, even if you're using a newer version of Python for local development.

(Note: when I mentioned mypy above, I was referring to the dependencies mypy installs in CI when it type-checks itself! It also has to declare tomli as a dev-dependency, because of similar sys.version_info branches in its own source code.)

[alex]

One note is that this changes one of the workflows we currently use, which is to run our type checking job on both our minimum python version and maximum version. For ty it seems like if we want to keep that workflow, we should have noxfile specify --python-version={sys.version}.

[AlexWaygood]

I think everything's working as expected here, and our behaviour is pretty well documented in https://docs.astral.sh/ty/reference/configuration/#python-version IMO, so I'm going to close this. I think it's also clear to see from our existing diagnostic that we're using the site-packages directory from your Python 3.14 environment (it's listed as the fourth search path where we looked for the module). I acknowledge that this behaviour might seem surprising if you're used to mypy's behaviour where it defaults to the Python version of the interpreter currently being used, but I'd argue that our behaviour makes more sense a priori -- if my Python project supports Python 3.9, I'd always want to check that my types and syntax are valid on 3.9, even if I'm using 3.14 for local development.

Attempting to figure out the Python version of the currently active environment also isn't always easy. We can do it for a virtual environment pretty well by parsing the pyvenv.cfg file, and on Unix we can look at the directory structure (we do both of these things as a fallback if --python-version wasn't specified on the CLI and there was no configuration in the pyproject.toml file!), but neither of those techniques work for Windows -- we might have to invoke the Python interpreter itself as a subprocess, which would be slow.

[AlexWaygood]

(Very happy to reopen if anybody has any specific suggestions for how to further improve our diagnostic here, but I'm struggling to see how we could in this specific case. Our diagnostic already includes a lot of information here.)

[carljm]

I think the trickiest thing here is just the fact that dependencies may vary by Python version, so there's an inherent potential mismatch whenever we type-check with a Python version that doesn't match the environment we're using. I could see a justification for logging a pre-emptive warning message (maybe only in verbose mode) if we can detect that's the case (which, as you say, we can only easily do on Unix or if we have a pyvenv.cfg).

But beyond that, ultimately we provide the necessary tools here (via an explicit-set Python version) to do whatever you need, it's just a question of picking the right defaults, and there's no one "right answer" there.