Skip to content

Add sentinels (PEP 661) to the spec #2277

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JelleZijlstra merged 7 commits into from
Aug 7, 2026
Merged

Add sentinels (PEP 661) to the spec #2277

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
d9961b2
Add sentinels (PEP 661) to the spec
JelleZijlstra May 1, 2026
de6d9ea
.
JelleZijlstra May 1, 2026
19e4152
Merge remote-tracking branch 'upstream/main' into sentinels
JelleZijlstra May 2, 2026
e6dd6e3
update
JelleZijlstra May 2, 2026
84d6fd8
add file
JelleZijlstra May 2, 2026
36a2158
add
JelleZijlstra May 2, 2026
9e7b570
Merge remote-tracking branch 'upstream/main' into codex/pr-2277-merge…
JelleZijlstra Aug 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions conformance/results/mypy/specialtypes_sentinels.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
conformant = "Unsupported"
conformance_automated = "Fail"
errors_diff = """
Line 36: Expected 1 errors
Line 39: Expected 1 errors
Line 20: Unexpected errors ['specialtypes_sentinels.py:20: error: Variable "specialtypes_sentinels.MISSING" is not valid as a type [valid-type]', 'specialtypes_sentinels.py:20: error: Variable "specialtypes_sentinels.SPECIAL" is not valid as a type [valid-type]']
Line 22: Unexpected errors ['specialtypes_sentinels.py:22: error: Expression is of type "Any", not MISSING? [assert-type]', 'specialtypes_sentinels.py:22: error: Variable "specialtypes_sentinels.MISSING" is not valid as a type [valid-type]']
Line 24: Unexpected errors ['specialtypes_sentinels.py:24: error: Variable "specialtypes_sentinels.SPECIAL" is not valid as a type [valid-type]']
Line 26: Unexpected errors ['specialtypes_sentinels.py:26: error: Variable "specialtypes_sentinels.Cls.IN_CLASS" is not valid as a type [valid-type]']
Line 28: Unexpected errors ['specialtypes_sentinels.py:28: error: Expression is of type "Any", not Cls.IN_CLASS? [assert-type]', 'specialtypes_sentinels.py:28: error: Variable "specialtypes_sentinels.Cls.IN_CLASS" is not valid as a type [valid-type]']
"""
output = """
specialtypes_sentinels.py:14: error: Incompatible default for parameter "x" (default has type "Sentinel", parameter has type "int") [assignment]
specialtypes_sentinels.py:20: error: Variable "specialtypes_sentinels.MISSING" is not valid as a type [valid-type]
specialtypes_sentinels.py:20: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#variables-vs-type-aliases
specialtypes_sentinels.py:20: error: Variable "specialtypes_sentinels.SPECIAL" is not valid as a type [valid-type]
specialtypes_sentinels.py:22: error: Expression is of type "Any", not MISSING? [assert-type]
specialtypes_sentinels.py:22: error: Variable "specialtypes_sentinels.MISSING" is not valid as a type [valid-type]
specialtypes_sentinels.py:22: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#variables-vs-type-aliases
specialtypes_sentinels.py:24: error: Variable "specialtypes_sentinels.SPECIAL" is not valid as a type [valid-type]
specialtypes_sentinels.py:24: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#variables-vs-type-aliases
specialtypes_sentinels.py:26: error: Variable "specialtypes_sentinels.Cls.IN_CLASS" is not valid as a type [valid-type]
specialtypes_sentinels.py:26: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#variables-vs-type-aliases
specialtypes_sentinels.py:28: error: Expression is of type "Any", not Cls.IN_CLASS? [assert-type]
specialtypes_sentinels.py:28: error: Variable "specialtypes_sentinels.Cls.IN_CLASS" is not valid as a type [valid-type]
specialtypes_sentinels.py:28: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#variables-vs-type-aliases
"""
8 changes: 8 additions & 0 deletions conformance/results/pycroscope/specialtypes_sentinels.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
conformance_automated = "Pass"
errors_diff = """
"""
output = """
./specialtypes_sentinels.py:14:10: Default value for argument x incompatible with declared type int [incompatible_default]
./specialtypes_sentinels.py:36:6: Incompatible argument type for x: expected int | Literal[<<MISSING>>, <SPECIAL>] but got <Cls.IN_CLASS> [incompatible_argument]
./specialtypes_sentinels.py:39:6: Incompatible argument type for x: expected int | Literal[<Cls.IN_CLASS>] but got <<MISSING>> [incompatible_argument]
"""
9 changes: 9 additions & 0 deletions conformance/results/pyrefly/specialtypes_sentinels.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
conformant = "Pass"
conformance_automated = "Pass"
errors_diff = """
"""
output = """
ERROR specialtypes_sentinels.py:14:20-27: Default `<MISSING>` is not assignable to parameter `x` with type `int` [bad-function-definition]
ERROR specialtypes_sentinels.py:36:7-19: Argument `Cls.Cls.IN_CLASS` is not assignable to parameter `x` with type `int | <MISSING> | SPECIAL` in function `func2` [bad-argument-type]
ERROR specialtypes_sentinels.py:39:7-14: Argument `<MISSING>` is not assignable to parameter `x` with type `int | Cls.Cls.IN_CLASS` in function `func3` [bad-argument-type]
"""
31 changes: 31 additions & 0 deletions conformance/results/pyright/specialtypes_sentinels.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
conformant = "Partial"
notes = """
Requires the string passed to `Sentinel` to match the assigned variable name.
This causes valid sentinel types and narrowing operations to be rejected.
"""
conformance_automated = "Fail"
errors_diff = """
Line 14: Expected 1 errors
Line 36: Expected 1 errors
Line 39: Expected 1 errors
Line 7: Unexpected errors ['specialtypes_sentinels.py:7:1 - error: Sentinel must be assigned to a variable with the same name (reportGeneralTypeIssues)']
Line 11: Unexpected errors ['specialtypes_sentinels.py:11:5 - error: Sentinel must be assigned to a variable with the same name (reportGeneralTypeIssues)']
Line 20: Unexpected errors ['specialtypes_sentinels.py:20:20 - error: Variable not allowed in type expression (reportInvalidTypeForm)']
Line 22: Unexpected errors ['specialtypes_sentinels.py:22:21 - error: "assert_type" mismatch: expected "Unknown" but received "int | Unknown | SPECIAL" (reportAssertTypeFailure)', 'specialtypes_sentinels.py:22:24 - error: Variable not allowed in type expression (reportInvalidTypeForm)']
Line 24: Unexpected errors ['specialtypes_sentinels.py:24:21 - error: "assert_type" mismatch: expected "int | SPECIAL" but received "int | Unknown | SPECIAL" (reportAssertTypeFailure)']
Line 26: Unexpected errors ['specialtypes_sentinels.py:26:24 - error: Variable not allowed in type expression (reportInvalidTypeForm)']
Line 28: Unexpected errors ['specialtypes_sentinels.py:28:21 - error: "assert_type" mismatch: expected "Unknown" but received "int | Unknown" (reportAssertTypeFailure)', 'specialtypes_sentinels.py:28:28 - error: Variable not allowed in type expression (reportInvalidTypeForm)']
Line 30: Unexpected errors ['specialtypes_sentinels.py:30:21 - error: "assert_type" mismatch: expected "int" but received "int | Unknown" (reportAssertTypeFailure)']
"""
output = """
specialtypes_sentinels.py:7:1 - error: Sentinel must be assigned to a variable with the same name (reportGeneralTypeIssues)
specialtypes_sentinels.py:11:5 - error: Sentinel must be assigned to a variable with the same name (reportGeneralTypeIssues)
specialtypes_sentinels.py:20:20 - error: Variable not allowed in type expression (reportInvalidTypeForm)
specialtypes_sentinels.py:22:21 - error: "assert_type" mismatch: expected "Unknown" but received "int | Unknown | SPECIAL" (reportAssertTypeFailure)
specialtypes_sentinels.py:22:24 - error: Variable not allowed in type expression (reportInvalidTypeForm)
specialtypes_sentinels.py:24:21 - error: "assert_type" mismatch: expected "int | SPECIAL" but received "int | Unknown | SPECIAL" (reportAssertTypeFailure)
specialtypes_sentinels.py:26:24 - error: Variable not allowed in type expression (reportInvalidTypeForm)
specialtypes_sentinels.py:28:21 - error: "assert_type" mismatch: expected "Unknown" but received "int | Unknown" (reportAssertTypeFailure)
specialtypes_sentinels.py:28:28 - error: Variable not allowed in type expression (reportInvalidTypeForm)
specialtypes_sentinels.py:30:21 - error: "assert_type" mismatch: expected "int" but received "int | Unknown" (reportAssertTypeFailure)
"""
39 changes: 27 additions & 12 deletions conformance/results/results.html
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

9 changes: 9 additions & 0 deletions conformance/results/ty/specialtypes_sentinels.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
conformant = "Pass"
conformance_automated = "Pass"
errors_diff = """
"""
output = """
specialtypes_sentinels.py:14:11: error[invalid-parameter-default] Default value of type `MISSING` is not assignable to annotated parameter type `int`
specialtypes_sentinels.py:36:7: error[invalid-argument-type] Argument to function `func2` is incorrect: Expected `int | MISSING | SPECIAL`, found `IN_CLASS`
specialtypes_sentinels.py:39:7: error[invalid-argument-type] Argument to function `func3` is incorrect: Expected `int | IN_CLASS`, found `MISSING`
"""
9 changes: 9 additions & 0 deletions conformance/results/zuban/specialtypes_sentinels.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
conformant = "Pass"
conformance_automated = "Pass"
errors_diff = """
"""
output = """
specialtypes_sentinels.py:14: error: Incompatible default for parameter "x" (default has type "Sentinel('<MISSING>')", parameter has type "int") [assignment]
specialtypes_sentinels.py:36: error: Argument 1 to "func2" has incompatible type "Sentinel('Cls.IN_CLASS')"; expected "int | Sentinel('<MISSING>') | Sentinel('SPECIAL')" [arg-type]
specialtypes_sentinels.py:39: error: Argument 1 to "func3" has incompatible type "Sentinel('<MISSING>')"; expected "int | Sentinel('Cls.IN_CLASS')" [arg-type]
"""
40 changes: 40 additions & 0 deletions conformance/tests/specialtypes_sentinels.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
from typing_extensions import Sentinel, assert_type
Comment thread
davidhalter marked this conversation as resolved.

# > 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

@carljm carljm Jul 27, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If it's still generally considered good style where possible to have the names match (and if it isn't, why is this case different from e.g. TypeVar etc?), type checkers may want to provide this as a style warning/lint. Should we allow that here with an # E?

See discussion in astral-sh/ty#4091

@JelleZijlstra JelleZijlstra Jul 27, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd prefer to do this by turning off the error code for ty in our checks. That way, we enforce that the type checker has a mode that allows this; a type checker that always errors on mismatched names is not compliant.

In general I'd rather avoid "E?" as it makes the spec weaker in its checks.

@carljm carljm Jul 27, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, we were planning to make this the same error code that enforces name matching on TypeVar and all other similar forms. I think if we disabled that error code for the conformance suite, it might cause us to fail some other checks? So I guess that gets back to my question above: is there a reason the conformance suite expectation for sentinels should be the reverse of what it is for those other forms with a similar name pattern?

@JelleZijlstra JelleZijlstra Jul 27, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd be willing to relax the check for TypeVar etc. too but that's a little out of scope for this PR.

I do think the case for having a mismatched name is stronger for sentinels, which have more runtime uses than other objects where we might want a name match.

@carljm carljm Jul 27, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I see the rationale for it being different from TypeVar etc. We can just make it a different error code in ty. Feels somewhat odd to have two different error codes for what looks like an identical pattern, but if it's expected that some users will want to enforce same-name for TypeVar et al but not for sentinel, then it's worth it.

SPECIAL = Sentinel("SPECIAL")

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 | SPECIAL = MISSING) -> None:
if x is MISSING:
assert_type(x, MISSING)
else:
assert_type(x, int | SPECIAL)

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(SPECIAL) # ok
func2(Cls.IN_CLASS) # E: incompatible argument

func3(1) # ok
func3(MISSING) # E: incompatible argument
func3(Cls.IN_CLASS) # ok
2 changes: 1 addition & 1 deletion docs/spec/annotations.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
40 changes: 40 additions & 0 deletions docs/spec/special-types.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment on lines +75 to +78

@cdce8p cdce8p May 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure about typing_extensions.Sentinel. If most type checkers already supported it fine, but as it's not, it might be easier in the long term to just drop the requirement here.

@carljm carljm May 1, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like at the moment typing_extensions.sentinel doesn't exist yet in typeshed. As long as typing_extensions.sentinel and typing_extensions.Sentinel are the same kind of object in typeshed (e.g. both classes), or one is literally an alias of the other, I expect it asks very little of type-checkers to support both.

That said, if there really aren't any uses of typing_extensions.Sentinel yet in the wild, I agree it seems like it would reduce the potential for confusion if we didn't support it.

@JelleZijlstra JelleZijlstra May 2, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's already being used by Pydantic: https://github.com/pydantic/pydantic/blob/597fa692eaaa90132f683e88ca994f28e185463b/pydantic-core/python/pydantic_core/__init__.py#L148

@cdce8p cdce8p May 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's already being used by Pydantic: https://github.com/pydantic/pydantic/blob/597fa692eaaa90132f683e88ca994f28e185463b/pydantic-core/python/pydantic_core/__init__.py#L148

Is that really an issue though if almost no type checker supports it? To be clear I'm not talking about removing it from typing_extensions. That would break already released pydantic versions. I'd just suggest only enforcing that type checkers support the lower case variants. For pydantic that would essentially mean to switch to sentinel, which I'd guess they'll do anyway as soon as it's available, and update their type checker once those support it. Until then they will just continue to see the error messages they already see now.

@JelleZijlstra JelleZijlstra May 2, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd prefer to support both since it doesn't seem like it would add a significant burden to type checkers.

@cdce8p cdce8p May 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd prefer to support both since it doesn't seem like it would add a significant burden to type checkers.

Sure, once support for PEP 661 is implemented, supporting typing_extensions.Sentinel will be trivial. That reduces the incentive for projects to migrate to sentinel though, thus forcing typing-extensions to keep it around for longer.

Mypy still has code for mypy_extensions.TypedDict which I'd love to clean up, though I suspect it might still be a long while before that will happen. Better to not enforce supporting something outdated to begin with. If type checkers decide they still want to support it, so be it, but I'd recommend against dictating it in the spec.

@Viicos Viicos May 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Pydantic side, we explicitly document the feature using sentinels as experimental, meaning (at least for us) users should be prepared for things to break, so our end we are fine not supporting Sentinel.


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``
Expand Down