[ty] Add version hint for failed stdlib attribute accesses (#20909)

This is the ultra-minimal implementation of

* astral-sh/ty#296

that was previously discussed as a good starting point. In particular we
don't actually bother trying to figure out the exact python versions,
but we still mention "hey btw for No Reason At All... you're on python
3.10" when you try to access something that has a definition rooted in
the stdlib that we believe exists sometimes.

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,56 @@ 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;
+    };
+    let Some(search_path) = module.search_path(db) else {
+        return;
+    };
+    if !search_path.is_standard_library() {
+        return;
+    }
+
+    // We populate place_table entries for stdlib items across all known versions and platforms,
+    // so if this lookup succeeds then we know that this lookup *could* succeed with possible
+    // configuration changes.
+    let symbol_table = place_table(db, global_scope(db, file));
+    if symbol_table.symbol_by_name(attr).is_none() {
+        return;
+    }
+
+    // For now, we just mention the current version they're on, and hope that's enough of a nudge.
+    // TODO: determine what version they need to be on
+    // TODO: also mention the platform we're assuming
+    // TODO: determine what platform they need to be on
+    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);
                         }
                         }
                     }