[ty] Improve diagnostics if the user attempts to import a stdlib module that does not exist on their configured Python version

Author: AlexWaygood

crates/ruff_python_ast/src/python_version.rs

@@ -11,6 +11,7 @@ pub struct PythonVersion {
 }
 
 impl PythonVersion {
+    pub const PY30: PythonVersion = PythonVersion { major: 3, minor: 0 };
     pub const PY37: PythonVersion = PythonVersion { major: 3, minor: 7 };
     pub const PY38: PythonVersion = PythonVersion { major: 3, minor: 8 };
     pub const PY39: PythonVersion = PythonVersion { major: 3, minor: 9 };

crates/ty_python_semantic/resources/mdtest/import/basic.md

@@ -176,3 +176,29 @@ emitted for the `import from` statement:
 # error: [unresolved-import]
 from does_not_exist import foo, bar, baz
 ```
+
+## Attempting to import a stdlib module that's not yet been added
+
+<!-- snapshot-diagnostics -->
+
+```toml
+[environment]
+python-version = "3.10"
+```
+
+```py
+import tomllib
+```
+
+## Attempting to import a stdlib module that was previously removed
+
+<!-- snapshot-diagnostics -->
+
+```toml
+[environment]
+python-version = "3.13"
+```
+
+```py
+import aifc
+```

crates/ty_python_semantic/resources/mdtest/snapshots/basic.md_-_Structures_-_Attempting_to_import…_(2fcfcf567587a056).snap

@@ -0,0 +1,31 @@
+---
+source: crates/ty_test/src/lib.rs
+expression: snapshot
+---
+---
+mdtest name: basic.md - Structures - Attempting to import a stdlib module that's not yet been added
+mdtest path: crates/ty_python_semantic/resources/mdtest/import/basic.md
+---
+
+# Python source files
+
+## mdtest_snippet.py
+
+```
+1 | import tomllib
+```
+
+# Diagnostics
+
+```
+error[unresolved-import]: Cannot resolve imported module `tomllib`
+ --> src/mdtest_snippet.py:1:8
+  |
+1 | import tomllib
+  |        ^^^^^^^
+  |
+info: The stdlib module `tomllib` is only available on Python 3.11+
+info: Python 3.10 was assumed when resolving modules because it was specified on the command line
+info: rule `unresolved-import` is enabled by default
+
+```

crates/ty_python_semantic/resources/mdtest/snapshots/basic.md_-_Structures_-_Attempting_to_import…_(c14954eefd15211f).snap

@@ -0,0 +1,31 @@
+---
+source: crates/ty_test/src/lib.rs
+expression: snapshot
+---
+---
+mdtest name: basic.md - Structures - Attempting to import a stdlib module that was previously removed
+mdtest path: crates/ty_python_semantic/resources/mdtest/import/basic.md
+---
+
+# Python source files
+
+## mdtest_snippet.py
+
+```
+1 | import aifc
+```
+
+# Diagnostics
+
+```
+error[unresolved-import]: Cannot resolve imported module `aifc`
+ --> src/mdtest_snippet.py:1:8
+  |
+1 | import aifc
+  |        ^^^^
+  |
+info: The stdlib module `aifc` is only available on Python <=3.12
+info: Python 3.13 was assumed when resolving modules because it was specified on the command line
+info: rule `unresolved-import` is enabled by default
+
+```

crates/ty_python_semantic/src/module_resolver/resolver.rs

@@ -369,7 +369,7 @@ impl SearchPaths {
         })
     }
 
-    pub(super) fn typeshed_versions(&self) -> &TypeshedVersions {
+    pub(crate) fn typeshed_versions(&self) -> &TypeshedVersions {
         &self.typeshed_versions
     }
 

crates/ty_python_semantic/src/module_resolver/typeshed.rs

@@ -58,7 +58,7 @@ impl std::error::Error for TypeshedVersionsParseError {
 }
 
 #[derive(Debug, PartialEq, Eq, Clone)]
-pub(super) enum TypeshedVersionsParseErrorKind {
+pub(crate) enum TypeshedVersionsParseErrorKind {
     TooManyLines(NonZeroUsize),
     UnexpectedNumberOfColons,
     InvalidModuleName(String),
@@ -105,7 +105,7 @@ pub(crate) struct TypeshedVersions(FxHashMap<ModuleName, PyVersionRange>);
 
 impl TypeshedVersions {
     #[must_use]
-    fn exact(&self, module_name: &ModuleName) -> Option<&PyVersionRange> {
+    pub(crate) fn exact(&self, module_name: &ModuleName) -> Option<&PyVersionRange> {
         self.0.get(module_name)
     }
 
@@ -257,19 +257,43 @@ impl fmt::Display for TypeshedVersions {
 }
 
 #[derive(Debug, Clone, Eq, PartialEq, Hash)]
-enum PyVersionRange {
+pub(crate) enum PyVersionRange {
     AvailableFrom(RangeFrom<PythonVersion>),
     AvailableWithin(RangeInclusive<PythonVersion>),
 }
 
 impl PyVersionRange {
     #[must_use]
-    fn contains(&self, version: PythonVersion) -> bool {
+    pub(crate) fn contains(&self, version: PythonVersion) -> bool {
         match self {
             Self::AvailableFrom(inner) => inner.contains(&version),
             Self::AvailableWithin(inner) => inner.contains(&version),
         }
     }
+
+    pub(crate) fn diagnostic_display(&self) -> impl std::fmt::Display {
+        struct DiagnosticDisplay<'a>(&'a PyVersionRange);
+
+        impl fmt::Display for DiagnosticDisplay<'_> {
+            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+                match self.0 {
+                    PyVersionRange::AvailableFrom(range_from) => write!(f, "{}+", range_from.start),
+                    PyVersionRange::AvailableWithin(range_inclusive) => {
+                        // Don't trust the start Python version if it's 3.0 or lower.
+                        // Typeshed doesn't attempt to give accurate start versions if a module was added
+                        // in the Python 2 era.
+                        if range_inclusive.start() <= &PythonVersion::PY30 {
+                            write!(f, "<={}", range_inclusive.end())
+                        } else {
+                            write!(f, "{}-{}", range_inclusive.start(), range_inclusive.end())
+                        }
+                    }
+                }
+            }
+        }
+
+        DiagnosticDisplay(self)
+    }
 }
 
 impl FromStr for PyVersionRange {

crates/ty_python_semantic/src/types/infer.rs

@@ -3899,8 +3899,32 @@ impl<'db> TypeInferenceBuilder<'db> {
             module.unwrap_or_default()
         ));
         if level == 0 {
+            if let Some(module_name) = module.and_then(ModuleName::new) {
+                let program = Program::get(self.db());
+                let typeshed_versions = program.search_paths(self.db()).typeshed_versions();
+
+                if let Some(version_range) = typeshed_versions.exact(&module_name) {
+                    // We know it is a stdlib module on *some* Python versions...
+                    let python_version = program.python_version(self.db());
+                    if !version_range.contains(python_version) {
+                        // ...But not on *this* Python version.
+                        diagnostic.info(format_args!(
+                            "The stdlib module `{module_name}` is only available on Python {version_range}",
+                            version_range = version_range.diagnostic_display(),
+                        ));
+                        add_inferred_python_version_hint_to_diagnostic(
+                            self.db(),
+                            &mut diagnostic,
+                            "resolving modules",
+                        );
+                        return;
+                    }
+                }
+            }
+
             diagnostic.info(
-                "make sure your Python environment is properly configured: https://github.com/astral-sh/ty/blob/main/docs/README.md#python-environment"
+                "make sure your Python environment is properly configured: \
+                https://github.com/astral-sh/ty/blob/main/docs/README.md#python-environment",
             );
         }
     }