Add Sentinel support (PEP-661) by hrolfurgylfa · Pull Request #3575 · facebook/pyrefly

hrolfurgylfa · 2026-05-25T15:39:18Z

Summary

This PR adds support for PEP 661 Sentinel types.

Test Plan

I've run this as an LSP for a bit on a bigger private repo and it seems to work, but the main testing was the tests added to test/narrow.rs and test/sentinel.rs.

Some assumptions/things I didn't fully understand and might deserve more attention:

I'm using NestingContext::toplevel() when creating a Sentinel struct, this is similar to TypeVar/TypeAlias/a few others, I left the same TODO in place as they had. I looked through some of the other types and couldn't find any other way it was being done, so I left it like this for now, but if anyone has any pointers to how it should be done better, please let me know and I can fix it.
For the cinderx support, I added the sentinel to it in the TODO section of variables that get set to Any. I haven't really diven into what cinderx is and how the support for it is implemented, but if it is important to get it working I can go ahead and look into that.
I'm using bind_legacy_type_var_or_typing_alias to bind the Sentinel type, I think this should be ok as the PEP is pretty strict in how it can be assigned. I've done some testing and only found one edge case so far that fails because of this, but I don't think Final's should be mixed with Sentinel objects like this anyway, here is the test case that fails:

from typing import Any, Final
from typing_extensions import Sentinel

MISSING: Final[Any]
MISSING = Sentinel("MISSING")

It fails because the Final doesn't notice the assignment, it still thinks the variable was never assigned to.

Status

This PR is mostly ready for review, but I'm keeping it in Draft form until #3562 is addressed, since until then I can't finalize Python 3.15 support.

meta-cla · 2026-05-25T15:39:25Z

Hi @hrolfurgylfa!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at cla@meta.com. Thanks!

meta-cla · 2026-05-25T18:35:27Z

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

yangdanny97 · 2026-05-29T02:58:26Z

Thanks for the PR, wow! that was fast, the PEP just got accepted recently and the conformance tests haven't even been added yet

I see you added lots of tests already, but maybe worth looking at the proposed conformance test to see if there's anything missing
https://github.com/python/typing/pull/2277/changes

I can give this a more detailed review once I've unblocked you on #3562

hrolfurgylfa · 2026-05-29T21:20:45Z

Thanks, I didn't know those conformance tests existed, I'll review those once I get back home after the weekend, don't have my laptop with me.

And yeah, a proper review should probably be held until I can add the Python 3.15 support, since there is a bit of extra code to differentiate sentinel lowercase builtin and Sentinel uppercase from typing extensions, might be adding another 30-50 lines, don't remember the exact number though.

I'm hoping to have both of those ready on Tuesday/Wednesday evening (UTC+0).

yangdanny97 · 2026-05-29T23:08:45Z

No rush at all. The typeshed update just got merged, so once you rebase it should be there

This seems to be what is being decided in the python typing spec, see the PR description: python/typing#2277 Although some typecheckers, like pyright, still have the old behaviour recommended in the PEP of giving an error when a different name is assigned.

hrolfurgylfa · 2026-06-04T20:24:37Z

This PR should now be ready for review.

It now passes the conformance tests, the only change was just no longer emit an error when a sentinel is assigned to a variable with a different name like MISSING = sentinel("<MISSING>"). This is something the PEP prohibited but in the open conformance PR to python/typing that prohibition was lifted, so type checkers are no longer supposed to emit an error there.

I'm still not perfectly sure on the query interface and tsp implementation for sentinel, I haven't really figured out how to test the tsp stuff properly and while I have looked at the output of the shape query with sentinels I'm not perfectly sure how it should look, as such I haven't added any automated tests for it.

This is necessary as some properties, like __name__, are only available on the builtin sentinel, not the typing_extensions Sentienl type. This can be confirmed by running the following: ``` uv run -p 3.15 --with 'typing_extensions' python -c 'from typing_extensions import Sentinel; MISSING = Sentinel("MISSING"); print(MISSING.__name__)' > Traceback (most recent call last): > File "<string>", line 1, in <module> > from typing_extensions import Sentinel; MISSING = Sentinel("MISSING"); MISSING.__name__ > ^^^^^^^^^^^^^^^^ > AttributeError: 'Sentinel' object has no attribute '__name__'. Did you mean '.__ne__' instead of '.__name__'? uv run -p 3.15 --with 'typing_extensions' python -c 'MISSING = sentinel("MISSING"); print(MISSING.__name__)' > MISSING ```

rchen152

Thank you for the PR! This is great. I left a few comments, mostly minor. The one larger question I have is whether we can drop the distinction between builtins.sentinel and typing_extensions.Sentinel, which seems like it would simplify the code a fair bit if we can get away with it.

rchen152 · 2026-06-06T09:22:45Z

            type_var_tuple: lookup_concrete(standardised(3, 11), "TypeVarTuple"),
            type_alias_type: lookup_concrete(standardised(3, 12), "TypeAliasType"),
+            // sentinel: lookup_concrete(typing_extensions, "Sentinel"),
+            sentinel_builtin: lookup_concrete(builtins, "sentinel"),


How different are builtins.sentinel and typing_extensions.Sentinel? If they're pretty similar, I'd suggest combining them into just one sentinel, which is looked up from builtins in 3.15+ and from typing_extensions otherwise, and modifying the rest of the PR to likewise stop tracking the distinction between the two.

In general, we treat the typing and typing_extensions versions of things as the same without worrying about the minor differences between their runtime definitions. And distinguishing between builtins.sentinel and typing_extensions.Sentinel seems to be adding a fair bit of complexity to this PR.

The main reason I differentiated between the two was the __name__ attribute that is only available on the builtins sentinel, not the typing extensions Sentinel. If we merge them it would mean that in Python 3.15+ pyrefly would say that accessing __name__ on typing_extensions Sentinel is allowed and returns a string, while raising a runtime error if run. If that is fine I can go ahead and remove this logic.

Here is how I confirmed this difference if you want to test it with the python 3.15 beta:

uv run -p 3.15 --with 'typing_extensions' python -c 'from typing_extensions import Sentinel; MISSING = Sentinel("MISSING"); print(MISSING.__name__)' > Traceback (most recent call last): > File "<string>", line 1, in <module> > from typing_extensions import Sentinel; MISSING = Sentinel("MISSING"); MISSING.__name__ > ^^^^^^^^^^^^^^^^ > AttributeError: 'Sentinel' object has no attribute '__name__'. Did you mean '.__ne__' instead of '.__name__'? uv run -p 3.15 --with 'typing_extensions' python -c 'MISSING = sentinel("MISSING"); print(MISSING.__name__)' > MISSING

Also, if this ends up being kept, I should probably add a comment explaining the reasoning better, and remove that commented out line, not sure how that one got past me.

Thanks for the explanation! If the presence/absence of the __name__ attribute is the main difference, then I'm in favor of merging them.

rchen152 · 2026-06-06T09:32:46Z

+    pub fn new(name: Identifier, module: Module, kind: SentinelKind) -> Self {
+        Self(ArcId::new(SentinelInner {
+            kind,
+            // TODO: properly take parent from caller of new()


You can grab the nesting context from the Scopes stack when constructing Binding::Sentinel - see comment in stmt.rs.

Thanks, fixed

rchen152 · 2026-06-06T09:43:30Z

+```python
+from typing_extensions import Sentinel
+
+# Sentinels must be assigned to a matching variable.


This doc example looks incorrect; the implementation (correctly) allows the name to not match the variable name.

Good catch, forgot to change this when I removed the error on different variable name, fixed

…name

… sentinel" This reverts commit b66942c.

github-actions · 2026-06-08T01:34:55Z

According to mypy_primer, this change doesn't affect type check results on a corpus of open source code. ✅

meta-codesync · 2026-06-08T21:29:32Z

@rchen152 has imported this pull request. If you are a Meta employee, you can view this in D107930625.

rchen152

Looks good, thank you! I'll get a second review and get this merged.

hrolfurgylfa · 2026-06-08T22:36:11Z

Thanks 😄

github-actions Bot added the size/xl label May 25, 2026

meta-cla Bot added the cla signed label May 25, 2026

yangdanny97 self-assigned this May 29, 2026

yangdanny97 requested a review from rchen152 May 29, 2026 02:58

hrolfurgylfa force-pushed the PEP-661-Sentinel branch from 4778b67 to a492972 Compare June 2, 2026 19:00

github-actions Bot added size/xl and removed size/xl labels Jun 2, 2026

hrolfurgylfa force-pushed the PEP-661-Sentinel branch from 47853ea to b1c8fbf Compare June 3, 2026 20:53

github-actions Bot added size/xl and removed size/xl labels Jun 3, 2026

hrolfurgylfa added 5 commits June 4, 2026 20:15

Add Sentinel support (PEP-661)

20f0070

BuiltinSentinel working

2553533

Rename Sentinel to lower case in error messages

d1ce26f

Add test to confirm sentinel in class body working

153d58a

hrolfurgylfa force-pushed the PEP-661-Sentinel branch from b1c8fbf to 1d894a2 Compare June 4, 2026 20:15

github-actions Bot added size/xl and removed size/xl labels Jun 4, 2026

hrolfurgylfa marked this pull request as ready for review June 4, 2026 20:24

hrolfurgylfa added 3 commits June 4, 2026 21:56

Move sentinel truthy test away from test/narrow.rs

26aad50

Move more sentinel references to lowercase

f766c28

hrolfurgylfa force-pushed the PEP-661-Sentinel branch from 1d894a2 to f766c28 Compare June 4, 2026 21:56

github-actions Bot added size/xl and removed size/xl labels Jun 4, 2026

rchen152 requested changes Jun 6, 2026

View reviewed changes

Fix sentinel nesting_context usage

bcce9c0

github-actions Bot added size/xl and removed size/xl labels Jun 6, 2026

Fix documentation to allow different sentinel first argument and var …

8418fca

…name

github-actions Bot added size/xl and removed size/xl labels Jun 6, 2026

Revert "Differentiate between typing_extensions Sentinel and builtins…

aad9898

… sentinel" This reverts commit b66942c.

github-actions Bot added size/xl and removed size/xl labels Jun 7, 2026

rchen152 approved these changes Jun 8, 2026

View reviewed changes

Conversation

hrolfurgylfa commented May 25, 2026

Summary

Test Plan

Some assumptions/things I didn't fully understand and might deserve more attention:

Status

Uh oh!

meta-cla Bot commented May 25, 2026

Action Required

Process

Uh oh!

meta-cla Bot commented May 25, 2026

Uh oh!

yangdanny97 commented May 29, 2026

Uh oh!

hrolfurgylfa commented May 29, 2026

Uh oh!

yangdanny97 commented May 29, 2026

Uh oh!

hrolfurgylfa commented Jun 4, 2026

Uh oh!

rchen152 left a comment

Choose a reason for hiding this comment

Uh oh!

rchen152 Jun 6, 2026

Choose a reason for hiding this comment

Uh oh!

hrolfurgylfa Jun 6, 2026

Choose a reason for hiding this comment

Uh oh!

rchen152 Jun 6, 2026

Choose a reason for hiding this comment

Uh oh!

rchen152 Jun 6, 2026

Choose a reason for hiding this comment

Uh oh!

hrolfurgylfa Jun 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rchen152 Jun 6, 2026

Choose a reason for hiding this comment

Uh oh!

hrolfurgylfa Jun 6, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jun 8, 2026

Uh oh!

meta-codesync Bot commented Jun 8, 2026

Uh oh!

rchen152 left a comment

Choose a reason for hiding this comment

Uh oh!

hrolfurgylfa commented Jun 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants