From effa2ecdcf0d019d6ed04ca160f789af57e959de Mon Sep 17 00:00:00 2001
From: Ethan Furman <ethan@stoneleaf.us>
Date: Thu, 7 Sep 2023 18:57:48 -0700
Subject: [3.11] gh-108682: [Enum] raise TypeError if super().__new__ called in
 custom __new__ (GH-108704) (GH-108739)

When overriding the `__new__` method of an enum, the underlying data type should be created directly; i.e. .

    member = object.__new__(cls)
    member = int.__new__(cls, value)
    member = str.__new__(cls, value)

Calling `super().__new__()` finds the lookup version of `Enum.__new__`, and will now raise an exception when detected.

(cherry picked from commit d48760b2f1e28dd3c1a35721939f400a8ab619b8)
---
 Doc/howto/enum.rst                                 | 23 +++++++++++++++++++++-
 Lib/enum.py                                        |  7 +++++++
 Lib/test/test_enum.py                              | 11 +++++++++++
 .../2023-08-30-20-10-28.gh-issue-108682.c2gzLQ.rst |  2 ++
 4 files changed, 42 insertions(+), 1 deletion(-)
 create mode 100644 Misc/NEWS.d/next/Library/2023-08-30-20-10-28.gh-issue-108682.c2gzLQ.rst

diff --git a/Doc/howto/enum.rst b/Doc/howto/enum.rst
index e904944..465be65 100644
--- a/Doc/howto/enum.rst
+++ b/Doc/howto/enum.rst
@@ -422,10 +422,17 @@ enumeration, with the exception of special methods (:meth:`__str__`,
 :meth:`__add__`, etc.), descriptors (methods are also descriptors), and
 variable names listed in :attr:`_ignore_`.
 
-Note:  if your enumeration defines :meth:`__new__` and/or :meth:`__init__` then
+Note:  if your enumeration defines :meth:`__new__` and/or :meth:`__init__`,
 any value(s) given to the enum member will be passed into those methods.
 See `Planet`_ for an example.
 
+.. note::
+
+    The :meth:`__new__` method, if defined, is used during creation of the Enum
+    members; it is then replaced by Enum's :meth:`__new__` which is used after
+    class creation for lookup of existing members.  See :ref:`new-vs-init` for
+    more details.
+
 
 Restricted Enum subclassing
 ---------------------------
@@ -860,6 +867,8 @@ Some rules:
    :meth:`__str__` method has been reset to their data types'
    :meth:`__str__` method.
 
+.. _new-vs-init:
+
 When to use :meth:`__new__` vs. :meth:`__init__`
 ------------------------------------------------
 
@@ -892,6 +901,11 @@ want one of them to be the value::
     >>> print(Coordinate(3))
     Coordinate.VY
 
+.. warning::
+
+    *Do not* call ``super().__new__()``, as the lookup-only ``__new__`` is the one
+    that is found; instead, use the data type directly.
+
 
 Finer Points
 ^^^^^^^^^^^^
@@ -1316,6 +1330,13 @@ to handle any extra arguments::
     members; it is then replaced by Enum's :meth:`__new__` which is used after
     class creation for lookup of existing members.
 
+.. warning::
+
+    *Do not* call ``super().__new__()``, as the lookup-only ``__new__`` is the one
+    that is found; instead, use the data type directly -- e.g.::
+
+       obj = int.__new__(cls, value)
+
 
 OrderedEnum
 ^^^^^^^^^^^
diff --git a/Lib/enum.py b/Lib/enum.py
index 1f447c8..155cb13 100644
--- a/Lib/enum.py
+++ b/Lib/enum.py
@@ -863,6 +863,8 @@ class EnumType(type):
                 value = first_enum._generate_next_value_(name, start, count, last_values[:])
                 last_values.append(value)
                 names.append((name, value))
+        if names is None:
+            names = ()
 
         # Here, names is either an iterable of (name, value) or a mapping.
         for item in names:
@@ -1107,6 +1109,11 @@ class Enum(metaclass=EnumType):
             for member in cls._member_map_.values():
                 if member._value_ == value:
                     return member
+        # still not found -- verify that members exist, in-case somebody got here mistakenly
+        # (such as via super when trying to override __new__)
+        if not cls._member_map_:
+            raise TypeError("%r has no members defined" % cls)
+        #
         # still not found -- try _missing_ hook
         try:
             exc = None
diff --git a/Lib/test/test_enum.py b/Lib/test/test_enum.py
index cc66875..ed1c3a5 100644
--- a/Lib/test/test_enum.py
+++ b/Lib/test/test_enum.py
@@ -322,6 +322,17 @@ class _EnumTests:
         with self.assertRaises(AttributeError):
             del Season.SPRING.name
 
+    def test_bad_new_super(self):
+        with self.assertRaisesRegex(
+                TypeError,
+                'has no members defined',
+            ):
+            class BadSuper(self.enum_type):
+                def __new__(cls, value):
+                    obj = super().__new__(cls, value)
+                    return obj
+                failed = 1
+
     def test_basics(self):
         TE = self.MainEnum
         if self.is_flag:
diff --git a/Misc/NEWS.d/next/Library/2023-08-30-20-10-28.gh-issue-108682.c2gzLQ.rst b/Misc/NEWS.d/next/Library/2023-08-30-20-10-28.gh-issue-108682.c2gzLQ.rst
new file mode 100644
index 0000000..148d432
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2023-08-30-20-10-28.gh-issue-108682.c2gzLQ.rst
@@ -0,0 +1,2 @@
+Enum: raise :exc:`TypeError` if ``super().__new__()`` is called from a
+custom ``__new__``.
-- 
cgit v0.12