Add experimental support for PEP 661 (Sentinels)

[erictraut]

PEP 661 was deferred from Python 3.14, but the Sentinel type was recently added to typing_extensions for experimental usage.

[erictraut]

This is addressed in pyright 1.1.402.

[fleming79]

Hi Thanks for providing this so quickly. As a piece of feedback I see an error when the sentinel is used for typing function parameters as shown in the screenshot below.

from typing_extensions import Sentinel

sentinel = Sentinel("sentinel")


def my_func(value: sentinel = sentinel):
    pass

I'm using pylance 2025.6.103 which has pyright 1.1.403.

[erictraut]

@fleming79, you need to set enableExperimentalFeatures to true if you want to use this feature. If you do that, it should work as you expect.

[fleming79]

Perfect - thank you.

[aolieman]

Thank you, I've been eager to use Sentinel in my projects.

There's some unexpected behavior in this implementation regarding the sentinel naming. There seems to be a requirement that the sentinel has an uppercased name. I'm not sure where this requirement originates.

Code sample in pyright playground

from dataclasses import dataclass
from typing_extensions import Sentinel


MISSING = Sentinel("MISSING")
Empty = Sentinel("Empty")


@dataclass
class Address:
    email: str
    name: str | None


def update_not_missing(
    address: Address, 
    email: str | MISSING, 
    name: str | None | MISSING
) -> None:
    if email is not MISSING:
        address.email = email
    if name is not MISSING:
        address.name = name


def update_not_empty(
    address: Address, 
    email: str | Empty, 
    name: str | None | Empty
) -> None:
    if email is not Empty:
        address.email = email
    if name is not Empty:
        address.name = name

[erictraut]

@aolieman, thanks for trying out the feature. The reason it works for you when you use an all-caps name is that pyright treats variables with all-caps names as a constant and prevents them from being reassigned. This is generally important for x is y and x is not y narrowing. However, in the case of sentinels, this constant requirement isn't needed for soundness.

Could you please file a bug report so this is tracked?

In the meantime, you can work around the issue by using a Final type qualifier.

Empty: Final = Sentinel("Empty")

[amacfie-tc]

There are some issues reported by Pydantic users: pydantic/pydantic#12090 (comment)

class Foo(BaseModel):
    name: str | MISSING = MISSING # This is fine


foo = Foo.model_validate({})
reveal_type(foo.name)  # Type is str | Unknown

if not isinstance(foo.name, MISSING):  # Doesnt work
    foo.name

if foo.name is MISSING:
    reveal_type(foo.name) # Still str | Unknown
else:
    reveal_type(foo.name)  # Still str | Unknown

if foo.name is not MISSING:
    reveal_type(foo.name)  # Still str | Unknown