Add sentinels (PEP 661) to the spec

conformance/results/mypy/specialtypes_sentinels.toml

@@ -0,0 +1,23 @@
+conformant = "Unsupported"
+conformance_automated = "Fail"
+errors_diff = """
+Line 36: Expected 1 errors
+Line 39: Expected 1 errors
+Line 21: Unexpected errors ['specialtypes_sentinels.py:21: error: Variable "specialtypes_sentinels.MISSING" is not valid as a type  [valid-type]']
+Line 23: Unexpected errors ['specialtypes_sentinels.py:23: error: Expression is of type "Any", not MISSING?  [assert-type]', 'specialtypes_sentinels.py:23: error: Variable "specialtypes_sentinels.MISSING" is not valid as a type  [valid-type]']
+Line 27: Unexpected errors ['specialtypes_sentinels.py:27: error: Variable "specialtypes_sentinels.Cls.IN_CLASS" is not valid as a type  [valid-type]']
+Line 29: Unexpected errors ['specialtypes_sentinels.py:29: error: Expression is of type "Any", not Cls.IN_CLASS?  [assert-type]', 'specialtypes_sentinels.py:29: error: Variable "specialtypes_sentinels.Cls.IN_CLASS" is not valid as a type  [valid-type]']
+"""
+output = """
+specialtypes_sentinels.py:15: error: Incompatible default for parameter "x" (default has type "Sentinel", parameter has type "int")  [assignment]
+specialtypes_sentinels.py:21: error: Variable "specialtypes_sentinels.MISSING" is not valid as a type  [valid-type]
+specialtypes_sentinels.py:21: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#variables-vs-type-aliases
+specialtypes_sentinels.py:23: error: Expression is of type "Any", not MISSING?  [assert-type]
+specialtypes_sentinels.py:23: error: Variable "specialtypes_sentinels.MISSING" is not valid as a type  [valid-type]
+specialtypes_sentinels.py:23: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#variables-vs-type-aliases
+specialtypes_sentinels.py:27: error: Variable "specialtypes_sentinels.Cls.IN_CLASS" is not valid as a type  [valid-type]
+specialtypes_sentinels.py:27: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#variables-vs-type-aliases
+specialtypes_sentinels.py:29: error: Expression is of type "Any", not Cls.IN_CLASS?  [assert-type]
+specialtypes_sentinels.py:29: error: Variable "specialtypes_sentinels.Cls.IN_CLASS" is not valid as a type  [valid-type]
+specialtypes_sentinels.py:29: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#variables-vs-type-aliases
+"""

conformance/results/pyrefly/specialtypes_sentinels.toml

@@ -0,0 +1,23 @@
+conformant = "Unsupported"
+conformance_automated = "Fail"
+errors_diff = """
+Line 36: Expected 1 errors
+Line 39: Expected 1 errors
+Line 21: Unexpected errors ['Expected a type form, got instance of `type[int] | UnionType` [not-a-type]']
+Line 23: Unexpected errors ['assert_type(Sentinel, Unknown) failed [assert-type]', 'Expected a type form, got instance of `Sentinel` [not-a-type]']
+Line 25: Unexpected errors ['assert_type(Unknown, int) failed [assert-type]']
+Line 27: Unexpected errors ['Expected a type form, got instance of `type[int] | UnionType` [not-a-type]']
+Line 29: Unexpected errors ['assert_type(Sentinel, Unknown) failed [assert-type]', 'Expected a type form, got instance of `Sentinel` [not-a-type]']
+Line 31: Unexpected errors ['assert_type(Unknown, int) failed [assert-type]']
+"""
+output = """
+ERROR specialtypes_sentinels.py:15:20-27: Default `Sentinel` is not assignable to parameter `x` with type `int` [bad-function-definition]
+ERROR specialtypes_sentinels.py:21:14-27: Expected a type form, got instance of `type[int] | UnionType` [not-a-type]
+ERROR specialtypes_sentinels.py:23:20-32: assert_type(Sentinel, Unknown) failed [assert-type]
+ERROR specialtypes_sentinels.py:23:24-31: Expected a type form, got instance of `Sentinel` [not-a-type]
+ERROR specialtypes_sentinels.py:25:20-28: assert_type(Unknown, int) failed [assert-type]
+ERROR specialtypes_sentinels.py:27:14-32: Expected a type form, got instance of `type[int] | UnionType` [not-a-type]
+ERROR specialtypes_sentinels.py:29:20-37: assert_type(Sentinel, Unknown) failed [assert-type]
+ERROR specialtypes_sentinels.py:29:24-36: Expected a type form, got instance of `Sentinel` [not-a-type]
+ERROR specialtypes_sentinels.py:31:20-28: assert_type(Unknown, int) failed [assert-type]
+"""

conformance/results/pyright/specialtypes_sentinels.toml

@@ -0,0 +1,24 @@
+conformant = "Unsupported"
+conformance_automated = "Fail"
+errors_diff = """
+Line 36: Expected 1 errors
+Line 39: Expected 1 errors
+Line 21: Unexpected errors ['specialtypes_sentinels.py:21:20 - error: Variable not allowed in type expression (reportInvalidTypeForm)']
+Line 23: Unexpected errors ['specialtypes_sentinels.py:23:21 - error: "assert_type" mismatch: expected "Unknown" but received "int | Unknown" (reportAssertTypeFailure)', 'specialtypes_sentinels.py:23:24 - error: Variable not allowed in type expression (reportInvalidTypeForm)']
+Line 25: Unexpected errors ['specialtypes_sentinels.py:25:21 - error: "assert_type" mismatch: expected "int" but received "int | Unknown" (reportAssertTypeFailure)']
+Line 27: Unexpected errors ['specialtypes_sentinels.py:27:24 - error: Variable not allowed in type expression (reportInvalidTypeForm)']
+Line 29: Unexpected errors ['specialtypes_sentinels.py:29:21 - error: "assert_type" mismatch: expected "Unknown" but received "int | Unknown" (reportAssertTypeFailure)', 'specialtypes_sentinels.py:29:28 - error: Variable not allowed in type expression (reportInvalidTypeForm)']
+Line 31: Unexpected errors ['specialtypes_sentinels.py:31:21 - error: "assert_type" mismatch: expected "int" but received "int | Unknown" (reportAssertTypeFailure)']
+"""
+output = """
+specialtypes_sentinels.py:15:20 - error: Expression of type "Sentinel" cannot be assigned to parameter of type "int"
+  "Sentinel" is not assignable to "int" (reportArgumentType)
+specialtypes_sentinels.py:21:20 - error: Variable not allowed in type expression (reportInvalidTypeForm)
+specialtypes_sentinels.py:23:21 - error: "assert_type" mismatch: expected "Unknown" but received "int | Unknown" (reportAssertTypeFailure)
+specialtypes_sentinels.py:23:24 - error: Variable not allowed in type expression (reportInvalidTypeForm)
+specialtypes_sentinels.py:25:21 - error: "assert_type" mismatch: expected "int" but received "int | Unknown" (reportAssertTypeFailure)
+specialtypes_sentinels.py:27:24 - error: Variable not allowed in type expression (reportInvalidTypeForm)
+specialtypes_sentinels.py:29:21 - error: "assert_type" mismatch: expected "Unknown" but received "int | Unknown" (reportAssertTypeFailure)
+specialtypes_sentinels.py:29:28 - error: Variable not allowed in type expression (reportInvalidTypeForm)
+specialtypes_sentinels.py:31:21 - error: "assert_type" mismatch: expected "int" but received "int | Unknown" (reportAssertTypeFailure)
+"""

conformance/results/results.html

@@ -262,6 +262,13 @@ <h3>Python Type System Conformance Test Results</h3>
 <th class="column col2 conformant">Pass</th>
 <th class="column col2 conformant">Pass</th>
 </tr>
+<tr><th class="column col1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;specialtypes_sentinels</th>
+<th class="column col2 not-conformant">Unsupported</th>
+<th class="column col2 not-conformant">Unsupported</th>
+<th class="column col2 not-conformant">Unsupported</th>
+<th class="column col2 not-conformant">Unsupported</th>
+<th class="column col2 not-conformant">Unsupported</th>
+</tr>
 <tr><th class="column col1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;specialtypes_type</th>
 <th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>Does not treat `type` same as `type[Any]` for assert_type.</p><p>Does not allow access to unknown attributes from object of type `type[Any]`.</p></span></div></th>
 <th class="column col2 conformant">Pass</th>

conformance/results/ty/specialtypes_sentinels.toml

@@ -0,0 +1,21 @@
+conformant = "Unsupported"
+conformance_automated = "Fail"
+errors_diff = """
+Line 36: Expected 1 errors
+Line 39: Expected 1 errors
+Line 21: Unexpected errors ['specialtypes_sentinels.py:21:20: error[invalid-type-form] Variable of type `Sentinel` is not allowed in a parameter annotation']
+Line 23: Unexpected errors ['specialtypes_sentinels.py:23:9: error[type-assertion-failure] Type `(int & Sentinel) | (Unknown & Sentinel)` does not match asserted type `@Todo`']
+Line 25: Unexpected errors ['specialtypes_sentinels.py:25:9: error[type-assertion-failure] Type `int | Unknown` does not match asserted type `int`']
+Line 27: Unexpected errors ['specialtypes_sentinels.py:27:20: error[invalid-type-form] Variable of type `Sentinel` is not allowed in a parameter annotation']
+Line 29: Unexpected errors ['specialtypes_sentinels.py:29:9: error[type-assertion-failure] Type `(int & Sentinel) | (Unknown & Sentinel)` does not match asserted type `@Todo`']
+Line 31: Unexpected errors ['specialtypes_sentinels.py:31:9: error[type-assertion-failure] Type `int | Unknown` does not match asserted type `int`']
+"""
+output = """
+specialtypes_sentinels.py:15:11: error[invalid-parameter-default] Default value of type `Sentinel` is not assignable to annotated parameter type `int`
+specialtypes_sentinels.py:21:20: error[invalid-type-form] Variable of type `Sentinel` is not allowed in a parameter annotation
+specialtypes_sentinels.py:23:9: error[type-assertion-failure] Type `(int & Sentinel) | (Unknown & Sentinel)` does not match asserted type `@Todo`
+specialtypes_sentinels.py:25:9: error[type-assertion-failure] Type `int | Unknown` does not match asserted type `int`
+specialtypes_sentinels.py:27:20: error[invalid-type-form] Variable of type `Sentinel` is not allowed in a parameter annotation
+specialtypes_sentinels.py:29:9: error[type-assertion-failure] Type `(int & Sentinel) | (Unknown & Sentinel)` does not match asserted type `@Todo`
+specialtypes_sentinels.py:31:9: error[type-assertion-failure] Type `int | Unknown` does not match asserted type `int`
+"""

conformance/results/zuban/specialtypes_sentinels.toml

@@ -0,0 +1,25 @@
+conformant = "Unsupported"
+conformance_automated = "Fail"
+errors_diff = """
+Line 36: Expected 1 errors
+Line 39: Expected 1 errors
+Line 21: Unexpected errors ['specialtypes_sentinels.py:21: error: Variable "tests.specialtypes_sentinels.MISSING" is not valid as a type  [valid-type]']
+Line 23: Unexpected errors ['specialtypes_sentinels.py:23: error: Variable "tests.specialtypes_sentinels.MISSING" is not valid as a type  [valid-type]']
+Line 25: Unexpected errors ['specialtypes_sentinels.py:25: error: Expression is of type "int | Any", not "int"  [misc]']
+Line 27: Unexpected errors ['specialtypes_sentinels.py:27: error: Variable "tests.specialtypes_sentinels.IN_CLASS" is not valid as a type  [valid-type]']
+Line 29: Unexpected errors ['specialtypes_sentinels.py:29: error: Variable "tests.specialtypes_sentinels.IN_CLASS" is not valid as a type  [valid-type]']
+Line 31: Unexpected errors ['specialtypes_sentinels.py:31: error: Expression is of type "int | Any", not "int"  [misc]']
+"""
+output = """
+specialtypes_sentinels.py:15: error: Incompatible default for argument "x" (default has type "Sentinel", argument has type "int")  [assignment]
+specialtypes_sentinels.py:21: error: Variable "tests.specialtypes_sentinels.MISSING" is not valid as a type  [valid-type]
+specialtypes_sentinels.py:21: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#variables-vs-type-aliases
+specialtypes_sentinels.py:23: error: Variable "tests.specialtypes_sentinels.MISSING" is not valid as a type  [valid-type]
+specialtypes_sentinels.py:23: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#variables-vs-type-aliases
+specialtypes_sentinels.py:25: error: Expression is of type "int | Any", not "int"  [misc]
+specialtypes_sentinels.py:27: error: Variable "tests.specialtypes_sentinels.IN_CLASS" is not valid as a type  [valid-type]
+specialtypes_sentinels.py:27: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#variables-vs-type-aliases
+specialtypes_sentinels.py:29: error: Variable "tests.specialtypes_sentinels.IN_CLASS" is not valid as a type  [valid-type]
+specialtypes_sentinels.py:29: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#variables-vs-type-aliases
+specialtypes_sentinels.py:31: error: Expression is of type "int | Any", not "int"  [misc]
+"""

conformance/tests/specialtypes_sentinels.py

@@ -0,0 +1,40 @@
+from unittest.mock import sentinel
+
+from typing_extensions import Sentinel, assert_type
+
+# > Sentinel objects may be used in type annotations if they are defined using
+# > a simple assignment of the form ``NAME = sentinel('NAME')`` in the
+# > global scope or in a class body that is not within a function.
+
+MISSING = Sentinel("<MISSING>")  # name is not required to match the variable name
+
+class Cls:
+    IN_CLASS = Sentinel("Cls.IN_CLASS")
+
+
+def func1(x: int = MISSING) -> None:  # E: incompatible default
+    pass
+
+# > Type checkers must support narrowing union types involving sentinels using the
+# > ``is`` and ``is not`` operators
+
+def func2(x: int | MISSING = MISSING) -> None:
+    if x is MISSING:
+        assert_type(x, MISSING)
+    else:
+        assert_type(x, int)
+
+def func3(x: int | Cls.IN_CLASS = Cls.IN_CLASS) -> None:
+    if x is Cls.IN_CLASS:
+        assert_type(x, Cls.IN_CLASS)
+    else:
+        assert_type(x, int)
+
+
+func2(1)  # ok
+func2(MISSING)  # ok
+func2(Cls.IN_CLASS)  # E: incompatible argument
+
+func3(1)  # ok
+func3(MISSING)  # E: incompatible argument
+func3(Cls.IN_CLASS)  # ok

docs/spec/annotations.rst

@@ -139,7 +139,7 @@ The following grammar describes the allowed elements of type and annotation expr
                    : | <None>
                    : | name
                    :       (where name must refer to a valid in-scope class,
-                   :        type alias, or TypeVar)
+                   :        type alias, TypeVar, or sentinel object)
                    : | name '[' (`maybe_unpacked` | `type_expression_list`)
                    :        (',' (`maybe_unpacked` | `type_expression_list`))* ']'
                    :       (the `type_expression_list` form is valid only when

docs/spec/special-types.rst

@@ -53,6 +53,46 @@ are highly dynamic.
 When used in a type hint, the expression ``None`` is considered
 equivalent to ``type(None)``.
 
+.. _ `sentinels`:
+
+Sentinels
+---------
+
+Sentinel objects may be used in type annotations to represent themselves::
+
+  MISSING = sentinel('MISSING')
+  OTHER = sentinel('OTHER')
+
+  def f(x: int | MISSING = MISSING) -> int:
+      if x is MISSING:
+          return 0
+      return x
+
+  f(OTHER)  # Error, OTHER is not an int or MISSING
+  f(MISSING)  # OK, MISSING is a valid argument
+
+Sentinels may be created using the ``sentinel()`` built-in in Python 3.15
+and higher. ``typing_extensions`` provides a backport of this function. For
+historical reasons the object was first introduced under the name
+``typing_extensions.Sentinel``, and later ``typing_extensions.sentinel`` was
+added as an alias; type checkers should support both.
+
+Sentinel objects may be used in type annotations if they are defined using
+a simple assignment of the form ``NAME = sentinel('NAME')`` in the
+global scope or in a class body that is not within a function. The name of the
+variable need not match the string argument passed to ``sentinel()`` but it is
+conventional to do so for names in the global scope.
+
+Type checkers must support narrowing union types involving sentinels using the
+``is`` and ``is not`` operators::
+
+  def g(x: int | MISSING) -> None:
+      if x is MISSING:
+          assert_type(x, MISSING)
+      else:
+          assert_type(x, int)
+
+
 .. _`noreturn`:
 
 ``NoReturn``