Close 25594: advise against accessing Enum members from other members

diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst
index 0fbbf5af79fc4eae773b47957fa1f746db618d05..a76f5a369ca025f9df66bbb6832c815f001763ee 100644 (file)
--- a/Doc/library/enum.rst
+++ b/Doc/library/enum.rst
@@ -730,18 +730,24 @@ member instances.
 Finer Points
 ^^^^^^^^^^^^
 
-Enum members are instances of an Enum class, and even though they are
-accessible as `EnumClass.member`, they are not accessible directly from
-the member::
-
-    >>> Color.red
-    <Color.red: 1>
-    >>> Color.red.blue
-    Traceback (most recent call last):
+:class:`Enum` members are instances of an :class:`Enum` class, and even
+though they are accessible as `EnumClass.member`, they should not be accessed
+directly from the member as that lookup may fail or, worse, return something
+besides the :class:`Enum` member you looking for::
+
+    >>> class FieldTypes(Enum):
+    ...     name = 0
+    ...     value = 1
+    ...     size = 2
     ...
-    AttributeError: 'Color' object has no attribute 'blue'
+    >>> FieldTypes.value.size
+    <FieldTypes.size: 2>
+    >>> FieldTypes.size.value
+    2
+
+.. versionchanged:: 3.5
 
-Likewise, the :attr:`__members__` is only available on the class.
+The :attr:`__members__` attribute is only available on the class.
 
 If you give your :class:`Enum` subclass extra methods, like the `Planet`_
 class above, those methods will show up in a :func:`dir` of the member,