[ty] Preserve nominal type of enum.property instances (#25849)

## Summary

This is a follow-up to #25681 that preserves the nominal class of
synthesized property instances created by `enum.property`.

Previously, `PropertyInstanceType` always fell back to
`builtins.property`. That discarded the `enum.property` identity, so
assignments to `enum.property` failed and enum-specific members such as
`name`, `clsname`, and `member` were unavailable. The originating known
class is now retained through accessor replacement, type
transformations, member lookup, descriptor dispatch, relations, `super`,
and display.

The regression coverage also checks precise getter and setter behavior.
A TODO documents the remaining limitation that constructing a subclass
of `enum.property` currently collapses the result to `enum.property`.

## Test Plan

Added/updated mdtests.

Author: carljm

crates/ty_ide/src/completion.rs

@@ -4668,8 +4668,8 @@ Answer.<CURSOR>
                 NO :: Literal[Answer.NO]
                 YES :: Literal[Answer.YES]
                 mro :: bound method <class 'Answer'>.mro() -> list[type]
-                name :: property
-                value :: property
+                name :: enum.property
+                value :: enum.property
                 __annotations__ :: dict[str, Any]
                 __base__ :: type | None
                 __bases__ :: tuple[type, ...]

crates/ty_python_semantic/resources/mdtest/enums.md

@@ -725,6 +725,14 @@ class Answer(Enum):
     def some_property(self) -> str:
         return "property value"
 
+    @enum_property
+    def settable_property(self) -> int:
+        return 1
+
+    @settable_property.setter
+    def settable_property(self, value: str) -> None:
+        pass
+
     def direct_property_getter(self) -> int:
         return 1
 
@@ -734,6 +742,25 @@ class Answer(Enum):
 reveal_type(enum_members(Answer))
 assert_type(Answer.YES.some_property, str)
 assert_type(Answer.YES.direct_property, int)
+Answer.YES.some_property = "new value"  # error: [invalid-assignment]
+Answer.YES.settable_property = "new value"
+assert_type(Answer.YES.settable_property, int)
+Answer.YES.settable_property = 1  # error: [invalid-assignment]
+
+def get(value: Enum) -> str:
+    return value.name
+
+descriptor = enum_property(get)
+reveal_type(descriptor)  # revealed: enum.property
+# revealed: <method-wrapper '__get__' of enum.property 'get'>
+reveal_type(descriptor.__get__)
+retained: enum_property = descriptor
+retained_as_property: property = descriptor
+not_enum_property: enum_property = property(get)  # error: [invalid-assignment]
+retained_getter: enum_property = descriptor.getter(get)
+assert_type(descriptor.name, str)
+assert_type(descriptor.clsname, str)
+assert_type(descriptor.member, Enum | None)
 ```
 
 Enum attributes defined using `enum.property` take precedence over generated attributes.

crates/ty_python_semantic/src/types.rs

@@ -594,12 +594,13 @@ pub enum PropertyAccessorRole {
     Deleter,
 }
 
-/// Represents an instance of `builtins.property`.
-#[salsa::interned(debug, heap_size=ruff_memory_usage::heap_size)]
+/// Represents an instance of `builtins.property` or `enum.property`.
+#[salsa::interned(debug, constructor=new_internal, heap_size=ruff_memory_usage::heap_size)]
 pub struct PropertyInstanceType<'db> {
     pub getter: Option<Type<'db>>,
     pub setter: Option<Type<'db>>,
     pub deleter: Option<Type<'db>>,
+    instance_class: KnownClass,
 }
 
 fn walk_property_instance_type<'db, V: visitor::TypeVisitor<'db> + ?Sized>(
@@ -622,6 +623,38 @@ fn walk_property_instance_type<'db, V: visitor::TypeVisitor<'db> + ?Sized>(
 impl get_size2::GetSize for PropertyInstanceType<'_> {}
 
 impl<'db> PropertyInstanceType<'db> {
+    pub fn new(
+        db: &'db dyn Db,
+        getter: Option<Type<'db>>,
+        setter: Option<Type<'db>>,
+        deleter: Option<Type<'db>>,
+    ) -> Self {
+        Self::new_internal(db, getter, setter, deleter, KnownClass::Property)
+    }
+
+    fn new_enum_property(
+        db: &'db dyn Db,
+        getter: Option<Type<'db>>,
+        setter: Option<Type<'db>>,
+        deleter: Option<Type<'db>>,
+    ) -> Self {
+        Self::new_internal(db, getter, setter, deleter, KnownClass::EnumProperty)
+    }
+
+    fn with_accessors(
+        self,
+        db: &'db dyn Db,
+        getter: Option<Type<'db>>,
+        setter: Option<Type<'db>>,
+        deleter: Option<Type<'db>>,
+    ) -> Self {
+        Self::new_internal(db, getter, setter, deleter, self.instance_class(db))
+    }
+
+    fn instance_fallback(self, db: &'db dyn Db) -> Type<'db> {
+        self.instance_class(db).to_instance(db)
+    }
+
     /// Returns the [`PropertyAccessorRole`] that `def` plays in this property, or `None` when
     /// `def` is not one of this property's accessors.
     ///
@@ -669,7 +702,7 @@ impl<'db> PropertyInstanceType<'db> {
         let deleter = self
             .deleter(db)
             .map(|ty| ty.apply_type_mapping_impl(db, type_mapping, tcx, visitor));
-        Self::new(db, getter, setter, deleter)
+        self.with_accessors(db, getter, setter, deleter)
     }
 
     fn recursive_type_normalized_impl(
@@ -702,7 +735,7 @@ impl<'db> PropertyInstanceType<'db> {
             ),
             None => None,
         };
-        Some(Self::new(db, getter, setter, deleter))
+        Some(self.with_accessors(db, getter, setter, deleter))
     }
 
     fn find_legacy_typevars_impl(
@@ -1369,6 +1402,7 @@ impl<'db> Type<'db> {
                 bound.nominal_class(db)
             }
             Type::LiteralValue(literal) => literal.fallback_instance(db).nominal_class(db),
+            Type::PropertyInstance(property) => property.instance_fallback(db).nominal_class(db),
             _ => None,
         }
     }
@@ -2538,13 +2572,13 @@ impl<'db> Type<'db> {
                         // Hard code this knowledge, as we look up `__set__` and `__delete__` on `FunctionType` often.
                         Some(Place::Undefined.into())
                     }
-                    (Some(KnownClass::Property), "__get__") => Some(
+                    (Some(KnownClass::Property | KnownClass::EnumProperty), "__get__") => Some(
                         Place::bound(Type::WrapperDescriptor(
                             WrapperDescriptorKind::PropertyDunderGet,
                         ))
                         .into(),
                     ),
-                    (Some(KnownClass::Property), "__set__") => Some(
+                    (Some(KnownClass::Property | KnownClass::EnumProperty), "__set__") => Some(
                         Place::bound(Type::WrapperDescriptor(
                             WrapperDescriptorKind::PropertyDunderSet,
                         ))
@@ -2887,9 +2921,9 @@ impl<'db> Type<'db> {
 
             Type::SpecialForm(_) | Type::KnownInstance(_) => Place::Undefined.into(),
 
-            Type::PropertyInstance(_) => KnownClass::Property
-                .to_instance(db)
-                .instance_member(db, name),
+            Type::PropertyInstance(property) => {
+                property.instance_fallback(db).instance_member(db, name)
+            }
 
             // Note: `super(pivot, owner).__dict__` refers to the `__dict__` of the `builtins.super` instance,
             // not that of the owner.
@@ -5804,7 +5838,7 @@ impl<'db> Type<'db> {
             Type::NominalInstance(instance) => instance.to_meta_type(db),
             Type::KnownInstance(known_instance) => known_instance.to_meta_type(db),
             Type::SpecialForm(special_form) => special_form.to_meta_type(db),
-            Type::PropertyInstance(_) => KnownClass::Property.to_class_literal(db),
+            Type::PropertyInstance(property) => property.instance_class(db).to_class_literal(db),
             Type::Union(union) => union.map(db, |ty| ty.to_meta_type(db)),
             Type::TypeIs(_) | Type::TypeGuard(_) => KnownClass::Bool.to_class_literal(db),
             Type::TypeForm(_) => Type::object().to_meta_type(db),

crates/ty_python_semantic/src/types/bound_super.rs

@@ -814,7 +814,9 @@ impl<'db> BoundSuperType<'db> {
                 return delegate_to(KnownClass::ModuleType.to_instance(db));
             }
             Type::GenericAlias(_) => return delegate_to(KnownClass::GenericAlias.to_instance(db)),
-            Type::PropertyInstance(_) => return delegate_to(KnownClass::Property.to_instance(db)),
+            Type::PropertyInstance(property) => {
+                return delegate_to(property.instance_fallback(db));
+            }
             Type::BoundSuper(_) => return delegate_to(KnownClass::Super.to_instance(db)),
             Type::TypedDict(td) => {
                 // In general it isn't sound to upcast a `TypedDict` to a `dict`,

crates/ty_python_semantic/src/types/call/bind.rs

@@ -1624,7 +1624,7 @@ impl<'db> Bindings<'db> {
                                     let mut ty_property = bound_method.self_instance(db);
                                     if let Type::PropertyInstance(property) = ty_property {
                                         ty_property =
-                                            Type::PropertyInstance(PropertyInstanceType::new(
+                                            Type::PropertyInstance(property.with_accessors(
                                                 db,
                                                 property.getter(db),
                                                 Some(*setter),
@@ -1639,7 +1639,7 @@ impl<'db> Bindings<'db> {
                                     let mut ty_property = bound_method.self_instance(db);
                                     if let Type::PropertyInstance(property) = ty_property {
                                         ty_property =
-                                            Type::PropertyInstance(PropertyInstanceType::new(
+                                            Type::PropertyInstance(property.with_accessors(
                                                 db,
                                                 Some(*getter),
                                                 property.setter(db),
@@ -1654,7 +1654,7 @@ impl<'db> Bindings<'db> {
                                     let mut ty_property = bound_method.self_instance(db);
                                     if let Type::PropertyInstance(property) = ty_property {
                                         ty_property =
-                                            Type::PropertyInstance(PropertyInstanceType::new(
+                                            Type::PropertyInstance(property.with_accessors(
                                                 db,
                                                 property.getter(db),
                                                 property.setter(db),

crates/ty_python_semantic/src/types/call/bind/enum_property.rs

@@ -15,14 +15,17 @@ impl<'db> Bindings<'db> {
     ) {
         let property_instance =
             |getter: Option<Type<'db>>, setter: Option<Type<'db>>, deleter: Option<Type<'db>>| {
-                Type::PropertyInstance(PropertyInstanceType::new(
+                Type::PropertyInstance(PropertyInstanceType::new_enum_property(
                     db,
                     getter.filter(|ty| !ty.is_none(db)),
                     setter.filter(|ty| !ty.is_none(db)),
                     deleter.filter(|ty| !ty.is_none(db)),
                 ))
             };
 
+        // TODO: Preserve subclasses of `enum.property`. `PropertyInstanceType` currently records
+        // only a known property class, so this rewrite collapses subclass instances to
+        // `enum.property`.
         for constructor in self.iter_constructor_items_mut() {
             if !constructor
                 .constructed_instance_type()

crates/ty_python_semantic/src/types/display.rs

@@ -32,9 +32,9 @@ use crate::types::typevar::BoundTypeVarIdentity;
 use crate::types::visitor::TypeVisitor;
 use crate::types::{
     CallableType, IntersectionType, KnownBoundMethodType, KnownClass, KnownInstanceType,
-    LiteralValueType, LiteralValueTypeKind, MaterializationKind, Protocol, ProtocolInstanceType,
-    SpecialFormType, StringLiteralType, SubclassOfInner, SubclassOfType, Type, TypeAliasType,
-    TypeGuardLike, TypedDictType, UnionType, WrapperDescriptorKind, visitor,
+    LiteralValueType, LiteralValueTypeKind, MaterializationKind, PropertyInstanceType, Protocol,
+    ProtocolInstanceType, SpecialFormType, StringLiteralType, SubclassOfInner, SubclassOfType,
+    Type, TypeAliasType, TypeGuardLike, TypedDictType, UnionType, WrapperDescriptorKind, visitor,
 };
 use ty_python_core::definition::Definition;
 use ty_python_core::scope::{FileScopeId, ScopeKind};
@@ -932,6 +932,14 @@ struct DisplayRepresentation<'db> {
     settings: DisplaySettings<'db>,
 }
 
+fn property_display_name(db: &dyn Db, property: PropertyInstanceType<'_>) -> &'static str {
+    if property.instance_class(db) == KnownClass::EnumProperty {
+        "enum.property"
+    } else {
+        "property"
+    }
+}
+
 impl Display for DisplayRepresentation<'_> {
     fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
         self.fmt_detailed(&mut TypeWriter::Formatter(f))
@@ -995,7 +1003,9 @@ impl<'db> FmtDetailed<'db> for DisplayRepresentation<'db> {
                     f.write_char('>')
                 }
             },
-            Type::PropertyInstance(_) => f.with_type(self.ty).write_str("property"),
+            Type::PropertyInstance(property) => f
+                .with_type(self.ty)
+                .write_str(property_display_name(self.db, property)),
             Type::ModuleLiteral(module) => {
                 f.set_invalid_type_annotation();
                 f.write_char('<')?;
@@ -1146,29 +1156,29 @@ impl<'db> FmtDetailed<'db> for DisplayRepresentation<'db> {
                         Some(&**function.name(self.db)),
                     ),
                     KnownBoundMethodType::PropertyDunderGet(property) => (
-                        KnownClass::Property,
+                        property.instance_class(self.db),
                         "__get__",
-                        "property",
+                        property_display_name(self.db, property),
                         Type::PropertyInstance(property),
                         property
                             .getter(self.db)
                             .and_then(Type::as_function_literal)
                             .map(|getter| &**getter.name(self.db)),
                     ),
                     KnownBoundMethodType::PropertyDunderSet(property) => (
-                        KnownClass::Property,
+                        property.instance_class(self.db),
                         "__set__",
-                        "property",
+                        property_display_name(self.db, property),
                         Type::PropertyInstance(property),
                         property
                             .setter(self.db)
                             .and_then(Type::as_function_literal)
                             .map(|setter| &**setter.name(self.db)),
                     ),
                     KnownBoundMethodType::PropertyDunderDelete(property) => (
-                        KnownClass::Property,
+                        property.instance_class(self.db),
                         "__delete__",
-                        "property",
+                        property_display_name(self.db, property),
                         Type::PropertyInstance(property),
                         property
                             .deleter(self.db)

crates/ty_python_semantic/src/types/relation.rs

@@ -2174,11 +2174,11 @@ impl<'a, 'c, 'db> TypeRelationChecker<'a, 'c, 'db> {
                     self.check_property_instance_pair(db, source_p, target_p)
                 }),
 
-            (Type::PropertyInstance(_), _) => {
-                self.check_type_pair(db, KnownClass::Property.to_instance(db), target)
+            (Type::PropertyInstance(property), _) => {
+                self.check_type_pair(db, property.instance_fallback(db), target)
             }
-            (_, Type::PropertyInstance(_)) => {
-                self.check_type_pair(db, source, KnownClass::Property.to_instance(db))
+            (_, Type::PropertyInstance(property)) => {
+                self.check_type_pair(db, source, property.instance_fallback(db))
             }
             // Other than the special cases enumerated above, nominal-instance types are never
             // subtypes of any other variants
@@ -2198,17 +2198,24 @@ impl<'a, 'c, 'db> TypeRelationChecker<'a, 'c, 'db> {
             (None | Some(_), None | Some(_)) => self.never(),
         };
 
-        check_optional_methods(source.getter(db), target.getter(db)).and(
+        self.check_type_pair(
             db,
-            self.constraints,
-            || {
-                check_optional_methods(source.setter(db), target.setter(db)).and(
-                    db,
-                    self.constraints,
-                    || check_optional_methods(source.deleter(db), target.deleter(db)),
-                )
-            },
+            source.instance_fallback(db),
+            target.instance_fallback(db),
         )
+        .and(db, self.constraints, || {
+            check_optional_methods(source.getter(db), target.getter(db)).and(
+                db,
+                self.constraints,
+                || {
+                    check_optional_methods(source.setter(db), target.setter(db)).and(
+                        db,
+                        self.constraints,
+                        || check_optional_methods(source.deleter(db), target.deleter(db)),
+                    )
+                },
+            )
+        })
     }
 
     pub(super) fn as_equivalence_checker(&self) -> EquivalenceChecker<'_, 'c, 'db> {
@@ -3124,8 +3131,9 @@ impl<'a, 'c, 'db> DisjointnessChecker<'a, 'c, 'db> {
                 self.check_type_pair(db, newtype.concrete_base_type(db), other)
             }
 
-            (Type::PropertyInstance(_), other) | (other, Type::PropertyInstance(_)) => {
-                self.check_type_pair(db, KnownClass::Property.to_instance(db), other)
+            (Type::PropertyInstance(property), other)
+            | (other, Type::PropertyInstance(property)) => {
+                self.check_type_pair(db, property.instance_fallback(db), other)
             }
 
             (Type::BoundSuper(left), Type::BoundSuper(right)) => self