Merge branch 'master' into revert-23107-revert-13893-fix-issue-37193revert-23107-revert-13893-fix-issue-37193

1 files changed, 209 insertions, 62 deletions

diff --git a/Lib/enum.py b/Lib/enum.py
index 40ff25b9cd..75249bfdc1 100644
--- a/Lib/enum.py
+++ b/Lib/enum.py
@@ -9,32 +9,63 @@ __all__ = [
         ]
 
 
+class _NoInitSubclass:
+    """
+    temporary base class to suppress calling __init_subclass__
+    """
+    @classmethod
+    def __init_subclass__(cls, **kwds):
+        pass
+
 def _is_descriptor(obj):
-    """Returns True if obj is a descriptor, False otherwise."""
+    """
+    Returns True if obj is a descriptor, False otherwise.
+    """
     return (
             hasattr(obj, '__get__') or
             hasattr(obj, '__set__') or
-            hasattr(obj, '__delete__'))
-
+            hasattr(obj, '__delete__')
+            )
 
 def _is_dunder(name):
-    """Returns True if a __dunder__ name, False otherwise."""
-    return (len(name) > 4 and
+    """
+    Returns True if a __dunder__ name, False otherwise.
+    """
+    return (
+            len(name) > 4 and
             name[:2] == name[-2:] == '__' and
             name[2] != '_' and
-            name[-3] != '_')
-
+            name[-3] != '_'
+            )
 
 def _is_sunder(name):
-    """Returns True if a _sunder_ name, False otherwise."""
-    return (len(name) > 2 and
+    """
+    Returns True if a _sunder_ name, False otherwise.
+    """
+    return (
+            len(name) > 2 and
             name[0] == name[-1] == '_' and
             name[1:2] != '_' and
-            name[-2:-1] != '_')
-
+            name[-2:-1] != '_'
+            )
+
+def _is_private(cls_name, name):
+    # do not use `re` as `re` imports `enum`
+    pattern = '_%s__' % (cls_name, )
+    if (
+            len(name) >= 5
+            and name.startswith(pattern)
+            and name[len(pattern)] != '_'
+            and (name[-1] != '_' or name[-2] != '_')
+        ):
+        return True
+    else:
+        return False
 
 def _make_class_unpicklable(cls):
-    """Make the given class un-picklable."""
+    """
+    Make the given class un-picklable.
+    """
     def _break_on_call_reduce(self, proto):
         raise TypeError('%r cannot be pickled' % self)
     cls.__reduce_ex__ = _break_on_call_reduce
@@ -49,11 +80,11 @@ class auto:
 
 
 class _EnumDict(dict):
-    """Track enum member order and ensure member names are not reused.
+    """
+    Track enum member order and ensure member names are not reused.
 
     EnumMeta will use the names found in self._member_names as the
     enumeration member names.
-
     """
     def __init__(self):
         super().__init__()
@@ -63,21 +94,26 @@ class _EnumDict(dict):
         self._auto_called = False
 
     def __setitem__(self, key, value):
-        """Changes anything not dundered or not a descriptor.
+        """
+        Changes anything not dundered or not a descriptor.
 
         If an enum member name is used twice, an error is raised; duplicate
         values are not checked for.
 
         Single underscore (sunder) names are reserved.
-
         """
-        if _is_sunder(key):
+        if _is_private(self._cls_name, key):
+            # do nothing, name will be a normal attribute
+            pass
+        elif _is_sunder(key):
             if key not in (
                     '_order_', '_create_pseudo_member_',
                     '_generate_next_value_', '_missing_', '_ignore_',
                     ):
-                raise ValueError(f'_sunder_ names, such as "{key}", are '
-                                  'reserved for future Enum use')
+                raise ValueError(
+                        '_sunder_ names, such as %r, are reserved for future Enum use'
+                        % (key, )
+                        )
             if key == '_generate_next_value_':
                 # check if members already defined as auto()
                 if self._auto_called:
@@ -91,13 +127,16 @@ class _EnumDict(dict):
                 self._ignore = value
                 already = set(value) & set(self._member_names)
                 if already:
-                    raise ValueError('_ignore_ cannot specify already set names: %r' % (already, ))
+                    raise ValueError(
+                            '_ignore_ cannot specify already set names: %r'
+                            % (already, )
+                            )
         elif _is_dunder(key):
             if key == '__order__':
                 key = '_order_'
         elif key in self._member_names:
             # descriptor overwriting an enum?
-            raise TypeError('Attempted to reuse key: %r' % key)
+            raise TypeError('%r already defined as: %r' % (key, self[key]))
         elif key in self._ignore:
             pass
         elif not _is_descriptor(value):
@@ -106,35 +145,54 @@ class _EnumDict(dict):
                 raise TypeError('%r already defined as: %r' % (key, self[key]))
             if isinstance(value, auto):
                 if value.value == _auto_null:
-                    value.value = self._generate_next_value(key, 1, len(self._member_names), self._last_values[:])
+                    value.value = self._generate_next_value(
+                            key,
+                            1,
+                            len(self._member_names),
+                            self._last_values[:],
+                            )
                     self._auto_called = True
                 value = value.value
             self._member_names.append(key)
             self._last_values.append(value)
         super().__setitem__(key, value)
 
+    def update(self, members, **more_members):
+        try:
+            for name in members.keys():
+                self[name] = members[name]
+        except AttributeError:
+            for name, value in members:
+                self[name] = value
+        for name, value in more_members.items():
+            self[name] = value
+
 
 # Dummy value for Enum as EnumMeta explicitly checks for it, but of course
 # until EnumMeta finishes running the first time the Enum class doesn't exist.
 # This is also why there are checks in EnumMeta like `if Enum is not None`
 Enum = None
 
-
 class EnumMeta(type):
-    """Metaclass for Enum"""
+    """
+    Metaclass for Enum
+    """
     @classmethod
-    def __prepare__(metacls, cls, bases):
+    def __prepare__(metacls, cls, bases, **kwds):
         # check that previous enum members do not exist
         metacls._check_for_existing_members(cls, bases)
         # create the namespace dict
         enum_dict = _EnumDict()
+        enum_dict._cls_name = cls
         # inherit previous flags and _generate_next_value_ function
         member_type, first_enum = metacls._get_mixins_(cls, bases)
         if first_enum is not None:
-            enum_dict['_generate_next_value_'] = getattr(first_enum, '_generate_next_value_', None)
+            enum_dict['_generate_next_value_'] = getattr(
+                    first_enum, '_generate_next_value_', None,
+                    )
         return enum_dict
 
-    def __new__(metacls, cls, bases, classdict):
+    def __new__(metacls, cls, bases, classdict, **kwds):
         # an Enum class is final once enumeration items have been defined; it
         # cannot be mixed with other types (int, float, etc.) if it has an
         # inherited __new__ unless a new __new__ is defined (or the resulting
@@ -146,8 +204,9 @@ class EnumMeta(type):
         for key in ignore:
             classdict.pop(key, None)
         member_type, first_enum = metacls._get_mixins_(cls, bases)
-        __new__, save_new, use_args = metacls._find_new_(classdict, member_type,
-                                                        first_enum)
+        __new__, save_new, use_args = metacls._find_new_(
+                classdict, member_type, first_enum,
+                )
 
         # save enum items into separate mapping so they don't get baked into
         # the new class
@@ -168,17 +227,33 @@ class EnumMeta(type):
         if '__doc__' not in classdict:
             classdict['__doc__'] = 'An enumeration.'
 
+        # postpone calling __init_subclass__
+        if '__init_subclass__' in classdict and classdict['__init_subclass__'] is None:
+            raise TypeError('%s.__init_subclass__ cannot be None')
+        # remove current __init_subclass__ so previous one can be found with getattr
+        new_init_subclass = classdict.pop('__init_subclass__', None)
         # create our new Enum type
-        enum_class = super().__new__(metacls, cls, bases, classdict)
+        if bases:
+            bases = (_NoInitSubclass, ) + bases
+            enum_class = super().__new__(metacls, cls, bases, classdict, **kwds)
+            enum_class.__bases__ = enum_class.__bases__[1:] #or (object, )
+        else:
+            enum_class = super().__new__(metacls, cls, bases, classdict, **kwds)
+        old_init_subclass = getattr(enum_class, '__init_subclass__', None)
+        # and restore the new one (if there was one)
+        if new_init_subclass is not None:
+            enum_class.__init_subclass__ = classmethod(new_init_subclass)
         enum_class._member_names_ = []               # names in definition order
         enum_class._member_map_ = {}                 # name->value map
         enum_class._member_type_ = member_type
 
         # save DynamicClassAttribute attributes from super classes so we know
         # if we can take the shortcut of storing members in the class dict
-        dynamic_attributes = {k for c in enum_class.mro()
-                              for k, v in c.__dict__.items()
-                              if isinstance(v, DynamicClassAttribute)}
+        dynamic_attributes = {
+                k for c in enum_class.mro()
+                for k, v in c.__dict__.items()
+                if isinstance(v, DynamicClassAttribute)
+                }
 
         # Reverse value->name map for hashable values.
         enum_class._value2member_map_ = {}
@@ -279,6 +354,9 @@ class EnumMeta(type):
             if _order_ != enum_class._member_names_:
                 raise TypeError('member order does not match _order_')
 
+        # finally, call parents' __init_subclass__
+        if Enum is not None and old_init_subclass is not None:
+            old_init_subclass(**kwds)
         return enum_class
 
     def __bool__(self):
@@ -288,7 +366,8 @@ class EnumMeta(type):
         return True
 
     def __call__(cls, value, names=None, *, module=None, qualname=None, type=None, start=1):
-        """Either returns an existing member, or creates a new enum class.
+        """
+        Either returns an existing member, or creates a new enum class.
 
         This method is used both when an enum class is given a value to match
         to an enumeration member (i.e. Color(3)) and for the functional API
@@ -310,12 +389,18 @@ class EnumMeta(type):
         not correct, unpickling will fail in some circumstances.
 
         `type`, if set, will be mixed in as the first base class.
-
         """
         if names is None:  # simple value lookup
             return cls.__new__(cls, value)
         # otherwise, functional API: we're creating a new Enum type
-        return cls._create_(value, names, module=module, qualname=qualname, type=type, start=start)
+        return cls._create_(
+                value,
+                names,
+                module=module,
+                qualname=qualname,
+                type=type,
+                start=start,
+                )
 
     def __contains__(cls, member):
         if not isinstance(member, Enum):
@@ -328,22 +413,23 @@ class EnumMeta(type):
         # nicer error message when someone tries to delete an attribute
         # (see issue19025).
         if attr in cls._member_map_:
-            raise AttributeError(
-                    "%s: cannot delete Enum member." % cls.__name__)
+            raise AttributeError("%s: cannot delete Enum member %r." % (cls.__name__, attr))
         super().__delattr__(attr)
 
     def __dir__(self):
-        return (['__class__', '__doc__', '__members__', '__module__'] +
-                self._member_names_)
+        return (
+                ['__class__', '__doc__', '__members__', '__module__']
+                + self._member_names_
+                )
 
     def __getattr__(cls, name):
-        """Return the enum member matching `name`
+        """
+        Return the enum member matching `name`
 
         We use __getattr__ instead of descriptors or inserting into the enum
         class' __dict__ in order to support `name` and `value` being both
         properties for enum members (which live in the class' __dict__) and
         enum members themselves.
-
         """
         if _is_dunder(name):
             raise AttributeError(name)
@@ -356,6 +442,9 @@ class EnumMeta(type):
         return cls._member_map_[name]
 
     def __iter__(cls):
+        """
+        Returns members in definition order.
+        """
         return (cls._member_map_[name] for name in cls._member_names_)
 
     def __len__(cls):
@@ -363,11 +452,11 @@ class EnumMeta(type):
 
     @property
     def __members__(cls):
-        """Returns a mapping of member name->value.
+        """
+        Returns a mapping of member name->value.
 
         This mapping lists all enum members, including aliases. Note that this
         is a read-only view of the internal mapping.
-
         """
         return MappingProxyType(cls._member_map_)
 
@@ -375,15 +464,18 @@ class EnumMeta(type):
         return "<enum %r>" % cls.__name__
 
     def __reversed__(cls):
+        """
+        Returns members in reverse definition order.
+        """
         return (cls._member_map_[name] for name in reversed(cls._member_names_))
 
     def __setattr__(cls, name, value):
-        """Block attempts to reassign Enum members.
+        """
+        Block attempts to reassign Enum members.
 
         A simple assignment to the class namespace only changes one of the
         several possible ways to get an Enum member from the Enum class,
         resulting in an inconsistent Enumeration.
-
         """
         member_map = cls.__dict__.get('_member_map_', {})
         if name in member_map:
@@ -391,7 +483,8 @@ class EnumMeta(type):
         super().__setattr__(name, value)
 
     def _create_(cls, class_name, names, *, module=None, qualname=None, type=None, start=1):
-        """Convenience method to create a new Enum class.
+        """
+        Convenience method to create a new Enum class.
 
         `names` can be:
 
@@ -400,7 +493,6 @@ class EnumMeta(type):
         * An iterable of member names.  Values are incremented by 1 from `start`.
         * An iterable of (member name, value) pairs.
         * A mapping of member name -> value pairs.
-
         """
         metacls = cls.__class__
         bases = (cls, ) if type is None else (type, cls)
@@ -481,15 +573,18 @@ class EnumMeta(type):
         for chain in bases:
             for base in chain.__mro__:
                 if issubclass(base, Enum) and base._member_names_:
-                    raise TypeError("%s: cannot extend enumeration %r" % (class_name, base.__name__))
+                    raise TypeError(
+                            "%s: cannot extend enumeration %r"
+                            % (class_name, base.__name__)
+                            )
 
     @staticmethod
     def _get_mixins_(class_name, bases):
-        """Returns the type for creating enum members, and the first inherited
+        """
+        Returns the type for creating enum members, and the first inherited
         enum class.
 
         bases: the tuple of bases that was given to __new__
-
         """
         if not bases:
             return object, Enum
@@ -501,12 +596,16 @@ class EnumMeta(type):
                 for base in chain.__mro__:
                     if base is object:
                         continue
+                    elif issubclass(base, Enum):
+                        if base._member_type_ is not object:
+                            data_types.append(base._member_type_)
+                            break
                     elif '__new__' in base.__dict__:
                         if issubclass(base, Enum):
                             continue
                         data_types.append(candidate or base)
                         break
-                    elif not issubclass(base, Enum):
+                    else:
                         candidate = base
             if len(data_types) > 1:
                 raise TypeError('%r: too many data types: %r' % (class_name, data_types))
@@ -528,12 +627,12 @@ class EnumMeta(type):
 
     @staticmethod
     def _find_new_(classdict, member_type, first_enum):
-        """Returns the __new__ to be used for creating the enum members.
+        """
+        Returns the __new__ to be used for creating the enum members.
 
         classdict: the class dictionary given to __new__
         member_type: the data type whose __new__ will be used by default
         first_enum: enumeration to check for an overriding __new__
-
         """
         # now find the correct __new__, checking to see of one was defined
         # by the user; also check earlier enum classes in case a __new__ was
@@ -573,10 +672,10 @@ class EnumMeta(type):
 
 
 class Enum(metaclass=EnumMeta):
-    """Generic enumeration.
+    """
+    Generic enumeration.
 
     Derive from this class to define new enumerations.
-
     """
     def __new__(cls, value):
         # all enum instances are actually created during class construction
@@ -619,6 +718,14 @@ class Enum(metaclass=EnumMeta):
             raise exc
 
     def _generate_next_value_(name, start, count, last_values):
+        """
+        Generate the next value when not given.
+
+        name: the name of the member
+        start: the initial start value or None
+        count: the number of existing members
+        last_value: the last value assigned or None
+        """
         for last_value in reversed(last_values):
             try:
                 return last_value + 1
@@ -627,6 +734,9 @@ class Enum(metaclass=EnumMeta):
         else:
             return start
 
+    def __init_subclass__(cls, **kwds):
+        super().__init_subclass__(**kwds)
+
     @classmethod
     def _missing_(cls, value):
         return None
@@ -639,6 +749,9 @@ class Enum(metaclass=EnumMeta):
         return "%s.%s" % (self.__class__.__name__, self._name_)
 
     def __dir__(self):
+        """
+        Returns all members and all public methods
+        """
         added_behavior = [
                 m
                 for cls in self.__class__.mro()
@@ -648,12 +761,15 @@ class Enum(metaclass=EnumMeta):
         return (['__class__', '__doc__', '__module__'] + added_behavior)
 
     def __format__(self, format_spec):
+        """
+        Returns format using actual value type unless __str__ has been overridden.
+        """
         # mixed-in Enums should use the mixed-in type's __format__, otherwise
         # we can get strange results with the Enum name showing up instead of
         # the value
 
         # pure Enum branch, or branch with __str__ explicitly overridden
-        str_overridden = type(self).__str__ != Enum.__str__
+        str_overridden = type(self).__str__ not in (Enum.__str__, Flag.__str__)
         if self._member_type_ is object or str_overridden:
             cls = str
             val = str(self)
@@ -720,12 +836,20 @@ class StrEnum(str, Enum):
 
     __str__ = str.__str__
 
+    def _generate_next_value_(name, start, count, last_values):
+        """
+        Return the lower-cased version of the member name.
+        """
+        return name.lower()
+
 
 def _reduce_ex_by_name(self, proto):
     return self.name
 
 class Flag(Enum):
-    """Support for flags"""
+    """
+    Support for flags
+    """
 
     def _generate_next_value_(name, start, count, last_values):
         """
@@ -748,6 +872,9 @@ class Flag(Enum):
 
     @classmethod
     def _missing_(cls, value):
+        """
+        Returns member (possibly creating it) if one can be found for value.
+        """
         original_value = value
         if value < 0:
             value = ~value
@@ -777,6 +904,9 @@ class Flag(Enum):
         return pseudo_member
 
     def __contains__(self, other):
+        """
+        Returns True if self has at least the same flags set as other.
+        """
         if not isinstance(other, self.__class__):
             raise TypeError(
                 "unsupported operand type(s) for 'in': '%s' and '%s'" % (
@@ -784,6 +914,9 @@ class Flag(Enum):
         return other._value_ & self._value_ == other._value_
 
     def __iter__(self):
+        """
+        Returns flags in decreasing value order.
+        """
         members, extra_flags = _decompose(self.__class__, self.value)
         return (m for m in members if m._value_ != 0)
 
@@ -839,10 +972,15 @@ class Flag(Enum):
 
 
 class IntFlag(int, Flag):
-    """Support for integer-based Flags"""
+    """
+    Support for integer-based Flags
+    """
 
     @classmethod
     def _missing_(cls, value):
+        """
+        Returns member (possibly creating it) if one can be found for value.
+        """
         if not isinstance(value, int):
             raise ValueError("%r is not a valid %s" % (value, cls.__qualname__))
         new_member = cls._create_pseudo_member_(value)
@@ -850,6 +988,9 @@ class IntFlag(int, Flag):
 
     @classmethod
     def _create_pseudo_member_(cls, value):
+        """
+        Create a composite member iff value contains only members.
+        """
         pseudo_member = cls._value2member_map_.get(value, None)
         if pseudo_member is None:
             need_to_create = [value]
@@ -904,11 +1045,15 @@ class IntFlag(int, Flag):
 
 
 def _high_bit(value):
-    """returns index of highest bit, or -1 if value is zero or negative"""
+    """
+    returns index of highest bit, or -1 if value is zero or negative
+    """
     return value.bit_length() - 1
 
 def unique(enumeration):
-    """Class decorator for enumerations ensuring unique member values."""
+    """
+    Class decorator for enumerations ensuring unique member values.
+    """
     duplicates = []
     for name, member in enumeration.__members__.items():
         if name != member.name:
@@ -921,7 +1066,9 @@ def unique(enumeration):
     return enumeration
 
 def _decompose(flag, value):
-    """Extract all members from the value."""
+    """
+    Extract all members from the value.
+    """
     # _decompose is only called if the value is not named
     not_covered = value
     negative = value < 0