Add red_knot.Unknown

Author: sharkdp

crates/red_knot_python_semantic/resources/mdtest/type_api.md

@@ -3,7 +3,7 @@
 This document describes the internal `red_knot` API for manipulating types and querying their
 properties.
 
-## Type operations
+## Type extensions
 
 The Python language itself allows us to perform a variety of operations on types. For example, we
 can build a union of types like `int | None`, or we can use type constructors such as `list[int]` or
@@ -68,6 +68,25 @@ class D: ...
 assert_true(not is_subtype_of(ABC, D))
 ```
 
+### Unknown type
+
+The `Unknown` type is a special type that we use to represent actually unknown types (no
+annotation), as opposed to `Any` which represents an explicitly unknown type.
+
+```py
+from red_knot import Unknown, assert_true, is_assignable_to, is_fully_static
+
+assert_true(is_assignable_to(Unknown, int))
+assert_true(is_assignable_to(int, Unknown))
+
+assert_true(not is_fully_static(Unknown))
+
+x: Unknown = 1
+
+def _() -> None:
+    reveal_type(x)  # revealed: Unknown
+```
+
 ## Type predicates
 
 The `red_knot` module also provides predicates to test various properties of types. These are

crates/red_knot_python_semantic/src/types.rs

@@ -2085,6 +2085,7 @@ impl<'db> Type<'db> {
                 invalid_expressions: smallvec::smallvec![InvalidTypeExpression::BareLiteral],
                 fallback_type: Type::Unknown,
             }),
+            Type::KnownInstance(KnownInstanceType::RedKnotUnknown) => Ok(Type::Unknown),
             Type::Todo(_) => Ok(*self),
             _ => Ok(todo_type!(
                 "Unsupported or invalid type in a type expression"
@@ -2595,6 +2596,7 @@ pub enum KnownInstanceType<'db> {
     TypeIs,
     ReadOnly,
     // TODO: fill this enum out with more special forms, etc.
+    RedKnotUnknown,
 }
 
 impl<'db> KnownInstanceType<'db> {
@@ -2633,6 +2635,7 @@ impl<'db> KnownInstanceType<'db> {
             Self::ChainMap => "ChainMap",
             Self::OrderedDict => "OrderedDict",
             Self::ReadOnly => "ReadOnly",
+            Self::RedKnotUnknown => "Unknown",
         }
     }
 
@@ -2671,7 +2674,8 @@ impl<'db> KnownInstanceType<'db> {
             | Self::ChainMap
             | Self::OrderedDict
             | Self::ReadOnly
-            | Self::TypeAliasType(_) => Truthiness::AlwaysTrue,
+            | Self::TypeAliasType(_)
+            | Self::RedKnotUnknown => Truthiness::AlwaysTrue,
         }
     }
 
@@ -2711,6 +2715,7 @@ impl<'db> KnownInstanceType<'db> {
             Self::ReadOnly => "typing.ReadOnly",
             Self::TypeVar(typevar) => typevar.name(db),
             Self::TypeAliasType(_) => "typing.TypeAliasType",
+            Self::RedKnotUnknown => "red_knot.Unknown",
         }
     }
 
@@ -2750,6 +2755,7 @@ impl<'db> KnownInstanceType<'db> {
             Self::OrderedDict => KnownClass::StdlibAlias,
             Self::TypeVar(_) => KnownClass::TypeVar,
             Self::TypeAliasType(_) => KnownClass::TypeAliasType,
+            Self::RedKnotUnknown => KnownClass::Object,
         }
     }
 
@@ -2795,6 +2801,7 @@ impl<'db> KnownInstanceType<'db> {
             "Concatenate" => Self::Concatenate,
             "NotRequired" => Self::NotRequired,
             "LiteralString" => Self::LiteralString,
+            "Unknown" => Self::RedKnotUnknown,
             _ => return None,
         };
 
@@ -2844,6 +2851,7 @@ impl<'db> KnownInstanceType<'db> {
             | Self::TypeVar(_) => {
                 matches!(module, KnownModule::Typing | KnownModule::TypingExtensions)
             }
+            Self::RedKnotUnknown => matches!(module, KnownModule::RedKnot),
         }
     }
 

crates/red_knot_python_semantic/src/types/class_base.rs

@@ -93,7 +93,8 @@ impl<'db> ClassBase<'db> {
                 | KnownInstanceType::Required
                 | KnownInstanceType::TypeAlias
                 | KnownInstanceType::ReadOnly
-                | KnownInstanceType::Optional => None,
+                | KnownInstanceType::Optional
+                | KnownInstanceType::RedKnotUnknown => None,
                 KnownInstanceType::Any => Some(Self::Any),
                 // TODO: Classes inheriting from `typing.Type` et al. also have `Generic` in their MRO
                 KnownInstanceType::Dict => {

crates/red_knot_python_semantic/src/types/infer.rs

@@ -5217,7 +5217,9 @@ impl<'db> TypeInferenceBuilder<'db> {
                 );
                 Type::Unknown
             }
-            KnownInstanceType::TypingSelf | KnownInstanceType::TypeAlias => {
+            KnownInstanceType::TypingSelf
+            | KnownInstanceType::TypeAlias
+            | KnownInstanceType::RedKnotUnknown => {
                 self.context.report_lint(
                     &INVALID_TYPE_FORM,
                     subscript.into(),

crates/red_knot_vendored/vendor/typeshed/stdlib/red_knot.pyi

@@ -1,11 +1,19 @@
-from typing import TypeVarTuple
+from typing import TypeVarTuple, _SpecialForm
 
+
+# Special operations
+class TypeOf[T]: ...
+
+def assert_true(x: object) -> None: ...
+
+
+# Type extensions
 Ts = TypeVarTuple("Ts")
 
-# Operations on types
 class Not[T]: ...
 class Intersection[*Ts]: ...
-class ClassLiteral[T]: ...
+
+Unknown = object()
 
 # Predicates on types
 class _IsEquivalentTo[S, T]: ...
@@ -23,9 +31,3 @@ def is_disjoint_from[S, T](x: S, y: T) -> _IsDisjointFrom[S, T]: ...
 def is_fully_static[T](x: T) -> _IsFullyStatic[T]: ...
 def is_singleton[T](x: T) -> _IsSingleton[T]: ...
 def is_single_valued[T](x: T) -> _IsSingleValued[T]: ...
-
-
-# Special operations
-class TypeOf[T]: ...
-
-def assert_true(x: object) -> None: ...