Add Sentinel support (PEP-661)

Author: hrolfurgylfa

crates/pyrefly_config/src/error_kind.rs

@@ -220,6 +220,8 @@ pub enum ErrorKind {
     /// A use of `typing.Self` in a context where Pyrefly does not recognize it as
     /// mapping to a valid class type.
     InvalidSelfType,
+    /// An error caused by incorrect usage or definition of a Sentinel.
+    InvalidSentinel,
     /// Attempting to call `super()` in a way that is not allowed.
     /// e.g. calling `super(Y, x)` on an object `x` that does not match the class `Y`.
     InvalidSuperCall,

crates/pyrefly_types/src/display.rs

@@ -570,6 +570,7 @@ impl<'a> TypeDisplayContext<'a> {
                 output.write_qname(t.qname())?;
                 output.write_str("]")
             }
+            Type::Sentinel(t) => output.write_qname(t.qname()),
             Type::TypeVarTuple(t) => {
                 let type_var_tuple_qname = self.stdlib.map(|s| s.type_var_tuple().qname());
                 output.write_builtin("TypeVarTuple", type_var_tuple_qname)?;

crates/pyrefly_types/src/equality.rs

@@ -28,6 +28,7 @@ use vec1::Vec1;
 
 use crate::param_spec::ParamSpec;
 use crate::quantified::QuantifiedIdentity;
+use crate::sentinel::Sentinel;
 use crate::type_var::TypeVar;
 use crate::type_var_tuple::TypeVarTuple;
 
@@ -47,6 +48,7 @@ pub struct TypeEqCtx {
     param_spec: SmallMap<ParamSpec, ParamSpec>,
     type_var: SmallMap<TypeVar, TypeVar>,
     type_var_tuple: SmallMap<TypeVarTuple, TypeVarTuple>,
+    sentinel: SmallMap<Sentinel, Sentinel>,
     /// Alpha-equivalence mapping for Quantified binders: LHS identity → RHS identity.
     /// First pairing wins; subsequent occurrences must match.
     quantified_identity: SmallMap<QuantifiedIdentity, QuantifiedIdentity>,
@@ -144,6 +146,18 @@ impl TypeEq for TypeVarTuple {
     }
 }
 
+impl TypeEq for Sentinel {
+    fn type_eq(&self, other: &Self, ctx: &mut TypeEqCtx) -> bool {
+        type_eq_identity(
+            self,
+            other,
+            ctx,
+            |ctx| &mut ctx.sentinel,
+            |ctx| self.type_eq_inner(other, ctx),
+        )
+    }
+}
+
 pub trait TypeEq: Eq {
     fn type_eq(&self, other: &Self, ctx: &mut TypeEqCtx) -> bool {
         let _ = ctx;

crates/pyrefly_types/src/heap.rs

@@ -37,6 +37,7 @@ use crate::literal::Literal;
 use crate::module::ModuleType;
 use crate::param_spec::ParamSpec;
 use crate::quantified::Quantified;
+use crate::sentinel::Sentinel;
 use crate::special_form::SpecialForm;
 use crate::tensor::TensorType;
 use crate::tuple::Tuple;
@@ -137,6 +138,11 @@ impl TypeHeap {
         Type::None
     }
 
+    /// Create a `Type::Sentinel`.
+    pub fn mk_sentinel(&self, sentinel: Sentinel) -> Type {
+        Type::Sentinel(sentinel)
+    }
+
     /// Create a `Type::Union` from members.
     pub fn mk_union(&self, members: Vec<Type>) -> Type {
         Type::Union(Box::new(Union {

crates/pyrefly_types/src/lib.rs

@@ -38,6 +38,7 @@ pub mod module;
 pub mod param_spec;
 pub mod quantified;
 pub mod read_only;
+pub mod sentinel;
 pub mod simplify;
 pub mod special_form;
 pub mod stdlib;

crates/pyrefly_types/src/sentinel.rs

@@ -0,0 +1,72 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+use std::fmt;
+use std::fmt::Display;
+use std::hash::Hash;
+
+use dupe::Dupe;
+use pyrefly_derive::TypeEq;
+use pyrefly_python::module::Module;
+use pyrefly_python::nesting_context::NestingContext;
+use pyrefly_python::qname::QName;
+use pyrefly_util::arc_id::ArcId;
+use pyrefly_util::visit::Visit;
+use pyrefly_util::visit::VisitMut;
+use ruff_python_ast::Identifier;
+
+use crate::equality::TypeEq;
+use crate::equality::TypeEqCtx;
+use crate::heap::TypeHeap;
+use crate::types::Type;
+
+/// Used to represent Sentinel calls. Each Sentinel is unique, so use the ArcId to separate them.
+#[derive(Clone, Dupe, Debug, PartialEq, Eq, Hash, Ord, PartialOrd)]
+pub struct Sentinel(ArcId<SentinelInner>);
+
+// This is a lie, we do have types in the bound position
+impl Visit<Type> for Sentinel {
+    const RECURSE_CONTAINS: bool = false;
+    fn recurse<'a>(&'a self, _: &mut dyn FnMut(&'a Type)) {}
+}
+
+impl VisitMut<Type> for Sentinel {
+    const RECURSE_CONTAINS: bool = false;
+    fn recurse_mut(&mut self, _: &mut dyn FnMut(&mut Type)) {}
+}
+
+impl Display for Sentinel {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.0.qname.id())
+    }
+}
+
+#[derive(Debug, PartialEq, TypeEq, Eq, Ord, PartialOrd)]
+struct SentinelInner {
+    qname: QName,
+}
+
+impl Sentinel {
+    pub fn new(name: Identifier, module: Module) -> Self {
+        Self(ArcId::new(SentinelInner {
+            // TODO: properly take parent from caller of new()
+            qname: QName::new(name, NestingContext::toplevel(), module),
+        }))
+    }
+
+    pub fn qname(&self) -> &QName {
+        &self.0.qname
+    }
+
+    pub fn to_type(&self, heap: &TypeHeap) -> Type {
+        heap.mk_sentinel(self.dupe())
+    }
+
+    pub fn type_eq_inner(&self, other: &Self, ctx: &mut TypeEqCtx) -> bool {
+        self.0.type_eq(&other.0, ctx)
+    }
+}

crates/pyrefly_types/src/stdlib.rs

@@ -105,6 +105,8 @@ pub struct Stdlib {
     /// After 3.14, `typing_extensions` reexports from `typing`.
     /// For 3.12 and 3.13 defined separately in both locations.
     type_alias_type: StdlibResult<ClassType>,
+    /// Defined in `typing_extensions` until 3.15, defined in `typing` since 3.15.
+    sentinel: StdlibResult<ClassType>,
     traceback_type: StdlibResult<ClassType>,
     builtins_type: StdlibResult<ClassType>,
     /// Introduced in Python 3.10.
@@ -257,6 +259,7 @@ impl Stdlib {
             param_spec_kwargs: lookup_concrete(standardised(3, 10), "ParamSpecKwargs"),
             type_var_tuple: lookup_concrete(standardised(3, 11), "TypeVarTuple"),
             type_alias_type: lookup_concrete(standardised(3, 12), "TypeAliasType"),
+            sentinel: lookup_concrete(standardised(3, 15), "Sentinel"),
             traceback_type: lookup_concrete(types, "TracebackType"),
             function_type: lookup_concrete(types, "FunctionType"),
             method_type: lookup_concrete(types, "MethodType"),
@@ -577,6 +580,10 @@ impl Stdlib {
         Self::primitive(&self.type_alias_type)
     }
 
+    pub fn sentinel(&self) -> &ClassType {
+        Self::primitive(&self.sentinel)
+    }
+
     pub fn traceback_type(&self) -> &ClassType {
         Self::primitive(&self.traceback_type)
     }

crates/pyrefly_types/src/types.rs

@@ -58,6 +58,7 @@ use crate::literal::Literal;
 use crate::module::ModuleType;
 use crate::param_spec::ParamSpec;
 use crate::quantified::Quantified;
+use crate::sentinel::Sentinel;
 use crate::simplify::unions;
 use crate::special_form::SpecialForm;
 use crate::stdlib::Stdlib;
@@ -857,6 +858,9 @@ pub enum Type {
     /// be immediately looked up for untyping (see `TypeAliasData::TypeAliasRef`), `UntypedAlias`
     /// stores a reference that is untyped once we actually look up the value.
     UntypedAlias(Box<TypeAliasData>),
+    // Sentinel types, documented here: https://docs.python.org/3.15/library/functions.html#sentinel
+    // First introduced in PEP 661: https://peps.python.org/pep-0661/
+    Sentinel(Sentinel),
     /// Represents the result of a super() call. The first ClassType is the point in the MRO that attribute lookup
     /// on the super instance should start at (*not* the class passed to the super() call), and the second
     /// ClassType is the second argument (implicit or explicit) to the super() call. For example, in:
@@ -918,6 +922,7 @@ impl Visit for Type {
             Type::Annotated(x, _metadata) => x.visit(f),
             Type::Unpack(x) => x.visit(f),
             Type::TypeVar(x) => x.visit(f),
+            Type::Sentinel(x) => x.visit(f),
             Type::ParamSpec(x) => x.visit(f),
             Type::TypeVarTuple(x) => x.visit(f),
             Type::SpecialForm(x) => x.visit(f),
@@ -974,6 +979,7 @@ impl VisitMut for Type {
             Type::Annotated(x, _metadata) => x.visit_mut(f),
             Type::Unpack(x) => x.visit_mut(f),
             Type::TypeVar(x) => x.visit_mut(f),
+            Type::Sentinel(x) => x.visit_mut(f),
             Type::ParamSpec(x) => x.visit_mut(f),
             Type::TypeVarTuple(x) => x.visit_mut(f),
             Type::SpecialForm(x) => x.visit_mut(f),
@@ -1924,6 +1930,7 @@ impl Type {
             Type::ParamSpec(t) => Some(t.qname()),
             Type::SelfType(cls) => Some(cls.qname()),
             Type::Literal(lit) if let Lit::Enum(e) = &lit.value => Some(e.class.qname()),
+            Type::Sentinel(s) => Some(s.qname()),
             _ => None,
         }
     }
@@ -1937,6 +1944,7 @@ impl Type {
             Type::Literal(lit) if let Lit::Str(x) = &lit.value => Some(!x.is_empty()),
             Type::Type(_) => Some(true),
             Type::None => Some(false),
+            Type::Sentinel(_) => Some(true),
             Type::Tuple(Tuple::Concrete(elements)) => Some(!elements.is_empty()),
             Type::Union(u) => {
                 let mut answer = None;

pyrefly/lib/alt/attr.rs

@@ -2336,6 +2336,9 @@ impl<'a, Ans: LookupAnswer> AnswersSolver<'a, Ans> {
             Type::TypeVar(_) => acc.push(AttributeBase1::ClassInstance(
                 self.stdlib.type_var().clone(),
             )),
+            Type::Sentinel(_) => acc.push(AttributeBase1::ClassInstance(
+                self.stdlib.sentinel().clone(),
+            )),
             Type::ParamSpec(_) => acc.push(AttributeBase1::ClassInstance(
                 self.stdlib.param_spec().clone(),
             )),

pyrefly/lib/alt/expr.rs

@@ -94,6 +94,7 @@ use crate::types::literal::Lit;
 use crate::types::param_spec::ParamSpec;
 use crate::types::quantified::Quantified;
 use crate::types::quantified::QuantifiedKind;
+use crate::types::sentinel::Sentinel;
 use crate::types::special_form::SpecialForm;
 use crate::types::tuple::Tuple;
 use crate::types::type_info::TypeInfo;
@@ -1799,6 +1800,97 @@ impl<'a, Ans: LookupAnswer> AnswersSolver<'a, Ans> {
         }
     }
 
+    pub fn sentinel_from_call(
+        &self,
+        name: Identifier,
+        x: &ExprCall,
+        errors: &ErrorCollector,
+    ) -> Sentinel {
+        let mut iargs = x.arguments.args.iter();
+        if let Some(arg) = iargs.next() {
+            if let Expr::StringLiteral(lit) = arg {
+                if lit.value.to_str() != name.id.as_str() {
+                    self.error(
+                        errors,
+                        x.range,
+                        ErrorKind::InvalidSentinel,
+                        format!(
+                            "Sentinel must be assigned to a variable named `{}`",
+                            lit.value.to_str()
+                        ),
+                    );
+                }
+            } else {
+                self.error(
+                    errors,
+                    arg.range(),
+                    ErrorKind::InvalidSentinel,
+                    "Expected first argument of Sentinel to be a string literal".to_owned(),
+                );
+            }
+        } else {
+            self.error(
+                errors,
+                x.range,
+                ErrorKind::InvalidSentinel,
+                "Sentinel requires a name as the first argument".to_owned(),
+            );
+        }
+        if let Some(arg) = iargs.next() {
+            let args_range_end = x.arguments.args.last().map(|arg| arg.range().end());
+            let range = TextRange::new(
+                arg.range().start(),
+                // args_range_end should never be None as it should only be None if there are
+                // no args, but no reason not to have a default here anyway.
+                args_range_end.unwrap_or_else(|| arg.range().end()),
+            );
+            self.error(
+                errors,
+                range,
+                ErrorKind::InvalidSentinel,
+                "Sentinel only takes one positional argument".to_owned(),
+            );
+        }
+
+        for kw in &x.arguments.keywords {
+            match &kw.arg {
+                Some(id) => match id.id.as_str() {
+                    "repr" => {
+                        let got = self.expr_infer(&kw.value, errors);
+                        if !self
+                            .is_subset_eq(&got, &self.heap.mk_class_type(self.stdlib.str().clone()))
+                        {
+                            self.error(
+                                errors,
+                                kw.range,
+                                ErrorKind::InvalidSentinel,
+                                format!("Invalid type for Sentinel `repr` {got}"),
+                            );
+                        }
+                    }
+                    _ => {
+                        self.error(
+                            errors,
+                            kw.range,
+                            ErrorKind::InvalidSentinel,
+                            format!("Unexpected keyword argument `{}` to Sentinel", id.id),
+                        );
+                    }
+                },
+                _ => {
+                    self.error(
+                        errors,
+                        kw.range,
+                        ErrorKind::InvalidSentinel,
+                        "Cannot pass unpacked keyword arguments to Sentinel".to_owned(),
+                    );
+                }
+            }
+        }
+
+        Sentinel::new(name, self.module().dupe())
+    }
+
     pub fn typevar_from_call(
         &self,
         name: Identifier,