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

Open
JelleZijlstra wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Add sentinels (PEP 661) to the spec #2277

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 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
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]
"""
23 changes: 23 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,23 @@
conformant = "Unsupported"
conformance_automated = "Fail"
errors_diff = """
Line 36: Expected 1 errors
Line 39: Expected 1 errors
Line 20: Unexpected errors ['Expected a type form, got instance of `type[int] | UnionType | Any` [not-a-type]']
Line 22: Unexpected errors ['assert_type(Sentinel, Unknown) failed [assert-type]', 'Expected a type form, got instance of `Sentinel` [not-a-type]']
Line 24: Unexpected errors ['Expected a type form, got instance of `type[int] | UnionType` [not-a-type]']
Line 26: Unexpected errors ['Expected a type form, got instance of `type[int] | UnionType` [not-a-type]']
Line 28: Unexpected errors ['assert_type(Sentinel, Unknown) failed [assert-type]', 'Expected a type form, got instance of `Sentinel` [not-a-type]']
Line 30: Unexpected errors ['assert_type(Unknown, int) failed [assert-type]']
"""
output = """
ERROR specialtypes_sentinels.py:14:20-27: Default `Sentinel` is not assignable to parameter `x` with type `int` [bad-function-definition]
ERROR specialtypes_sentinels.py:20:14-37: Expected a type form, got instance of `type[int] | UnionType | Any` [not-a-type]
ERROR specialtypes_sentinels.py:22:20-32: assert_type(Sentinel, Unknown) failed [assert-type]
ERROR specialtypes_sentinels.py:22:24-31: Expected a type form, got instance of `Sentinel` [not-a-type]
ERROR specialtypes_sentinels.py:24:24-37: Expected a type form, got instance of `type[int] | UnionType` [not-a-type]
ERROR specialtypes_sentinels.py:26:14-32: Expected a type form, got instance of `type[int] | UnionType` [not-a-type]
ERROR specialtypes_sentinels.py:28:20-37: assert_type(Sentinel, Unknown) failed [assert-type]
ERROR specialtypes_sentinels.py:28:24-36: Expected a type form, got instance of `Sentinel` [not-a-type]
ERROR specialtypes_sentinels.py:30:20-28: assert_type(Unknown, int) failed [assert-type]
"""
25 changes: 25 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,25 @@
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:20 - error: Variable not allowed in type expression (reportInvalidTypeForm)', 'specialtypes_sentinels.py:20:30 - 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" (reportAssertTypeFailure)', 'specialtypes_sentinels.py:22:24 - error: Variable not allowed in type expression (reportInvalidTypeForm)']
Line 24: Unexpected errors ['specialtypes_sentinels.py:24:30 - error: Variable not allowed in type expression (reportInvalidTypeForm)']
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:14:20 - error: Expression of type "Sentinel" cannot be assigned to parameter of type "int"
  "Sentinel" is not assignable to "int" (reportArgumentType)
specialtypes_sentinels.py:20:20 - error: Variable not allowed in type expression (reportInvalidTypeForm)
specialtypes_sentinels.py:20:30 - error: Variable not allowed in type expression (reportInvalidTypeForm)
specialtypes_sentinels.py:22:21 - error: "assert_type" mismatch: expected "Unknown" but received "int | Unknown" (reportAssertTypeFailure)
specialtypes_sentinels.py:22:24 - error: Variable not allowed in type expression (reportInvalidTypeForm)
specialtypes_sentinels.py:24:30 - error: Variable not allowed in type expression (reportInvalidTypeForm)
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)
"""
8 changes: 8 additions & 0 deletions conformance/results/results.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -274,6 +274,14 @@ <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 conformant">Pass</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>
Expand Down
22 changes: 22 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,22 @@
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:20: error[invalid-type-form] Variable of type `Sentinel` is not allowed in a parameter annotation', 'specialtypes_sentinels.py:20:30: error[invalid-type-form] Variable of type `Sentinel` is not allowed in a parameter annotation']
Line 22: Unexpected errors ['specialtypes_sentinels.py:22:9: error[type-assertion-failure] Type `(int & Sentinel) | (Unknown & Sentinel)` does not match asserted type `@Todo`']
Line 24: Unexpected errors ['specialtypes_sentinels.py:24:30: error[invalid-type-form] Variable of type `Sentinel` is not allowed in a type expression']
Line 26: Unexpected errors ['specialtypes_sentinels.py:26:20: error[invalid-type-form] Variable of type `Sentinel` is not allowed in a parameter annotation']
Line 28: Unexpected errors ['specialtypes_sentinels.py:28:9: error[type-assertion-failure] Type `(int & Sentinel) | (Unknown & Sentinel)` does not match asserted type `@Todo`']
Line 30: Unexpected errors ['specialtypes_sentinels.py:30:9: error[type-assertion-failure] Type `int | Unknown` does not match asserted type `int`']
"""
output = """
specialtypes_sentinels.py:14:11: error[invalid-parameter-default] Default value of type `Sentinel` is not assignable to annotated parameter type `int`
specialtypes_sentinels.py:20:20: error[invalid-type-form] Variable of type `Sentinel` is not allowed in a parameter annotation
specialtypes_sentinels.py:20:30: error[invalid-type-form] Variable of type `Sentinel` is not allowed in a parameter annotation
specialtypes_sentinels.py:22:9: error[type-assertion-failure] Type `(int & Sentinel) | (Unknown & Sentinel)` does not match asserted type `@Todo`
specialtypes_sentinels.py:24:30: error[invalid-type-form] Variable of type `Sentinel` is not allowed in a type expression
specialtypes_sentinels.py:26:20: error[invalid-type-form] Variable of type `Sentinel` is not allowed in a parameter annotation
specialtypes_sentinels.py:28:9: error[type-assertion-failure] Type `(int & Sentinel) | (Unknown & Sentinel)` does not match asserted type `@Todo`
specialtypes_sentinels.py:30:9: error[type-assertion-failure] Type `int | Unknown` does not match asserted type `int`
"""
28 changes: 28 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,28 @@
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 "tests.specialtypes_sentinels.MISSING" is not valid as a type [valid-type]', 'specialtypes_sentinels.py:20: error: Variable "tests.specialtypes_sentinels.SPECIAL" is not valid as a type [valid-type]']
Line 22: Unexpected errors ['specialtypes_sentinels.py:22: error: Variable "tests.specialtypes_sentinels.MISSING" is not valid as a type [valid-type]']
Line 24: Unexpected errors ['specialtypes_sentinels.py:24: error: Variable "tests.specialtypes_sentinels.SPECIAL" is not valid as a type [valid-type]']
Line 26: Unexpected errors ['specialtypes_sentinels.py:26: error: Variable "tests.specialtypes_sentinels.IN_CLASS" is not valid as a type [valid-type]']
Line 28: Unexpected errors ['specialtypes_sentinels.py:28: error: Variable "tests.specialtypes_sentinels.IN_CLASS" is not valid as a type [valid-type]']
Line 30: Unexpected errors ['specialtypes_sentinels.py:30: error: Expression is of type "int | Any", not "int" [misc]']
"""
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 "tests.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 "tests.specialtypes_sentinels.SPECIAL" 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:22: error: Variable "tests.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 "tests.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 "tests.specialtypes_sentinels.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: Variable "tests.specialtypes_sentinels.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
specialtypes_sentinels.py:30: error: Expression is of type "int | Any", not "int" [misc]
"""
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