Skip to content

Commit 9798e88

Browse files
[ty] Preserve enum exhaustiveness with custom _missing_ methods (#27700)
## Summary Previously, we treated enums that override `_missing_` as non-exhaustive because those methods can manufacture undeclared enum members. ```python from enum import Enum from typing import assert_never class Color(Enum): RED = 1 BLUE = 2 @classmethod def _missing_(cls, value: object) -> "Color": return cls.RED def handle(color: Color) -> None: match color: case Color.RED | Color.BLUE: pass case _: assert_never(color) ``` We now ignore `_missing_` when determining enum exhaustiveness, matching mypy and Pyright. Any code can construct undeclared enum instances with `object.__new__`, so `_missing_` is not a meaningful boundary. `Flag` classes remain non-exhaustive. Closes astral-sh/ty#4241.
1 parent 5b2ed0d commit 9798e88

3 files changed

Lines changed: 93 additions & 37 deletions

File tree

‎crates/ty_python_semantic/resources/mdtest/exhaustiveness_checking.md‎

Lines changed: 37 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -283,7 +283,11 @@ def match_non_exhaustive(x: Color):
283283
assert_never(x) # error: [type-assertion-failure]
284284
```
285285

286-
Matching every named member is not exhaustive for enums that can also have unnamed members.
286+
Matching every named member is not exhaustive for `Flag` classes.
287+
288+
Custom `_missing_` methods technically could create a new undeclared member via `object.__new__`,
289+
but this is also possible outside a `_missing_` method. We choose to in general ignore this
290+
possibility; we don't assume that a `_missing_` method will do this.
287291

288292
```py
289293
from enum import Enum, Flag
@@ -296,19 +300,49 @@ class MissingValueEnum(Enum):
296300

297301
@classmethod
298302
def _missing_(cls, value: object) -> "MissingValueEnum":
299-
return object.__new__(cls)
303+
return cls.ONLY
300304

301305
def match_flag(value: Permission) -> int: # error: [invalid-return-type]
302306
match value:
303307
case Permission.READ:
304308
return 1
305309

306-
def match_open_enum(value: MissingValueEnum) -> int: # error: [invalid-return-type]
310+
def match_custom_missing_enum(value: MissingValueEnum) -> int:
307311
match value:
308312
case MissingValueEnum.ONLY:
309313
return 1
310314
```
311315

316+
## Checks on enums with custom missing methods
317+
318+
An enum remains exhaustive when it overrides `_missing_`, even if its value comes from a function
319+
with the enum as its return type.
320+
321+
```py
322+
from enum import Enum
323+
from typing import assert_never
324+
325+
class FallbackColor(Enum):
326+
RED = 1
327+
BLUE = 2
328+
329+
@classmethod
330+
def _missing_(cls, value: object) -> "FallbackColor":
331+
return FallbackColor.RED
332+
333+
def get_color() -> FallbackColor:
334+
return FallbackColor.BLUE
335+
336+
color = get_color()
337+
match color:
338+
case FallbackColor.RED:
339+
pass
340+
case FallbackColor.BLUE:
341+
pass
342+
case _:
343+
assert_never(color)
344+
```
345+
312346
## Checks on enum literal subsets
313347

314348
```py

‎crates/ty_python_semantic/resources/mdtest/narrow/conditionals/eq.md‎

Lines changed: 53 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -312,8 +312,8 @@ def compare_functional_flags(left: FunctionalPermission, right: FunctionalPermis
312312
reveal_type(left == right) # revealed: bool
313313
```
314314

315-
An enum with a custom `_missing_` method can create unnamed members, so two values need not be equal
316-
even when only one member is declared:
315+
A custom `_missing_` method does not change the enum's static member set, so an enum with one
316+
declared member remains a singleton:
317317

318318
```py
319319
from enum import Enum
@@ -323,13 +323,13 @@ class MissingValueEnum(Enum):
323323

324324
@classmethod
325325
def _missing_(cls, value: object) -> "MissingValueEnum":
326-
return object.__new__(cls)
326+
return cls.ONLY
327327

328-
def compare_open_enums(left: MissingValueEnum, right: MissingValueEnum):
329-
reveal_type(left == right) # revealed: bool
328+
def compare_custom_missing_enums(left: MissingValueEnum, right: MissingValueEnum):
329+
reveal_type(left == right) # revealed: Literal[True]
330330

331331
if left != right:
332-
reveal_type(left) # revealed: MissingValueEnum
332+
reveal_type(left) # revealed: Never
333333
```
334334

335335
A custom enum metaclass can add members that do not appear in the class body. Two values of a
@@ -662,24 +662,40 @@ def compare_false_to_integer_enum(left: MixedLeft1 | Literal[False], right: Mixe
662662
reveal_type(right) # revealed: Literal[MixedRight0.A]
663663
```
664664

665-
An open identity-comparing enum can still be narrowed to all of its declared members. Undeclared
666-
runtime members are not retained merely because every declared member matches:
665+
An identity-comparing enum with a custom `_missing_` method remains equivalent to the union of its
666+
declared members:
667667

668668
```py
669669
from enum import Enum
670670
from typing import Literal
671671

672-
class OpenIdentity(Enum):
672+
class CustomMissingIdentity(Enum):
673673
A = "a"
674674
B = "b"
675675

676676
@classmethod
677-
def _missing_(cls, value: object) -> "OpenIdentity":
677+
def _missing_(cls, value: object) -> "CustomMissingIdentity":
678678
raise ValueError
679679

680680
class OtherIdentity(Enum):
681681
C = "c"
682682

683+
def compare_custom_missing_identity(
684+
left: CustomMissingIdentity | OtherIdentity,
685+
right: Literal[CustomMissingIdentity.A, CustomMissingIdentity.B],
686+
):
687+
if left == right:
688+
reveal_type(left) # revealed: CustomMissingIdentity
689+
```
690+
691+
A metaclass can inject undeclared members, leaving an identity-comparing enum genuinely open.
692+
Comparing against its declared members can still exclude those undeclared members.
693+
694+
```py
695+
class OpenIdentity(Enum, metaclass=InjectingEnumMeta):
696+
A = "a"
697+
B = "b"
698+
683699
def compare_open_identity(
684700
left: OpenIdentity | OtherIdentity,
685701
right: Literal[OpenIdentity.A, OpenIdentity.B],
@@ -709,7 +725,8 @@ reveal_type(IntegerAliases.ZERO == IntegerAliases.FALSE) # revealed: Literal[Tr
709725
```
710726

711727
Plain enum members from different classes use identity comparison, even when their declared values
712-
are equal. Custom comparison methods and open scalar enums remain ambiguous:
728+
are equal. Custom comparison methods remain ambiguous, while scalar enums can compare across enum
729+
classes:
713730

714731
```py
715732
from enum import Enum, StrEnum
@@ -746,13 +763,25 @@ class CustomNeLeft(StrEnum):
746763
reveal_type(CustomNeLeft.MEMBER == CustomRight.MEMBER) # revealed: Literal[True]
747764
reveal_type(CustomNeLeft.MEMBER != CustomRight.MEMBER) # revealed: bool
748765

749-
class OpenLeft(StrEnum):
766+
class CustomMissingLeft(StrEnum):
750767
MEMBER = "shared"
751768

752769
@classmethod
753-
def _missing_(cls, value: object) -> "OpenLeft":
770+
def _missing_(cls, value: object) -> "CustomMissingLeft":
754771
raise ValueError
755772

773+
def compare_custom_missing(left: CustomMissingLeft, right: CustomRight):
774+
if left == right:
775+
reveal_type(left) # revealed: CustomMissingLeft
776+
```
777+
778+
A metaclass can add undeclared scalar members, so cross-enum comparison must retain the full open
779+
enum:
780+
781+
```py
782+
class OpenLeft(StrEnum, metaclass=InjectingEnumMeta):
783+
MEMBER = "shared"
784+
756785
def compare_open(left: OpenLeft, right: CustomRight):
757786
if left == right:
758787
reveal_type(left) # revealed: OpenLeft
@@ -766,8 +795,17 @@ def compare_optional_custom(left: CustomLeft | None, right: CustomRight):
766795
reveal_type(left) # revealed: CustomLeft
767796
```
768797

769-
An enum with `_missing_` may have members that do not appear in its definition. Adding `None` must
770-
not cause the comparison to assume that its declared member is the only possible match:
798+
A custom `_missing_` method does not affect comparison narrowing, including when the enum is
799+
combined with `None`:
800+
801+
```py
802+
def compare_optional_custom_missing(left: CustomMissingLeft | None, right: CustomRight):
803+
if left == right:
804+
reveal_type(left) # revealed: CustomMissingLeft
805+
```
806+
807+
Undeclared members of a genuinely open scalar enum must survive cross-enum comparison even when the
808+
enum is combined with `None`:
771809

772810
```py
773811
def compare_optional_open(left: OpenLeft | None, right: CustomRight):

‎crates/ty_python_semantic/src/types/enums.rs‎

Lines changed: 3 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -311,9 +311,8 @@ pub struct EnumClassLiteral<'db> {
311311
pub(super) aliases_are_known: bool,
312312
/// Whether the canonical members exhaust the runtime values of this enum class.
313313
///
314-
/// `Flag` classes, transforming metaclasses, and enums with a custom `_missing_` method can
315-
/// create runtime members beyond those declared in the class body, so their declared members
316-
/// are not a closed value set.
314+
/// `Flag` classes and transforming metaclasses can create runtime members beyond those
315+
/// declared in the class body, so their declared members are not a closed value set.
317316
#[returns(copy)]
318317
pub(crate) members_are_exhaustive: bool,
319318
}
@@ -354,8 +353,7 @@ fn enum_class_literal<'db>(
354353
db,
355354
&env,
356355
KnownClass::Flag.to_subclass_of(db, &env),
357-
)
358-
&& !enum_has_custom_missing(db, class);
356+
);
359357

360358
Some(EnumClassLiteral::new(
361359
db,
@@ -367,20 +365,6 @@ fn enum_class_literal<'db>(
367365
))
368366
}
369367

370-
/// Return whether enum construction may create pseudo-members through a custom `_missing_` method.
371-
fn enum_has_custom_missing<'db>(db: &'db dyn Db, class: ClassLiteral<'db>) -> bool {
372-
let ClassLiteral::Static(class) = class else {
373-
return false;
374-
};
375-
376-
class
377-
.iter_mro(db, None)
378-
.filter_map(ClassBase::into_class)
379-
.take_while(|base| base.known(db) != Some(KnownClass::Enum))
380-
.filter_map(|base| base.class_literal(db).as_static())
381-
.any(|base| custom_enum_method(db, base.body_scope(db), "_missing_").is_some())
382-
}
383-
384368
impl<'db> EnumClassLiteral<'db> {
385369
pub(crate) fn member_count(self, db: &'db dyn Db) -> usize {
386370
self.members(db).len()

0 commit comments

Comments
 (0)