[ty] Add support for sentinels (PEP 661)

crates/ty_python_semantic/resources/mdtest/sentinels.md

@@ -0,0 +1,145 @@
+# Sentinels
+
+## `typing_extensions.Sentinel`
+
+Sentinels constructed with `typing_extensions.Sentinel` can be used directly in type expressions:
+
+```py
+from typing_extensions import Sentinel, assert_type
+
+MISSING = Sentinel("MISSING")
+OTHER = Sentinel("OTHER")
+WITH_REPR = Sentinel("WITH_REPR", "<with repr>")
+WITH_REPR_KEYWORD = Sentinel("WITH_REPR_KEYWORD", repr="<with repr keyword>")
+
+reveal_type(MISSING)  # revealed: MISSING
+reveal_type(OTHER)  # revealed: OTHER
+reveal_type(WITH_REPR)  # revealed: WITH_REPR
+reveal_type(WITH_REPR_KEYWORD)  # revealed: WITH_REPR_KEYWORD
+
+def accepts_missing(x: MISSING) -> None: ...
+def accepts_other(x: OTHER) -> None: ...
+
+accepts_missing(MISSING)
+accepts_missing(OTHER)  # error: [invalid-argument-type]
+accepts_other(OTHER)
+accepts_other(MISSING)  # error: [invalid-argument-type]
+
+def bad_default(x: int = MISSING) -> None:  # error: [invalid-parameter-default]
+    pass
+
+def good_default(x: int | MISSING | OTHER = MISSING) -> None:
+    if x is MISSING:
+        assert_type(x, MISSING)
+        reveal_type(x)  # revealed: MISSING
+    else:
+        assert_type(x, int | OTHER)
+        reveal_type(x)  # revealed: int | OTHER
+
+good_default(1)
+good_default(MISSING)
+good_default(OTHER)
+
+def reverse_check(x: int | MISSING | OTHER) -> None:
+    if MISSING is x:
+        assert_type(x, MISSING)
+        reveal_type(x)  # revealed: MISSING
+    else:
+        assert_type(x, int | OTHER)
+        reveal_type(x)  # revealed: int | OTHER
+
+def negative_check(x: int | MISSING | OTHER) -> None:
+    if x is not MISSING:
+        assert_type(x, int | OTHER)
+        reveal_type(x)  # revealed: int | OTHER
+    else:
+        assert_type(x, MISSING)
+        reveal_type(x)  # revealed: MISSING
+
+def reverse_negative_check(x: int | MISSING | OTHER) -> None:
+    if MISSING is not x:
+        assert_type(x, int | OTHER)
+        reveal_type(x)  # revealed: int | OTHER
+    else:
+        assert_type(x, MISSING)
+        reveal_type(x)  # revealed: MISSING
+```
+
+Sentinel objects are always truthy, expose the standard sentinel metadata attributes, and are
+rejected as class bases:
+
+```py
+from typing_extensions import Sentinel
+
+MISSING = Sentinel("MISSING")
+
+reveal_type(bool(MISSING))  # revealed: Literal[True]
+reveal_type(MISSING.__module__)  # revealed: str
+
+class MissingSubclass(MISSING):  # error: [invalid-base]
+    pass
+```
+
+Sentinels declared in class scope can also be used in type expressions:
+
+```py
+from typing_extensions import Sentinel, assert_type
+
+class C:
+    MARKER = Sentinel("C.MARKER")
+
+def accepts_marker(x: C.MARKER) -> None: ...
+
+accepts_marker(C.MARKER)
+
+def class_default(x: int | C.MARKER = C.MARKER) -> None:
+    if x is C.MARKER:
+        assert_type(x, C.MARKER)
+        reveal_type(x)  # revealed: MARKER
+    else:
+        assert_type(x, int)
+        reveal_type(x)  # revealed: int
+
+def class_reverse_negative(x: int | C.MARKER) -> None:
+    if C.MARKER is not x:
+        assert_type(x, int)
+        reveal_type(x)  # revealed: int
+    else:
+        assert_type(x, C.MARKER)
+        reveal_type(x)  # revealed: MARKER
+```
+
+Sentinel declarations are recognized only in module and class scope:
+
+```py
+from typing_extensions import Sentinel
+
+def outer():
+    LOCAL = Sentinel("LOCAL")
+
+    def inner(x: LOCAL) -> None: ...  # error: [invalid-type-form]
+```
+
+Sentinels are not generic:
+
+```py
+from typing_extensions import Sentinel
+
+MISSING = Sentinel("MISSING")
+
+def f(x: MISSING[int]) -> None: ...  # error: [invalid-type-form]
+```
+
+Invalid sentinel constructor calls fall back to the normal call path:
+
+```py
+from typing_extensions import Sentinel
+
+NAME = "NAME"
+
+NON_LITERAL_NAME = Sentinel(NAME)
+UNKNOWN_NAME = Sentinel(UNKNOWN)  # error: [unresolved-reference]
+NON_LITERAL_REPR = Sentinel("NON_LITERAL_REPR", repr=NAME)
+UNKNOWN_REPR = Sentinel("UNKNOWN_REPR", repr=UNKNOWN)  # error: [unresolved-reference]
+UNKNOWN_KEYWORD = Sentinel("UNKNOWN_KEYWORD", unknown=NAME)  # error: [unknown-argument]
+```

crates/ty_python_semantic/src/types.rs

@@ -68,7 +68,9 @@ use crate::types::generics::{
     ApplySpecialization, InferableTypeVars, Specialization, bind_typevar,
 };
 use crate::types::infer::InferenceFlags;
-use crate::types::known_instance::{InternedConstraintSet, InternedType, UnionTypeInstance};
+use crate::types::known_instance::{
+    InternedConstraintSet, InternedType, SentinelInstance, UnionTypeInstance,
+};
 pub use crate::types::method::{BoundMethodType, KnownBoundMethodType, WrapperDescriptorKind};
 use crate::types::mro::{MroIterator, StaticMroError};
 pub(crate) use crate::types::narrow::{NarrowingConstraint, infer_narrowing_constraint};
@@ -2237,6 +2239,7 @@ impl<'db> Type<'db> {
                 !(special_form.check_module(KnownModule::Typing)
                     && special_form.check_module(KnownModule::TypingExtensions))
             }
+            Type::KnownInstance(KnownInstanceType::Sentinel(_)) => true,
             Type::KnownInstance(_) => false,
             Type::Callable(_) => {
                 // A callable type is never a singleton because for any given signature,
@@ -5402,6 +5405,9 @@ impl<'db> Type<'db> {
                 }
                 KnownInstanceType::Callable(callable) => Ok(Type::Callable(*callable)),
                 KnownInstanceType::LiteralStringAlias(ty) => Ok(ty.inner(db)),
+                KnownInstanceType::Sentinel(sentinel) => {
+                    Ok(Type::KnownInstance(KnownInstanceType::Sentinel(*sentinel)))
+                }
                 KnownInstanceType::FunctoolsPartial(_) => Err(InvalidTypeExpressionError {
                     invalid_expressions: smallvec_inline![InvalidTypeExpression::InvalidType(
                         *self, scope_id
@@ -6133,6 +6139,7 @@ impl<'db> Type<'db> {
                 | KnownInstanceType::LiteralStringAlias(_)
                 | KnownInstanceType::NamedTupleSpec(_)
                 | KnownInstanceType::NewType(_)
+                | KnownInstanceType::Sentinel(_)
                 | KnownInstanceType::FunctoolsPartial(_) => {
                     // TODO: For some of these, we may need to try to find legacy typevars in inner types.
                 }

crates/ty_python_semantic/src/types/class/known.rs

@@ -117,6 +117,7 @@ pub enum KnownClass {
     Mapping,
     // typing_extensions
     ExtensionsTypeVar, // must be distinct from typing.TypeVar, backports new features
+    Sentinel,
     // Collections
     ChainMap,
     Counter,
@@ -180,6 +181,7 @@ impl KnownClass {
             | Self::ParamSpecArgs
             | Self::ParamSpecKwargs
             | Self::TypeVarTuple
+            | Self::Sentinel
             | Self::Super
             | Self::WrapperDescriptorType
             | Self::UnionType
@@ -325,6 +327,7 @@ impl KnownClass {
             | KnownClass::ParamSpecArgs
             | KnownClass::ParamSpecKwargs
             | KnownClass::TypeVarTuple
+            | KnownClass::Sentinel
             | KnownClass::TypeAliasType
             | KnownClass::NoDefaultType
             | KnownClass::NewType
@@ -419,6 +422,7 @@ impl KnownClass {
             | KnownClass::ParamSpecArgs
             | KnownClass::ParamSpecKwargs
             | KnownClass::TypeVarTuple
+            | KnownClass::Sentinel
             | KnownClass::TypeAliasType
             | KnownClass::NoDefaultType
             | KnownClass::NewType
@@ -513,6 +517,7 @@ impl KnownClass {
             | KnownClass::ParamSpecArgs
             | KnownClass::ParamSpecKwargs
             | KnownClass::TypeVarTuple
+            | KnownClass::Sentinel
             | KnownClass::TypeAliasType
             | KnownClass::NoDefaultType
             | KnownClass::NewType
@@ -610,6 +615,7 @@ impl KnownClass {
             | Self::ParamSpecArgs
             | Self::ParamSpecKwargs
             | Self::TypeVarTuple
+            | Self::Sentinel
             | Self::TypeAliasType
             | Self::NoDefaultType
             | Self::NewType
@@ -720,6 +726,7 @@ impl KnownClass {
             | KnownClass::ParamSpecKwargs
             | KnownClass::ProtocolMeta
             | KnownClass::TypeVarTuple
+            | KnownClass::Sentinel
             | KnownClass::TypeAliasType
             | KnownClass::NoDefaultType
             | KnownClass::NewType
@@ -797,6 +804,7 @@ impl KnownClass {
             Self::ParamSpecArgs => "ParamSpecArgs",
             Self::ParamSpecKwargs => "ParamSpecKwargs",
             Self::TypeVarTuple => "TypeVarTuple",
+            Self::Sentinel => "Sentinel",
             Self::TypeAliasType => "TypeAliasType",
             Self::NoDefaultType => "_NoDefaultType",
             Self::NewType => "NewType",
@@ -1193,6 +1201,7 @@ impl KnownClass {
             Self::TypeAliasType
             | Self::ExtensionsTypeVar
             | Self::TypeVarTuple
+            | Self::Sentinel
             | Self::ExtensionsParamSpec
             | Self::ParamSpecArgs
             | Self::ParamSpecKwargs
@@ -1315,6 +1324,7 @@ impl KnownClass {
             | Self::ParamSpecArgs
             | Self::ParamSpecKwargs
             | Self::TypeVarTuple
+            | Self::Sentinel
             | Self::Enum
             | Self::EnumType
             | Self::Auto
@@ -1413,6 +1423,7 @@ impl KnownClass {
             | Self::ParamSpecArgs
             | Self::ParamSpecKwargs
             | Self::TypeVarTuple
+            | Self::Sentinel
             | Self::Enum
             | Self::EnumType
             | Self::Auto
@@ -1506,6 +1517,7 @@ impl KnownClass {
             "ParamSpecArgs" => &[Self::ParamSpecArgs],
             "ParamSpecKwargs" => &[Self::ParamSpecKwargs],
             "TypeVarTuple" => &[Self::TypeVarTuple],
+            "Sentinel" => &[Self::Sentinel],
             "ChainMap" => &[Self::ChainMap],
             "Counter" => &[Self::Counter],
             "defaultdict" => &[Self::DefaultDict],
@@ -1632,6 +1644,7 @@ impl KnownClass {
             | Self::ExtensionsTypeVar
             | Self::ParamSpec
             | Self::ExtensionsParamSpec
+            | Self::Sentinel
             | Self::NamedTupleLike
             | Self::ConstraintSet
             | Self::GenericContext

crates/ty_python_semantic/src/types/class_base.rs

@@ -191,6 +191,7 @@ impl<'db> ClassBase<'db> {
                 | KnownInstanceType::Literal(_)
                 | KnownInstanceType::LiteralStringAlias(_)
                 | KnownInstanceType::NamedTupleSpec(_)
+                | KnownInstanceType::Sentinel(_)
                 // A class inheriting from a newtype would make intuitive sense, but newtype
                 // wrappers are just identity callables at runtime, so this sort of inheritance
                 // doesn't work and isn't allowed.

crates/ty_python_semantic/src/types/display.rs

@@ -3109,6 +3109,9 @@ impl<'db> FmtDetailed<'db> for DisplayKnownInstanceRepr<'db> {
                 f.with_type(ty).write_str(declaration.name(self.db))?;
                 f.write_str("'>")
             }
+            KnownInstanceType::Sentinel(sentinel) => {
+                f.with_type(ty).write_str(sentinel.name(self.db).as_str())
+            }
             KnownInstanceType::NamedTupleSpec(_) => f.write_str("NamedTupleSpec"),
             KnownInstanceType::FunctoolsPartial(partial) => {
                 f.write_str("partial[")?;