From 2ccb86697192c5769bf099eaea24eb51f1752349 Mon Sep 17 00:00:00 2001 From: nileshpatil6 Date: Tue, 1 Sep 2026 20:49:24 +0530 Subject: [PATCH 1/3] Do not narrow enum equality comparisons when member values are not statically known --- .../src/analyzer/typeGuards.ts | 62 +++++++++++++++---- .../src/tests/samples/enumNarrowing1.py | 62 ++++++++++++++++++- 2 files changed, 111 insertions(+), 13 deletions(-) diff --git a/packages/pyright-internal/src/analyzer/typeGuards.ts b/packages/pyright-internal/src/analyzer/typeGuards.ts index 10e8cfee7b2e..1368abd22c8a 100644 --- a/packages/pyright-internal/src/analyzer/typeGuards.ts +++ b/packages/pyright-internal/src/analyzer/typeGuards.ts @@ -2799,9 +2799,11 @@ function isPrimitiveBackedEnumAndPrimitive(enumType: ClassType, primitiveType: C } // If the specified type is a literal member of a primitive-backed enum class, -// returns the corresponding primitive literal type. Otherwise returns the type +// returns the corresponding primitive literal type. If the member's underlying +// primitive value is not known statically (e.g. it was assigned with auto() or +// a computed expression), returns undefined. Otherwise returns the type // unmodified. -function unwrapPrimitiveBackedEnumLiteral(classType: ClassType): ClassType { +function unwrapPrimitiveBackedEnumLiteral(classType: ClassType): ClassType | undefined { const literalValue = classType.priv.literalValue; if (!(literalValue instanceof EnumLiteral) || !isPrimitiveBackedEnumClass(classType)) { return classType; @@ -2812,18 +2814,24 @@ function unwrapPrimitiveBackedEnumLiteral(classType: ClassType): ClassType { return itemType; } - return classType; + return undefined; } // Determines whether two literal types compare equal using the `==` operator at // runtime. This differs from ClassType.isLiteralValueSame only for members of // primitive-backed enum classes, which compare equal to their underlying -// primitive values. -function isLiteralValueEqualAtRuntime(type1: ClassType, type2: ClassType): boolean { - return ClassType.isLiteralValueSame( - unwrapPrimitiveBackedEnumLiteral(type1), - unwrapPrimitiveBackedEnumLiteral(type2) - ); +// primitive values. Returns undefined if the result of the comparison cannot +// be determined statically because an enum member's underlying primitive +// value is unknown. +function isLiteralValueEqualAtRuntime(type1: ClassType, type2: ClassType): boolean | undefined { + const unwrappedType1 = unwrapPrimitiveBackedEnumLiteral(type1); + const unwrappedType2 = unwrapPrimitiveBackedEnumLiteral(type2); + + if (!unwrappedType1 || !unwrappedType2) { + return undefined; + } + + return ClassType.isLiteralValueSame(unwrappedType1, unwrappedType2); } // Attempts to narrow a type (make it more constrained) based on a comparison @@ -2865,6 +2873,14 @@ function narrowTypeForLiteralComparison( const literalValueMatches = isPrimitiveBackedEnumComparison ? isLiteralValueEqualAtRuntime(subtype, literalType) : ClassType.isLiteralValueSame(subtype, literalType); + + if (literalValueMatches === undefined) { + // The outcome of the comparison cannot be determined statically + // because an enum member's underlying primitive value is unknown, + // so no narrowing can be applied in either direction. + return subtype; + } + if (isPositiveTest) { return literalValueMatches ? subtype : undefined; } @@ -2888,8 +2904,28 @@ function narrowTypeForLiteralComparison( // to the primitive literal type. if (ClassType.isEnumClass(subtype)) { const allLiteralTypes = enumerateLiteralsForType(evaluator, subtype); - const match = allLiteralTypes?.find((type) => isLiteralValueEqualAtRuntime(type, literalType)); - return match ?? subtype; + + if (allLiteralTypes) { + let match: ClassType | undefined; + let isIndeterminate = false; + + for (const type of allLiteralTypes) { + const isEqual = isLiteralValueEqualAtRuntime(type, literalType); + if (isEqual === undefined) { + // The member's underlying primitive value is unknown, + // so it cannot be safely eliminated. + isIndeterminate = true; + } else if (isEqual && !match) { + match = type; + } + } + + if (!isIndeterminate && match) { + return match; + } + } + + return subtype; } // The reference type is the primitive type, so narrowing it to the @@ -2908,7 +2944,9 @@ function narrowTypeForLiteralComparison( return combineTypes( allLiteralTypes.filter((type) => isPrimitiveBackedEnumComparison - ? !isLiteralValueEqualAtRuntime(type, literalType) + ? // Eliminate a member only if it definitely compares equal; + // an indeterminate result must retain the member. + isLiteralValueEqualAtRuntime(type, literalType) !== true : !ClassType.isLiteralValueSame(type, literalType) ) ); diff --git a/packages/pyright-internal/src/tests/samples/enumNarrowing1.py b/packages/pyright-internal/src/tests/samples/enumNarrowing1.py index e1cd8b75894f..f9a28bed1042 100644 --- a/packages/pyright-internal/src/tests/samples/enumNarrowing1.py +++ b/packages/pyright-internal/src/tests/samples/enumNarrowing1.py @@ -1,7 +1,7 @@ # This sample tests type narrowing for equality (== and !=) comparisons # between IntEnum/StrEnum members and primitive literals or literal unions. -from enum import IntEnum, IntFlag, StrEnum +from enum import IntEnum, IntFlag, StrEnum, auto from typing import Literal, Union, assert_type class Priority(IntEnum): @@ -77,3 +77,63 @@ def test_plain_enum(e: Priority, y: int): # declared type rather than narrowing to the enum literal. if y == Priority.HIGH: assert_type(y, int) + + +def get_int() -> int: + return 30 + + +class AutoValue(IntEnum): + # The underlying primitive values of these members are not known + # statically, so equality comparisons with int literals cannot be + # used for narrowing in either direction. + RED = auto() + GREEN = auto() + + +class ComputedValue(IntEnum): + FIRST = get_int() + SECOND = 40 + + +def test_auto_member_equals_int_literal(): + v = AutoValue.RED + if v == 1: + # At runtime AutoValue.RED == 1 is True, so this branch is reachable. + assert_type(v, Literal[AutoValue.RED]) + else: + assert_type(v, Literal[AutoValue.RED]) + + +def test_int_var_equals_auto_member(x: Literal[1, 3]): + if x == AutoValue.RED: + # At runtime x == AutoValue.RED is True when x is 1, so this branch + # is reachable and x cannot be narrowed. + assert_type(x, Literal[1, 3]) + else: + assert_type(x, Literal[1, 3]) + + +def test_auto_enum_var_equals_int_literal(v: AutoValue): + if v == 1: + assert_type(v, AutoValue) + else: + assert_type(v, Literal[AutoValue.RED, AutoValue.GREEN]) + + +def test_computed_member_equals_int_literal(): + v = ComputedValue.FIRST + if v == 30: + # At runtime this branch is reachable when get_int() returns 30. + assert_type(v, Literal[ComputedValue.FIRST]) + else: + assert_type(v, Literal[ComputedValue.FIRST]) + + +def test_computed_enum_var_equals_int_literal(v: ComputedValue): + if v == 40: + # SECOND has a known value that matches, but FIRST's value is + # unknown and could also be 40, so no narrowing can occur. + assert_type(v, ComputedValue) + else: + assert_type(v, Literal[ComputedValue.FIRST]) From 50ff88706d2e2e62d7c1a300206a019bb1756028 Mon Sep 17 00:00:00 2001 From: nileshpatil6 Date: Tue, 1 Sep 2026 21:14:39 +0530 Subject: [PATCH 2/3] Add match statement regression cases for enum members with unknown values --- .../src/tests/samples/enumNarrowing1.py | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/packages/pyright-internal/src/tests/samples/enumNarrowing1.py b/packages/pyright-internal/src/tests/samples/enumNarrowing1.py index f9a28bed1042..ff864de4af82 100644 --- a/packages/pyright-internal/src/tests/samples/enumNarrowing1.py +++ b/packages/pyright-internal/src/tests/samples/enumNarrowing1.py @@ -137,3 +137,23 @@ def test_computed_enum_var_equals_int_literal(v: ComputedValue): assert_type(v, ComputedValue) else: assert_type(v, Literal[ComputedValue.FIRST]) + + +def test_match_int_literal_pattern(v: ComputedValue): + # A literal pattern goes through the same comparison. SECOND has a known + # value that matches, but FIRST's value is unknown and could be 40 too, + # so FIRST must survive into the matching case and the fallback. + match v: + case 40: + assert_type(v, ComputedValue) + case _: + assert_type(v, ComputedValue) + + +def test_match_auto_int_literal_pattern(v: AutoValue): + # Neither member's value is known, so a literal pattern narrows nothing. + match v: + case 1: + assert_type(v, AutoValue) + case _: + assert_type(v, AutoValue) From d70e5f60c353c0a61761bb4332bc70350f8932aa Mon Sep 17 00:00:00 2001 From: Bill Schnurr Date: Fri, 20 Nov 2026 11:39:46 -0700 Subject: [PATCH 3/3] Preserve safe precision for partially known enum values Class B: Pyright cannot determine values added or changed by dynamic enum hooks. Keep those comparisons conservative while retaining the possible literal members for standard enums and preserving TypeVar conditions. Treat nested unknown enum values as indeterminate. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../typeEvaluator/typeGuardNarrowing.ts | 128 +++++++ .../src/tests/samples/enumNarrowingSafety1.py | 315 ++++++++++++++++++ .../src/tests/typeEvaluator3.test.ts | 28 ++ 3 files changed, 471 insertions(+) create mode 100644 packages/pyright-internal/src/tests/samples/enumNarrowingSafety1.py diff --git a/packages/pyright-internal/src/analyzer/typeEvaluator/typeGuardNarrowing.ts b/packages/pyright-internal/src/analyzer/typeEvaluator/typeGuardNarrowing.ts index e5ba3c310261..4d90ae314a9f 100644 --- a/packages/pyright-internal/src/analyzer/typeEvaluator/typeGuardNarrowing.ts +++ b/packages/pyright-internal/src/analyzer/typeEvaluator/typeGuardNarrowing.ts @@ -2328,6 +2328,21 @@ function unwrapPrimitiveBackedEnumLiteral(classType: ClassType): ClassType | und const itemType = literalValue.itemType; if (isClassInstance(itemType) && itemType.priv.literalValue !== undefined) { + // A nested enum literal can still have an unknown underlying value. + let nestedType = itemType; + let recursionCount = 0; + while (nestedType.priv.literalValue instanceof EnumLiteral) { + if (recursionCount++ >= maxTypeRecursionCount) { + return undefined; + } + + const nestedValueType = nestedType.priv.literalValue.itemType; + if (!isClassInstance(nestedValueType) || nestedValueType.priv.literalValue === undefined) { + return undefined; + } + nestedType = nestedValueType; + } + return itemType; } @@ -2436,9 +2451,29 @@ export function narrowTypeForLiteralComparison( if (allLiteralTypes) { let match: ClassType | undefined; let isIndeterminate = false; + const possibleMatches: ClassType[] = []; + const primitiveClass = ClassType.isBuiltIn(literalType, 'int') ? 'int' : 'str'; for (const type of allLiteralTypes) { const isEqual = isLiteralValueEqualAtRuntime(type, literalType); + const valueType = + type.priv.literalValue instanceof EnumLiteral + ? type.priv.literalValue.itemType + : undefined; + const value = + valueType && isClassInstance(valueType) ? valueType.priv.literalValue : undefined; + // Nested or converted values cannot prove a nonmatch. + const isDefiniteNonmatch = + isEqual === false && + valueType !== undefined && + isClassInstance(valueType) && + ClassType.isBuiltIn(valueType, primitiveClass) && + (primitiveClass === 'int' + ? typeof value === 'number' || typeof value === 'bigint' + : typeof value === 'string'); + if (!isDefiniteNonmatch) { + possibleMatches.push(type); + } if (isEqual === undefined) { isIndeterminate = true; } else if (isEqual && !match) { @@ -2446,6 +2481,99 @@ export function narrowTypeForLiteralComparison( } } + if (isIndeterminate && possibleMatches.length < allLiteralTypes.length) { + if (ClassType.isEnumMemberSetMayBeIncomplete(subtype)) { + // Older typeshed versions mark IntEnum with @disjoint_base, + // which cannot add members to a direct subclass. + const baseClass = + subtype.shared.baseClasses.length === 1 + ? subtype.shared.baseClasses[0] + : undefined; + const declaration = subtype.shared.declaration; + const metaclass = subtype.shared.effectiveMetaclass; + if ( + !baseClass || + !isClass(baseClass) || + !ClassType.isBuiltIn(baseClass, 'enum.IntEnum') || + !ClassType.isEnumMemberSetMayBeIncomplete(baseClass) || + declaration?.node.nodeType !== ParseNodeType.Class || + declaration.node.d.decorators.length > 0 || + !metaclass || + !isInstantiableClass(metaclass) || + !ClassType.isBuiltIn(metaclass, ['EnumMeta', 'EnumType']) + ) { + return subtype; + } + } + + if (!hasStandardEnumConstruction(subtype)) { + return subtype; + } + + // Class creation hooks can add members after static enumeration. + const subclassHook = lookUpClassMember( + subtype, + '__init_subclass__', + MemberAccessFlags.SkipObjectBaseClass + ); + if ( + subclassHook && + (!isClass(subclassHook.classType) || !ClassType.isBuiltIn(subclassHook.classType)) + ) { + return subtype; + } + + for (const methodName of ['__eq__', '__ne__']) { + const member = lookUpObjectMember( + subtype, + methodName, + MemberAccessFlags.SkipObjectBaseClass | MemberAccessFlags.SkipInstanceMembers + ); + if ( + !member || + !isClass(member.classType) || + !ClassType.isBuiltIn(member.classType, primitiveClass) + ) { + return subtype; + } + } + + for (const symbol of ClassType.getSymbolTable(subtype).values()) { + const memberType = evaluator.getEffectiveTypeOfSymbol(symbol); + if ( + someSubtypes(memberType, (type) => { + if (isAnyOrUnknown(type)) { + return true; + } + if (isClass(type)) { + if (TypeBase.isInstance(type)) { + if ( + ClassType.isBuiltIn(type, primitiveClass) || + ClassType.isBuiltIn(type, 'bool') || + (type.priv.literalValue instanceof EnumLiteral && + ClassType.isSameGenericClass(type, subtype)) + ) { + return false; + } + return !!lookUpObjectMember(type, '__set_name__'); + } + const metaclass = type.shared.effectiveMetaclass; + return ( + !metaclass || + !isClass(metaclass) || + !!lookUpClassMember(metaclass, '__set_name__') + ); + } + return false; + }) + ) { + return subtype; + } + } + + return addConditionToType(combineTypes(possibleMatches), getTypeCondition(subtype)); + } + if (!isIndeterminate && match) { return match; } diff --git a/packages/pyright-internal/src/tests/samples/enumNarrowingSafety1.py b/packages/pyright-internal/src/tests/samples/enumNarrowingSafety1.py new file mode 100644 index 000000000000..45d27d0a8b76 --- /dev/null +++ b/packages/pyright-internal/src/tests/samples/enumNarrowingSafety1.py @@ -0,0 +1,315 @@ +from enum import EnumType, IntEnum, IntFlag, StrEnum, unique +from typing import Any, Literal, TypeVar, assert_type + + +def number() -> int: + return 7 + + +def text() -> str: + return "a" + + +class Mixed(IntEnum): + ONE = 1 + COMPUTED = number() + THREE = 3 + + +class MixedText(StrEnum): + ALPHA = "a" + COMPUTED = text() + GAMMA = "c" + + +class Source(IntEnum): + VALUE = number() + + +class Nested(IntEnum): + VALUE = Source.VALUE + + +class StringSource(StrEnum): + VALUE = text() + + +class StringNested(StrEnum): + VALUE = StringSource.VALUE + + +class KnownSource(IntEnum): + VALUE = 7 + + +class KnownNested(IntEnum): + VALUE = KnownSource.VALUE + + +class BooleanValue(IntEnum): + COMPUTED = number() + TRUE = True + THREE = 3 + + +@unique +class Decorated(IntEnum): + ONE = 1 + COMPUTED = number() + THREE = 3 + + +class CustomEq(IntEnum): + ONE = 1 + COMPUTED = number() + THREE = 3 + + def __eq__(self, value: object) -> bool: + return (int(self) == 3 and value == 1) or bool(int.__eq__(self, value)) + + __hash__ = int.__hash__ + + +class CustomNe(IntEnum): + ONE = 1 + COMPUTED = number() + THREE = 3 + + def __ne__(self, value: object) -> bool: + return not (int(self) == 3 and value == 1) and bool(int.__ne__(self, value)) + + +class CustomNew(IntEnum): + def __new__(cls, raw: int): + value = 10 if raw == 1 else 1 if raw == 3 else raw + member = int.__new__(cls, value) + member._value_ = value + return member + + ONE = 1 + COMPUTED = number() + THREE = 3 + + +class Flag(IntFlag): + ONE = 1 + TWO = 2 + + +def accept_possible(value: Literal[Mixed.ONE, Mixed.COMPUTED]) -> None: + pass + + +def accept_one(value: Literal[Mixed.ONE]) -> None: + pass + + +def accept_text(value: Literal[MixedText.ALPHA, MixedText.COMPUTED]) -> None: + pass + + +def test_mixed(value: Mixed) -> None: + if value == 1: + assert_type(value, Literal[Mixed.ONE, Mixed.COMPUTED]) + accept_possible(value) + accept_one(value) # This should generate an error. + else: + assert_type(value, Literal[Mixed.COMPUTED, Mixed.THREE]) + + +def test_inequality(value: Mixed) -> None: + if value != 1: + assert_type(value, Literal[Mixed.COMPUTED, Mixed.THREE]) + else: + assert_type(value, Literal[Mixed.ONE, Mixed.COMPUTED]) + accept_possible(value) + + +def test_unknown_match_only(value: Mixed) -> None: + if value == 9: + assert_type(value, Literal[Mixed.COMPUTED]) + + +def test_text(value: MixedText) -> None: + if value == "a": + assert_type(value, Literal[MixedText.ALPHA, MixedText.COMPUTED]) + accept_text(value) + else: + assert_type(value, Literal[MixedText.COMPUTED, MixedText.GAMMA]) + + +def test_nested(value: Literal[Nested.VALUE]) -> int: + if value == 7: + assert_type(value, Literal[Nested.VALUE]) + return "reachable" # This should generate an error. + assert_type(value, Literal[Nested.VALUE]) + return 0 + + +def test_nested_text(value: Literal[StringNested.VALUE]) -> int: + if value == "a": + assert_type(value, Literal[StringNested.VALUE]) + return "reachable" # This should generate an error. + assert_type(value, Literal[StringNested.VALUE]) + return 0 + + +def test_reverse_nested(flag: bool) -> int: + value = 7 if flag else 9 + if value == Nested.VALUE: + assert_type(value, Literal[7, 9]) + return "reachable" # This should generate an error. + assert_type(value, Literal[7, 9]) + return 0 + + +def test_known_nested_nonmatch(value: Literal[KnownNested.VALUE]) -> int: + if value == 9: + return "unreachable" + return 0 + + +def test_boolean_value(value: BooleanValue) -> None: + if value == 1: + assert_type(value, Literal[BooleanValue.COMPUTED, BooleanValue.TRUE]) + + +def test_decorated(value: Decorated) -> None: + if value == 1: + assert_type(value, Decorated) + + +def test_custom_equality(value: CustomEq) -> None: + if value == 1: + assert_type(value, CustomEq) + + +def test_custom_inequality(value: CustomNe) -> None: + if value != 1: + pass + else: + assert_type(value, CustomNe) + + +def test_custom_construction(value: CustomNew) -> None: + if value == 1: + assert_type(value, CustomNew) + + +def test_flag(value: Flag) -> None: + if value == 1: + assert_type(value, Flag) + else: + assert_type(value, Flag) + + +class DeepNested(IntEnum): + VALUE = Nested.VALUE + + +class KnownOne(IntEnum): + VALUE = 1 + + +class NestedAndUnknown(IntEnum): + COMPUTED = number() + NESTED = KnownOne.VALUE + THREE = 3 + + +class CustomMeta(EnumType): + pass + + +class MetaEnum(IntEnum, metaclass=CustomMeta): + ONE = 1 + COMPUTED = number() + THREE = 3 + + +def test_deep_nested(value: Literal[DeepNested.VALUE]) -> int: + if value == 7: + return "reachable" # This should generate an error. + return 0 + + +def test_nested_member(value: NestedAndUnknown) -> None: + if value == 1: + assert_type(value, Literal[NestedAndUnknown.COMPUTED, NestedAndUnknown.NESTED]) + + +def test_custom_metaclass(value: MetaEnum) -> None: + if value == 1: + assert_type(value, MetaEnum) + + +def register_dynamic(owner: Any) -> None: + value = int.__new__(owner, 1) + value._name_ = "DYNAMIC" + value._value_ = 1 + owner._member_map_["DYNAMIC"] = value + owner._value2member_map_[1] = value + owner._member_names_.append("DYNAMIC") + + +class HookBase(IntEnum): + def __init_subclass__(cls) -> None: + super().__init_subclass__() + register_dynamic(cls) + + +class HookEnum(HookBase): + ONE = 1 + COMPUTED = number() + THREE = 3 + + +class Register: + def __get__(self, instance: object, owner: object) -> object: + return self + + def __set_name__(self, owner: Any, name: str) -> None: + register_dynamic(owner) + + +class DescriptorEnum(IntEnum): + ONE = 1 + COMPUTED = number() + THREE = 3 + hook = Register() + + +def accept_hook(value: Literal[HookEnum.ONE, HookEnum.COMPUTED]) -> None: + pass + + +def accept_descriptor(value: Literal[DescriptorEnum.ONE, DescriptorEnum.COMPUTED]) -> None: + pass + + +def test_subclass_hook(value: HookEnum) -> None: + if value == 1: + assert_type(value, HookEnum) + accept_hook(value) # This should generate an error. + + +def test_descriptor_hook(value: DescriptorEnum) -> None: + if value == 1: + assert_type(value, DescriptorEnum) + accept_descriptor(value) # This should generate an error. + + +T = TypeVar("T", bound=Mixed) +C = TypeVar("C", Literal[Mixed.ONE], Literal[Mixed.COMPUTED], Literal[Mixed.THREE]) + + +def test_bound_typevar(value: T) -> T: + if value == 1: + return value + raise ValueError() + + +def test_constrained_typevar(value: C) -> C: + if value == 1: + return value + return value diff --git a/packages/pyright-internal/src/tests/typeEvaluator3.test.ts b/packages/pyright-internal/src/tests/typeEvaluator3.test.ts index ee984e04692f..51e89649b5a1 100644 --- a/packages/pyright-internal/src/tests/typeEvaluator3.test.ts +++ b/packages/pyright-internal/src/tests/typeEvaluator3.test.ts @@ -1214,6 +1214,34 @@ test('EnumNarrowing1', () => { TestUtils.validateResults(analysisResults, 0); }); +test.each([ + { name: 'default', pythonVersion: undefined }, + { name: 'Python 3.11', pythonVersion: pythonVersion3_11 }, +])('EnumNarrowingSafety1 $name', ({ pythonVersion }) => { + const configOptions = new ConfigOptions(Uri.empty()); + if (pythonVersion) { + configOptions.defaultPythonVersion = pythonVersion; + } + + const analysisResults = TestUtils.typeAnalyzeSampleFiles(['enumNarrowingSafety1.py'], configOptions); + + TestUtils.validateResults(analysisResults, 7); + expect( + analysisResults[0].errors + .slice() + .sort((a, b) => a.range.start.line - b.range.start.line) + .map((diagnostic) => [diagnostic.range.start.line + 1, diagnostic.getRule()]) + ).toEqual([ + [115, DiagnosticRule.reportArgumentType], + [144, DiagnosticRule.reportReturnType], + [152, DiagnosticRule.reportReturnType], + [161, DiagnosticRule.reportReturnType], + [232, DiagnosticRule.reportReturnType], + [293, DiagnosticRule.reportArgumentType], + [299, DiagnosticRule.reportArgumentType], + ]); +}); + test('EnumNarrowing2', () => { const analysisResults = TestUtils.typeAnalyzeSampleFiles(['enumNarrowing2.py']);