astral-sh
diff --git a/‎crates/red_knot_python_semantic/src/module_resolver/module.rs‎
Lines changed: 8 additions & 3 deletions b/‎crates/red_knot_python_semantic/src/module_resolver/module.rs‎
Lines changed: 8 additions & 3 deletions
diff --git a/‎crates/red_knot_python_semantic/src/types.rs‎
Lines changed: 34 additions & 43 deletions b/‎crates/red_knot_python_semantic/src/types.rs‎
Lines changed: 34 additions & 43 deletions
diff --git a/‎crates/red_knot_python_semantic/src/types/class.rs‎
Lines changed: 160 additions & 12 deletions b/‎crates/red_knot_python_semantic/src/types/class.rs‎
Lines changed: 160 additions & 12 deletions
@@ -134,9 +134,8 @@ impl KnownModule {
     }
 
     pub fn name(self) -> ModuleName {
-        let self_as_str = self.as_str();
-        ModuleName::new_static(self_as_str)
-            .unwrap_or_else(|| panic!("{self_as_str} should be a valid module name!"))
+        ModuleName::new_static(self.as_str())
+            .unwrap_or_else(|| panic!("{self} should be a valid module name!"))
     }
 
     pub(crate) fn try_from_search_path_and_name(
@@ -167,6 +166,12 @@ impl KnownModule {
     }
 }
 
+impl std::fmt::Display for KnownModule {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
 
@@ -730,10 +730,9 @@ impl<'db> Type<'db> {
             // `Literal[str]` is a subtype of `type` because the `str` class object is an instance of its metaclass `type`.
             // `Literal[abc.ABC]` is a subtype of `abc.ABCMeta` because the `abc.ABC` class object
             // is an instance of its metaclass `abc.ABCMeta`.
-            (Type::ClassLiteral(ClassLiteralType { class }), _) => class
-                .metaclass(db)
-                .to_instance(db)
-                .is_subtype_of(db, target),
+            (Type::ClassLiteral(ClassLiteralType { class }), _) => {
+                class.metaclass_instance_type(db).is_subtype_of(db, target)
+            }
 
             // `type[str]` (== `SubclassOf("str")` in red-knot) describes all possible runtime subclasses
             // of the class object `str`. It is a subtype of `type` (== `Instance("type")`) because `str`
@@ -745,11 +744,9 @@ impl<'db> Type<'db> {
             (Type::SubclassOf(subclass_of_ty), _) => subclass_of_ty
                 .subclass_of()
                 .into_class()
-                .is_some_and(|class| {
-                    class
-                        .metaclass(db)
-                        .to_instance(db)
-                        .is_subtype_of(db, target)
+                .map(|class| class.metaclass_instance_type(db))
+                .is_some_and(|metaclass_instance_type| {
+                    metaclass_instance_type.is_subtype_of(db, target)
                 }),
 
             // For example: `Type::KnownInstance(KnownInstanceType::Type)` is a subtype of `Type::Instance(_SpecialForm)`,
@@ -1122,16 +1119,17 @@ impl<'db> Type<'db> {
                 ty.bool(db).is_always_true()
             }
 
+            // for `type[Any]`/`type[Unknown]`/`type[Todo]`, we know the type cannot be any larger than `type`,
+            // so although the type is dynamic we can still determine disjointness in some situations
             (Type::SubclassOf(subclass_of_ty), other)
-            | (other, Type::SubclassOf(subclass_of_ty)) => {
-                let metaclass_instance_ty = match subclass_of_ty.subclass_of() {
-                    // for `type[Any]`/`type[Unknown]`/`type[Todo]`, we know the type cannot be any larger than `type`,
-                    // so although the type is dynamic we can still determine disjointness in some situations
-                    ClassBase::Dynamic(_) => KnownClass::Type.to_instance(db),
-                    ClassBase::Class(class) => class.metaclass(db).to_instance(db),
-                };
-                other.is_disjoint_from(db, metaclass_instance_ty)
-            }
+            | (other, Type::SubclassOf(subclass_of_ty)) => match subclass_of_ty.subclass_of() {
+                ClassBase::Dynamic(_) => {
+                    KnownClass::Type.to_instance(db).is_disjoint_from(db, other)
+                }
+                ClassBase::Class(class) => class
+                    .metaclass_instance_type(db)
+                    .is_disjoint_from(db, other),
+            },
 
             (Type::KnownInstance(known_instance), Type::Instance(InstanceType { class }))
             | (Type::Instance(InstanceType { class }), Type::KnownInstance(known_instance)) => {
@@ -1200,8 +1198,7 @@ impl<'db> Type<'db> {
             (Type::ClassLiteral(ClassLiteralType { class }), instance @ Type::Instance(_))
             | (instance @ Type::Instance(_), Type::ClassLiteral(ClassLiteralType { class })) => {
                 !class
-                    .metaclass(db)
-                    .to_instance(db)
+                    .metaclass_instance_type(db)
                     .is_subtype_of(db, instance)
             }
 
@@ -2106,19 +2103,13 @@ impl<'db> Type<'db> {
             Type::FunctionLiteral(_) => Truthiness::AlwaysTrue,
             Type::Callable(_) => Truthiness::AlwaysTrue,
             Type::ModuleLiteral(_) => Truthiness::AlwaysTrue,
-            Type::ClassLiteral(ClassLiteralType { class }) => {
-                return class
-                    .metaclass(db)
-                    .to_instance(db)
-                    .try_bool_impl(db, allow_short_circuit);
-            }
+            Type::ClassLiteral(ClassLiteralType { class }) => class
+                .metaclass_instance_type(db)
+                .try_bool_impl(db, allow_short_circuit)?,
             Type::SubclassOf(subclass_of_ty) => match subclass_of_ty.subclass_of() {
                 ClassBase::Dynamic(_) => Truthiness::Ambiguous,
                 ClassBase::Class(class) => {
-                    return class
-                        .metaclass(db)
-                        .to_instance(db)
-                        .try_bool_impl(db, allow_short_circuit);
+                    Type::class_literal(class).try_bool_impl(db, allow_short_circuit)?
                 }
             },
             Type::AlwaysTruthy => Truthiness::AlwaysTrue,
@@ -2948,19 +2939,19 @@ impl<'db> Type<'db> {
     }
 
     #[must_use]
-    pub fn to_instance(&self, db: &'db dyn Db) -> Type<'db> {
+    pub fn to_instance(&self, db: &'db dyn Db) -> Option<Type<'db>> {
         match self {
-            Type::Dynamic(_) => *self,
-            Type::Never => Type::Never,
-            Type::ClassLiteral(ClassLiteralType { class }) => Type::instance(*class),
-            Type::SubclassOf(subclass_of_ty) => match subclass_of_ty.subclass_of() {
-                ClassBase::Class(class) => Type::instance(class),
-                ClassBase::Dynamic(dynamic) => Type::Dynamic(dynamic),
-            },
-            Type::Union(union) => union.map(db, |element| element.to_instance(db)),
-            Type::Intersection(_) => todo_type!("Type::Intersection.to_instance()"),
-            // TODO: calling `.to_instance()` on any of these should result in a diagnostic,
-            // since they already indicate that the object is an instance of some kind:
+            Type::Dynamic(_) | Type::Never => Some(*self),
+            Type::ClassLiteral(ClassLiteralType { class }) => Some(Type::instance(*class)),
+            Type::SubclassOf(subclass_of_ty) => Some(subclass_of_ty.to_instance()),
+            Type::Union(union) => {
+                let mut builder = UnionBuilder::new(db);
+                for element in union.elements(db) {
+                    builder = builder.add(element.to_instance(db)?);
+                }
+                Some(builder.build())
+            }
+            Type::Intersection(_) => Some(todo_type!("Type::Intersection.to_instance()")),
             Type::BooleanLiteral(_)
             | Type::BytesLiteral(_)
             | Type::FunctionLiteral(_)
@@ -2974,7 +2965,7 @@ impl<'db> Type<'db> {
             | Type::Tuple(_)
             | Type::LiteralString
             | Type::AlwaysTruthy
-            | Type::AlwaysFalsy => Type::unknown(),
+            | Type::AlwaysFalsy => None,
         }
     }
 
 
@@ -1,3 +1,5 @@
+use std::sync::{LazyLock, Mutex};
+
 use crate::{
     module_resolver::file_to_module,
     semantic_index::{
@@ -18,6 +20,7 @@ use indexmap::IndexSet;
 use itertools::Itertools as _;
 use ruff_db::files::File;
 use ruff_python_ast::{self as ast, PythonVersion};
+use rustc_hash::FxHashSet;
 
 use super::{
     class_base::ClassBase, infer_expression_type, infer_unpack_types, IntersectionBuilder,
@@ -185,6 +188,14 @@ impl<'db> Class<'db> {
             .unwrap_or_else(|_| SubclassOfType::subclass_of_unknown())
     }
 
+    /// Return a type representing "the set of all instances of the metaclass of this class".
+    pub(super) fn metaclass_instance_type(self, db: &'db dyn Db) -> Type<'db> {
+        self
+            .metaclass(db)
+            .to_instance(db)
+            .expect("`Type::to_instance()` should always return `Some()` when called on the type of a metaclass")
+    }
+
     /// Return the metaclass of this class, or an error if the metaclass cannot be inferred.
     #[salsa::tracked]
     pub(super) fn try_metaclass(self, db: &'db dyn Db) -> Result<Type<'db>, MetaclassError<'db>> {
@@ -879,7 +890,7 @@ impl<'db> KnownClass {
         }
     }
 
-    pub(crate) fn as_str(self, db: &'db dyn Db) -> &'static str {
+    pub(crate) fn name(self, db: &'db dyn Db) -> &'static str {
         match self {
             Self::Bool => "bool",
             Self::Object => "object",
@@ -937,17 +948,101 @@ impl<'db> KnownClass {
         }
     }
 
+    fn display(self, db: &'db dyn Db) -> impl std::fmt::Display + 'db {
+        struct KnownClassDisplay<'db> {
+            db: &'db dyn Db,
+            class: KnownClass,
+        }
+
+        impl std::fmt::Display for KnownClassDisplay<'_> {
+            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+                let KnownClassDisplay {
+                    class: known_class,
+                    db,
+                } = *self;
+                write!(
+                    f,
+                    "{module}.{class}",
+                    module = known_class.canonical_module(db),
+                    class = known_class.name(db)
+                )
+            }
+        }
+
+        KnownClassDisplay { db, class: self }
+    }
+
+    /// Lookup a [`KnownClass`] in typeshed and return a [`Type`]
+    /// representing all possible instances of the class.
+    ///
+    /// If the class cannot be found in typeshed, a debug-level log message will be emitted stating this.
     pub(crate) fn to_instance(self, db: &'db dyn Db) -> Type<'db> {
-        self.to_class_literal(db).to_instance(db)
+        self.to_class_literal(db)
+            .into_class_literal()
+            .map(|ClassLiteralType { class }| Type::instance(class))
+            .unwrap_or_else(Type::unknown)
     }
 
+    /// Attempt to lookup a [`KnownClass`] in typeshed and return a [`Type`] representing that class-literal.
+    ///
+    /// Return an error if the symbol cannot be found in the expected typeshed module,
+    /// or if the symbol is not a class definition, or if the symbol is possibly unbound.
+    pub(crate) fn try_to_class_literal(
+        self,
+        db: &'db dyn Db,
+    ) -> Result<ClassLiteralType<'db>, KnownClassLookupError<'db>> {
+        let symbol = known_module_symbol(db, self.canonical_module(db), self.name(db)).symbol;
+        match symbol {
+            Symbol::Type(Type::ClassLiteral(class_type), Boundness::Bound) => Ok(class_type),
+            Symbol::Type(Type::ClassLiteral(class_type), Boundness::PossiblyUnbound) => {
+                Err(KnownClassLookupError::ClassPossiblyUnbound { class_type })
+            }
+            Symbol::Type(found_type, _) => {
+                Err(KnownClassLookupError::SymbolNotAClass { found_type })
+            }
+            Symbol::Unbound => Err(KnownClassLookupError::ClassNotFound),
+        }
+    }
+
+    /// Lookup a [`KnownClass`] in typeshed and return a [`Type`] representing that class-literal.
+    ///
+    /// If the class cannot be found in typeshed, a debug-level log message will be emitted stating this.
     pub(crate) fn to_class_literal(self, db: &'db dyn Db) -> Type<'db> {
-        known_module_symbol(db, self.canonical_module(db), self.as_str(db))
-            .symbol
-            .ignore_possibly_unbound()
-            .unwrap_or(Type::unknown())
+        // a cache of the `KnownClass`es that we have already failed to lookup in typeshed
+        // (and therefore that we've already logged a warning for)
+        static MESSAGES: LazyLock<Mutex<FxHashSet<KnownClass>>> = LazyLock::new(Mutex::default);
+
+        self.try_to_class_literal(db)
+            .map(Type::ClassLiteral)
+            .unwrap_or_else(|lookup_error| {
+                if MESSAGES.lock().unwrap().insert(self) {
+                    if matches!(
+                        lookup_error,
+                        KnownClassLookupError::ClassPossiblyUnbound { .. }
+                    ) {
+                        tracing::info!("{}", lookup_error.display(db, self));
+                    } else {
+                        tracing::info!(
+                            "{}. Falling back to `Unknown` for the symbol instead.",
+                            lookup_error.display(db, self)
+                        );
+                    }
+                }
+
+                match lookup_error {
+                    KnownClassLookupError::ClassPossiblyUnbound { class_type, .. } => {
+                        Type::class_literal(class_type.class)
+                    }
+                    KnownClassLookupError::ClassNotFound { .. }
+                    | KnownClassLookupError::SymbolNotAClass { .. } => Type::unknown(),
+                }
+            })
     }
 
+    /// Lookup a [`KnownClass`] in typeshed and return a [`Type`]
+    /// representing that class and all possible subclasses of the class.
+    ///
+    /// If the class cannot be found in typeshed, a debug-level log message will be emitted stating this.
     pub(crate) fn to_subclass_of(self, db: &'db dyn Db) -> Type<'db> {
         self.to_class_literal(db)
             .into_class_literal()
@@ -958,11 +1053,8 @@ impl<'db> KnownClass {
     /// Return `true` if this symbol can be resolved to a class definition `class` in typeshed,
     /// *and* `class` is a subclass of `other`.
     pub(super) fn is_subclass_of(self, db: &'db dyn Db, other: Class<'db>) -> bool {
-        known_module_symbol(db, self.canonical_module(db), self.as_str(db))
-            .symbol
-            .ignore_possibly_unbound()
-            .and_then(Type::into_class_literal)
-            .is_some_and(|ClassLiteralType { class }| class.is_subclass_of(db, other))
+        self.try_to_class_literal(db)
+            .is_ok_and(|ClassLiteralType { class }| class.is_subclass_of(db, other))
     }
 
     /// Return the module in which we should look up the definition for this class
@@ -1227,6 +1319,62 @@ impl<'db> KnownClass {
     }
 }
 
+/// Enumeration of ways in which looking up a [`KnownClass`] in typeshed could fail.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum KnownClassLookupError<'db> {
+    /// There is no symbol by that name in the expected typeshed module.
+    ClassNotFound,
+    /// There is a symbol by that name in the expected typeshed module,
+    /// but it's not a class.
+    SymbolNotAClass { found_type: Type<'db> },
+    /// There is a symbol by that name in the expected typeshed module,
+    /// and it's a class definition, but it's possibly unbound.
+    ClassPossiblyUnbound { class_type: ClassLiteralType<'db> },
+}
+
+impl<'db> KnownClassLookupError<'db> {
+    fn display(&self, db: &'db dyn Db, class: KnownClass) -> impl std::fmt::Display + 'db {
+        struct ErrorDisplay<'db> {
+            db: &'db dyn Db,
+            class: KnownClass,
+            error: KnownClassLookupError<'db>,
+        }
+
+        impl std::fmt::Display for ErrorDisplay<'_> {
+            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+                let ErrorDisplay { db, class, error } = *self;
+
+                let class = class.display(db);
+                let python_version = Program::get(db).python_version(db);
+
+                match error {
+                    KnownClassLookupError::ClassNotFound => write!(
+                        f,
+                        "Could not find class `{class}` in typeshed on Python {python_version}",
+                    ),
+                    KnownClassLookupError::SymbolNotAClass { found_type } => write!(
+                        f,
+                        "Error looking up `{class}` in typeshed: expected to find a class definition \
+                        on Python {python_version}, but found a symbol of type `{found_type}` instead",
+                        found_type = found_type.display(db),
+                    ),
+                    KnownClassLookupError::ClassPossiblyUnbound { .. } => write!(
+                        f,
+                        "Error looking up `{class}` in typeshed on Python {python_version}: \
+                        expected to find a fully bound symbol, but found one that is possibly unbound",
+                    )
+                }
+            }
+        }
+
+        ErrorDisplay {
+            db,
+            class,
+            error: *self,
+        }
+    }
+}
+
 /// Enumeration of specific runtime that are special enough to be considered their own type.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, salsa::Update)]
 pub enum KnownInstanceType<'db> {
@@ -1609,7 +1757,7 @@ mod tests {
     fn known_class_roundtrip_from_str() {
         let db = setup_db();
         for class in KnownClass::iter() {
-            let class_name = class.as_str(&db);
+            let class_name = class.name(&db);
             let class_module = resolve_module(&db, &class.canonical_module(&db).name()).unwrap();
 
             assert_eq!(
Original file line number	Diff line number	Diff line change
`@@ -134,9 +134,8 @@ impl KnownModule {`
`134`	`134`	`}`
`135`	`135`
`136`	`136`	`pub fn name(self) -> ModuleName {`
`137`		`- let self_as_str = self.as_str();`
`138`		`- ModuleName::new_static(self_as_str)`
`139`		`- .unwrap_or_else(\|\| panic!("{self_as_str} should be a valid module name!"))`
	`137`	`+ ModuleName::new_static(self.as_str())`
	`138`	`+ .unwrap_or_else(\|\| panic!("{self} should be a valid module name!"))`
`140`	`139`	`}`
`141`	`140`
`142`	`141`	`pub(crate) fn try_from_search_path_and_name(`
`@@ -167,6 +166,12 @@ impl KnownModule {`
`167`	`166`	`}`
`168`	`167`	`}`
`169`	`168`
	`169`	`+impl std::fmt::Display for KnownModule {`
	`170`	`+ fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {`
	`171`	`+ f.write_str(self.as_str())`
	`172`	`+ }`
	`173`	`+}`
	`174`	`+`
`170`	`175`	`#[cfg(test)]`
`171`	`176`	`mod tests {`
`172`	`177`	`use super::*;`