add version hint for failed stdlib accesses

Author: Gankra

crates/ty/docs/rules.md

@@ -26,7 +26,7 @@ fn config_override_python_version() -> anyhow::Result<()> {
         ),
     ])?;
 
-    assert_cmd_snapshot!(case.command(), @r###"
+    assert_cmd_snapshot!(case.command(), @r#"
     success: false
     exit_code: 1
     ----- stdout -----
@@ -37,12 +37,19 @@ fn config_override_python_version() -> anyhow::Result<()> {
     5 | print(sys.last_exc)
       |       ^^^^^^^^^^^^
       |
+    info: Python 3.11 was assumed when accessing `last_exc`
+     --> pyproject.toml:3:18
+      |
+    2 | [tool.ty.environment]
+    3 | python-version = "3.11"
+      |                  ^^^^^^ Python 3.11 assumed due to this configuration setting
+      |
     info: rule `unresolved-attribute` is enabled by default
 
     Found 1 diagnostic
 
     ----- stderr -----
-    "###);
+    "#);
 
     assert_cmd_snapshot!(case.command().arg("--python-version").arg("3.12"), @r###"
     success: true
@@ -951,7 +958,7 @@ fn defaults_to_a_new_python_version() -> anyhow::Result<()> {
         ),
     ])?;
 
-    assert_cmd_snapshot!(case.command(), @r###"
+    assert_cmd_snapshot!(case.command(), @r#"
     success: false
     exit_code: 1
     ----- stdout -----
@@ -963,12 +970,20 @@ fn defaults_to_a_new_python_version() -> anyhow::Result<()> {
     4 | os.grantpt(1) # only available on unix, Python 3.13 or newer
       | ^^^^^^^^^^
       |
+    info: Python 3.10 was assumed when accessing `grantpt`
+     --> ty.toml:3:18
+      |
+    2 | [environment]
+    3 | python-version = "3.10"
+      |                  ^^^^^^ Python 3.10 assumed due to this configuration setting
+    4 | python-platform = "linux"
+      |
     info: rule `unresolved-attribute` is enabled by default
 
     Found 1 diagnostic
 
     ----- stderr -----
-    "###);
+    "#);
 
     // Use default (which should be latest supported)
     let case = CliTest::with_files([

crates/ty/tests/cli/python_environment.rs

@@ -2558,6 +2558,28 @@ class C:
 reveal_type(C().x)  # revealed: Unknown | tuple[Divergent, Literal[1]]
 ```
 
+## Attributes of standard library modules that aren't yet defined
+
+For attributes of stdlib modules that exist in future versions, we can give better diagnostics.
+
+<!-- snapshot-diagnostics -->
+
+```toml
+[environment]
+python-version = "3.10"
+```
+
+`main.py`:
+
+```py
+import datetime
+
+# error: [unresolved-attribute]
+reveal_type(datetime.UTC)  # revealed: Unknown
+# error: [unresolved-attribute]
+reveal_type(datetime.fakenotreal)  # revealed: Unknown
+```
+
 ## References
 
 Some of the tests in the *Class and instance variables* section draw inspiration from

crates/ty_python_semantic/resources/mdtest/attributes.md

@@ -0,0 +1,51 @@
+---
+source: crates/ty_test/src/lib.rs
+expression: snapshot
+---
+---
+mdtest name: attributes.md - Attributes - Attributes of standard library modules that aren't yet defined
+mdtest path: crates/ty_python_semantic/resources/mdtest/attributes.md
+---
+
+# Python source files
+
+## main.py
+
+```
+1 | import datetime
+2 | 
+3 | # error: [unresolved-attribute]
+4 | reveal_type(datetime.UTC)  # revealed: Unknown
+5 | # error: [unresolved-attribute]
+6 | reveal_type(datetime.fakenotreal)  # revealed: Unknown
+```
+
+# Diagnostics
+
+```
+error[unresolved-attribute]: Type `<module 'datetime'>` has no attribute `UTC`
+ --> src/main.py:4:13
+  |
+3 | # error: [unresolved-attribute]
+4 | reveal_type(datetime.UTC)  # revealed: Unknown
+  |             ^^^^^^^^^^^^
+5 | # error: [unresolved-attribute]
+6 | reveal_type(datetime.fakenotreal)  # revealed: Unknown
+  |
+info: Python 3.10 was assumed when accessing `UTC` because it was specified on the command line
+info: rule `unresolved-attribute` is enabled by default
+
+```
+
+```
+error[unresolved-attribute]: Type `<module 'datetime'>` has no attribute `fakenotreal`
+ --> src/main.py:6:13
+  |
+4 | reveal_type(datetime.UTC)  # revealed: Unknown
+5 | # error: [unresolved-attribute]
+6 | reveal_type(datetime.fakenotreal)  # revealed: Unknown
+  |             ^^^^^^^^^^^^^^^^^^^^
+  |
+info: rule `unresolved-attribute` is enabled by default
+
+```

crates/ty_python_semantic/resources/mdtest/snapshots/attributes.md_-_Attributes_-_Attributes_of_standa…_(49ba2c9016d64653).snap

@@ -181,7 +181,8 @@ impl PlaceTable {
     }
 
     /// Looks up a symbol by its name and returns a reference to it, if it exists.
-    #[cfg(test)]
+    ///
+    /// This should only be used in diagnostics and tests.
     pub(crate) fn symbol_by_name(&self, name: &str) -> Option<&Symbol> {
         self.symbols.symbol_id(name).map(|id| self.symbol(id))
     }

crates/ty_python_semantic/src/semantic_index/place.rs

@@ -8,6 +8,7 @@ use super::{
 use crate::lint::{Level, LintRegistryBuilder, LintStatus};
 use crate::semantic_index::definition::{Definition, DefinitionKind};
 use crate::semantic_index::place::{PlaceTable, ScopedPlaceId};
+use crate::semantic_index::{global_scope, place_table};
 use crate::suppression::FileSuppressionId;
 use crate::types::call::CallError;
 use crate::types::class::{DisjointBase, DisjointBaseKind, Field};
@@ -29,7 +30,7 @@ use crate::{
 use itertools::Itertools;
 use ruff_db::diagnostic::{Annotation, Diagnostic, Span, SubDiagnostic, SubDiagnosticSeverity};
 use ruff_python_ast::name::Name;
-use ruff_python_ast::{self as ast, AnyNodeRef};
+use ruff_python_ast::{self as ast, AnyNodeRef, Identifier};
 use ruff_text_size::{Ranged, TextRange};
 use rustc_hash::FxHashSet;
 use std::fmt::Formatter;
@@ -3140,6 +3141,50 @@ pub(super) fn hint_if_stdlib_submodule_exists_on_other_versions(
     add_inferred_python_version_hint_to_diagnostic(db, &mut diagnostic, "resolving modules");
 }
 
+/// This function receives an unresolved `foo.bar` attribute access,
+/// where `foo` can be resolved to have a type but that type does not
+/// have a `bar` attribute.
+///
+/// If the type of `foo` has a definition that originates in the
+/// standard library and `foo.bar` *does* exist as an attribute on *other*
+/// Python versions, we add a hint to the diagnostic that the user may have
+/// misconfigured their Python version.
+pub(super) fn hint_if_stdlib_attribute_exists_on_other_versions(
+    db: &dyn Db,
+    mut diagnostic: LintDiagnosticGuard,
+    value_type: &Type,
+    attr: &Identifier,
+) {
+    // Currently we limit this analysis to attributes of stdlib modules,
+    // as this covers the most important cases while not being too noisy
+    // about basic typos or special types like `super(C, self)`
+    let Type::ModuleLiteral(module_ty) = value_type else {
+        return;
+    };
+    let module = module_ty.module(db);
+    let Some(file) = module.file(db) else {
+        return;
+    };
+    // Must be a stdlib module
+    let Some(search_path) = module.search_path(db) else {
+        return;
+    };
+    if !search_path.is_standard_library() {
+        return;
+    }
+    // We must be aware that this is a real symbol on *some* version
+    let symbol_table = place_table(db, global_scope(db, file));
+    if symbol_table.symbol_by_name(attr).is_none() {
+        return;
+    }
+
+    add_inferred_python_version_hint_to_diagnostic(
+        db,
+        &mut diagnostic,
+        &format!("accessing `{}`", attr.id),
+    );
+}
+
 /// Suggest a name from `existing_names` that is similar to `wrong_name`.
 fn did_you_mean<S: AsRef<str>, T: AsRef<str>>(
     existing_names: impl Iterator<Item = S>,

crates/ty_python_semantic/src/types/diagnostic.rs

@@ -59,6 +59,7 @@ use crate::types::diagnostic::{
     IncompatibleBases, NON_SUBSCRIPTABLE, POSSIBLY_MISSING_IMPLICIT_CALL, POSSIBLY_MISSING_IMPORT,
     SUBCLASS_OF_FINAL_CLASS, UNDEFINED_REVEAL, UNRESOLVED_ATTRIBUTE, UNRESOLVED_GLOBAL,
     UNRESOLVED_IMPORT, UNRESOLVED_REFERENCE, UNSUPPORTED_OPERATOR, USELESS_OVERLOAD_BODY,
+    hint_if_stdlib_attribute_exists_on_other_versions,
     hint_if_stdlib_submodule_exists_on_other_versions, report_attempted_protocol_instantiation,
     report_bad_dunder_set_call, report_cannot_pop_required_field_on_typed_dict,
     report_duplicate_bases, report_implicit_return_type, report_index_out_of_bounds,
@@ -7497,13 +7498,14 @@ impl<'db, 'ast> TypeInferenceBuilder<'db, 'ast> {
                                 ),
                             );
                         } else {
-                            builder.into_diagnostic(
+                            let diagnostic = builder.into_diagnostic(
                                 format_args!(
                                     "Type `{}` has no attribute `{}`",
                                     value_type.display(db),
                                     attr.id
                                 ),
                             );
+                            hint_if_stdlib_attribute_exists_on_other_versions(db, diagnostic, &value_type, attr);
                         }
                         }
                     }