[3.12] gh-114071: [Enum] update docs and code for tuples/subclasses (GH-114871) (GH-114993)

Update documentation with `__new__` and `__init__` entries.

Support use of `auto()` in tuple subclasses on member assignment lines.  Previously, auto() was only supported on the member definition line either solo or as part of a tuple:

    RED = auto()
    BLUE = auto(), 'azul'

However, since Python itself supports using tuple subclasses where tuples are expected, e.g.:

    from collections import namedtuple
    T = namedtuple('T', 'first second third')

    def test(one, two, three):
        print(one, two, three)

    test(*T(4, 5, 6))
    GH- 4 5 6

it made sense to also support tuple subclasses in enum definitions.
(cherry picked from commit ff7588b)

Co-authored-by: Ethan Furman <ethan@stoneleaf.us>

Author: miss-islington

Doc/library/enum.rst

@@ -323,6 +323,17 @@ Data Types
          >>> PowersOfThree.SECOND.value
          9
 
+   .. method:: Enum.__init__(self, \*args, \**kwds)
+
+      By default, does nothing.  If multiple values are given in the member
+      assignment, those values become separate arguments to ``__init__``; e.g.
+
+         >>> from enum import Enum
+         >>> class Weekday(Enum):
+         ...     MONDAY = 1, 'Mon'
+
+      ``Weekday.__init__()`` would be called as ``Weekday.__init__(self, 1, 'Mon')``
+
    .. method:: Enum.__init_subclass__(cls, \**kwds)
 
       A *classmethod* that is used to further configure subsequent subclasses.
@@ -350,6 +361,18 @@ Data Types
          >>> Build('deBUG')
          <Build.DEBUG: 'debug'>
 
+   .. method:: Enum.__new__(cls, \*args, \**kwds)
+
+      By default, doesn't exist.  If specified, either in the enum class
+      definition or in a mixin class (such as ``int``), all values given
+      in the member assignment will be passed; e.g.
+
+         >>> from enum import Enum
+         >>> class MyIntEnum(Enum):
+         ...     SEVENTEEN = '1a', 16
+
+      results in the call ``int('1a', 16)`` and a value of ``17`` for the member.
+
    .. method:: Enum.__repr__(self)
 
       Returns the string used for *repr()* calls.  By default, returns the
@@ -463,9 +486,9 @@ Data Types
 
 .. class:: Flag
 
-   *Flag* members support the bitwise operators ``&`` (*AND*), ``|`` (*OR*),
-   ``^`` (*XOR*), and ``~`` (*INVERT*); the results of those operators are members
-   of the enumeration.
+   ``Flag`` is the same as :class:`Enum`, but its members support the bitwise
+   operators ``&`` (*AND*), ``|`` (*OR*), ``^`` (*XOR*), and ``~`` (*INVERT*);
+   the results of those operators are members of the enumeration.
 
    .. method:: __contains__(self, value)
 

Lib/enum.py

@@ -457,10 +457,11 @@ def __setitem__(self, key, value):
             if isinstance(value, auto):
                 single = True
                 value = (value, )
-            if type(value) is tuple and any(isinstance(v, auto) for v in value):
+            if isinstance(value, tuple) and any(isinstance(v, auto) for v in value):
                 # insist on an actual tuple, no subclasses, in keeping with only supporting
                 # top-level auto() usage (not contained in any other data structure)
                 auto_valued = []
+                t = type(value)
                 for v in value:
                     if isinstance(v, auto):
                         non_auto_store = False
@@ -475,7 +476,12 @@ def __setitem__(self, key, value):
                 if single:
                     value = auto_valued[0]
                 else:
-                    value = tuple(auto_valued)
+                    try:
+                        # accepts iterable as multiple arguments?
+                        value = t(auto_valued)
+                    except TypeError:
+                        # then pass them in singlely
+                        value = t(*auto_valued)
             self._member_names[key] = None
             if non_auto_store:
                 self._last_values.append(value)

Lib/test/test_enum.py

@@ -2308,6 +2308,40 @@ class SomeTuple(tuple, Enum):
         globals()['SomeTuple'] = SomeTuple
         test_pickle_dump_load(self.assertIs, SomeTuple.first)
 
+    def test_tuple_subclass_with_auto_1(self):
+        from collections import namedtuple
+        T = namedtuple('T', 'index desc')
+        class SomeEnum(T, Enum):
+            __qualname__ = 'SomeEnum'      # needed for pickle protocol 4
+            first = auto(), 'for the money'
+            second = auto(), 'for the show'
+            third = auto(), 'for the music'
+        self.assertIs(type(SomeEnum.first), SomeEnum)
+        self.assertEqual(SomeEnum.third.value, (3, 'for the music'))
+        self.assertIsInstance(SomeEnum.third.value, T)
+        self.assertEqual(SomeEnum.first.index, 1)
+        self.assertEqual(SomeEnum.second.desc, 'for the show')
+        globals()['SomeEnum'] = SomeEnum
+        globals()['T'] = T
+        test_pickle_dump_load(self.assertIs, SomeEnum.first)
+
+    def test_tuple_subclass_with_auto_2(self):
+        from collections import namedtuple
+        T = namedtuple('T', 'index desc')
+        class SomeEnum(Enum):
+            __qualname__ = 'SomeEnum'      # needed for pickle protocol 4
+            first = T(auto(), 'for the money')
+            second = T(auto(), 'for the show')
+            third = T(auto(), 'for the music')
+        self.assertIs(type(SomeEnum.first), SomeEnum)
+        self.assertEqual(SomeEnum.third.value, (3, 'for the music'))
+        self.assertIsInstance(SomeEnum.third.value, T)
+        self.assertEqual(SomeEnum.first.value.index, 1)
+        self.assertEqual(SomeEnum.second.value.desc, 'for the show')
+        globals()['SomeEnum'] = SomeEnum
+        globals()['T'] = T
+        test_pickle_dump_load(self.assertIs, SomeEnum.first)
+
     def test_duplicate_values_give_unique_enum_items(self):
         class AutoNumber(Enum):
             first = ()

Misc/NEWS.d/next/Library/2024-02-01-10-19-11.gh-issue-114071.vkm2G_.rst

@@ -0,0 +1 @@
+Support tuple subclasses using auto() for enum member value.