Permalink
* [Enum] reduce scope of new format behavior
Instead of treating all Enums the same for format(), only user mixed-in
enums will be affected. In other words, IntEnum and IntFlag will not be
changing the format() behavior, due to the requirement that they be
drop-in replacements of existing integer constants.
If a user creates their own integer-based enum, then the new behavior
will apply:
class Grades(int, Enum):
A = 5
B = 4
C = 3
D = 2
F = 0
Now: format(Grades.B) -> DeprecationWarning and '4'
3.12: -> no warning, and 'B'
| import sys | |
| from types import MappingProxyType, DynamicClassAttribute | |
| from operator import or_ as _or_ | |
| from functools import reduce | |
| from builtins import property as _bltin_property, bin as _bltin_bin | |
| __all__ = [ | |
| 'EnumType', 'EnumMeta', | |
| 'Enum', 'IntEnum', 'StrEnum', 'Flag', 'IntFlag', | |
| 'auto', 'unique', 'property', 'verify', | |
| 'FlagBoundary', 'STRICT', 'CONFORM', 'EJECT', 'KEEP', | |
| 'global_flag_repr', 'global_enum_repr', 'global_enum', | |
| 'EnumCheck', 'CONTINUOUS', 'NAMED_FLAGS', 'UNIQUE', | |
| ] | |
| # Dummy value for Enum and Flag as there are explicit checks for them | |
| # before they have been created. | |
| # This is also why there are checks in EnumType like `if Enum is not None` | |
| Enum = Flag = EJECT = None | |
| def _is_descriptor(obj): | |
| """ | |
| Returns True if obj is a descriptor, False otherwise. | |
| """ | |
| return ( | |
| hasattr(obj, '__get__') or | |
| hasattr(obj, '__set__') or | |
| hasattr(obj, '__delete__') | |
| ) | |
| def _is_dunder(name): | |
| """ | |
| Returns True if a __dunder__ name, False otherwise. | |
| """ | |
| return ( | |
| len(name) > 4 and | |
| name[:2] == name[-2:] == '__' and | |
| name[2] != '_' and | |
| name[-3] != '_' | |
| ) | |
| def _is_sunder(name): | |
| """ | |
| 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] != '_' | |
| ) | |
| def _is_private(cls_name, name): | |
| # do not use `re` as `re` imports `enum` | |
| pattern = '_%s__' % (cls_name, ) | |
| pat_len = len(pattern) | |
| if ( | |
| len(name) > pat_len | |
| and name.startswith(pattern) | |
| and name[pat_len:pat_len+1] != ['_'] | |
| and (name[-1] != '_' or name[-2] != '_') | |
| ): | |
| return True | |
| else: | |
| return False | |
| def _is_single_bit(num): | |
| """ | |
| True if only one bit set in num (should be an int) | |
| """ | |
| if num == 0: | |
| return False | |
| num &= num - 1 | |
| return num == 0 | |
| def _make_class_unpicklable(obj): | |
| """ | |
| Make the given obj un-picklable. | |
| obj should be either a dictionary, or an Enum | |
| """ | |
| def _break_on_call_reduce(self, proto): | |
| raise TypeError('%r cannot be pickled' % self) | |
| if isinstance(obj, dict): | |
| obj['__reduce_ex__'] = _break_on_call_reduce | |
| obj['__module__'] = '<unknown>' | |
| else: | |
| setattr(obj, '__reduce_ex__', _break_on_call_reduce) | |
| setattr(obj, '__module__', '<unknown>') | |
| def _iter_bits_lsb(num): | |
| # num must be an integer | |
| if isinstance(num, Enum): | |
| num = num.value | |
| while num: | |
| b = num & (~num + 1) | |
| yield b | |
| num ^= b | |
| def show_flag_values(value): | |
| return list(_iter_bits_lsb(value)) | |
| def bin(num, max_bits=None): | |
| """ | |
| Like built-in bin(), except negative values are represented in | |
| twos-compliment, and the leading bit always indicates sign | |
| (0=positive, 1=negative). | |
| >>> bin(10) | |
| '0b0 1010' | |
| >>> bin(~10) # ~10 is -11 | |
| '0b1 0101' | |
| """ | |
| ceiling = 2 ** (num).bit_length() | |
| if num >= 0: | |
| s = _bltin_bin(num + ceiling).replace('1', '0', 1) | |
| else: | |
| s = _bltin_bin(~num ^ (ceiling - 1) + ceiling) | |
| sign = s[:3] | |
| digits = s[3:] | |
| if max_bits is not None: | |
| if len(digits) < max_bits: | |
| digits = (sign[-1] * max_bits + digits)[-max_bits:] | |
| return "%s %s" % (sign, digits) | |
| _auto_null = object() | |
| class auto: | |
| """ | |
| Instances are replaced with an appropriate value in Enum class suites. | |
| """ | |
| value = _auto_null | |
| class property(DynamicClassAttribute): | |
| """ | |
| This is a descriptor, used to define attributes that act differently | |
| when accessed through an enum member and through an enum class. | |
| Instance access is the same as property(), but access to an attribute | |
| through the enum class will instead look in the class' _member_map_ for | |
| a corresponding enum member. | |
| """ | |
| def __get__(self, instance, ownerclass=None): | |
| if instance is None: | |
| try: | |
| return ownerclass._member_map_[self.name] | |
| except KeyError: | |
| raise AttributeError( | |
| '%s: no class attribute %r' % (ownerclass.__name__, self.name) | |
| ) | |
| else: | |
| if self.fget is None: | |
| # check for member | |
| if self.name in ownerclass._member_map_: | |
| import warnings | |
| warnings.warn( | |
| "accessing one member from another is not supported, " | |
| " and will be disabled in 3.12", | |
| DeprecationWarning, | |
| stacklevel=2, | |
| ) | |
| return ownerclass._member_map_[self.name] | |
| raise AttributeError( | |
| '%s: no instance attribute %r' % (ownerclass.__name__, self.name) | |
| ) | |
| else: | |
| return self.fget(instance) | |
| def __set__(self, instance, value): | |
| if self.fset is None: | |
| raise AttributeError( | |
| "%s: cannot set instance attribute %r" % (self.clsname, self.name) | |
| ) | |
| else: | |
| return self.fset(instance, value) | |
| def __delete__(self, instance): | |
| if self.fdel is None: | |
| raise AttributeError( | |
| "%s: cannot delete instance attribute %r" % (self.clsname, self.name) | |
| ) | |
| else: | |
| return self.fdel(instance) | |
| def __set_name__(self, ownerclass, name): | |
| self.name = name | |
| self.clsname = ownerclass.__name__ | |
| class _proto_member: | |
| """ | |
| intermediate step for enum members between class execution and final creation | |
| """ | |
| def __init__(self, value): | |
| self.value = value | |
| def __set_name__(self, enum_class, member_name): | |
| """ | |
| convert each quasi-member into an instance of the new enum class | |
| """ | |
| # first step: remove ourself from enum_class | |
| delattr(enum_class, member_name) | |
| # second step: create member based on enum_class | |
| value = self.value | |
| if not isinstance(value, tuple): | |
| args = (value, ) | |
| else: | |
| args = value | |
| if enum_class._member_type_ is tuple: # special case for tuple enums | |
| args = (args, ) # wrap it one more time | |
| if not enum_class._use_args_: | |
| enum_member = enum_class._new_member_(enum_class) | |
| if not hasattr(enum_member, '_value_'): | |
| enum_member._value_ = value | |
| else: | |
| enum_member = enum_class._new_member_(enum_class, *args) | |
| if not hasattr(enum_member, '_value_'): | |
| if enum_class._member_type_ is object: | |
| enum_member._value_ = value | |
| else: | |
| try: | |
| enum_member._value_ = enum_class._member_type_(*args) | |
| except Exception as exc: | |
| raise TypeError( | |
| '_value_ not set in __new__, unable to create it' | |
| ) from None | |
| value = enum_member._value_ | |
| enum_member._name_ = member_name | |
| enum_member.__objclass__ = enum_class | |
| enum_member.__init__(*args) | |
| enum_member._sort_order_ = len(enum_class._member_names_) | |
| # If another member with the same value was already defined, the | |
| # new member becomes an alias to the existing one. | |
| for name, canonical_member in enum_class._member_map_.items(): | |
| if canonical_member._value_ == enum_member._value_: | |
| enum_member = canonical_member | |
| break | |
| else: | |
| # this could still be an alias if the value is multi-bit and the | |
| # class is a flag class | |
| if ( | |
| Flag is None | |
| or not issubclass(enum_class, Flag) | |
| ): | |
| # no other instances found, record this member in _member_names_ | |
| enum_class._member_names_.append(member_name) | |
| elif ( | |
| Flag is not None | |
| and issubclass(enum_class, Flag) | |
| and _is_single_bit(value) | |
| ): | |
| # no other instances found, record this member in _member_names_ | |
| enum_class._member_names_.append(member_name) | |
| # get redirect in place before adding to _member_map_ | |
| # but check for other instances in parent classes first | |
| need_override = False | |
| descriptor = None | |
| for base in enum_class.__mro__[1:]: | |
| descriptor = base.__dict__.get(member_name) | |
| if descriptor is not None: | |
| if isinstance(descriptor, (property, DynamicClassAttribute)): | |
| break | |
| else: | |
| need_override = True | |
| # keep looking for an enum.property | |
| if descriptor and not need_override: | |
| # previous enum.property found, no further action needed | |
| pass | |
| else: | |
| redirect = property() | |
| redirect.__set_name__(enum_class, member_name) | |
| if descriptor and need_override: | |
| # previous enum.property found, but some other inherited attribute | |
| # is in the way; copy fget, fset, fdel to this one | |
| redirect.fget = descriptor.fget | |
| redirect.fset = descriptor.fset | |
| redirect.fdel = descriptor.fdel | |
| setattr(enum_class, member_name, redirect) | |
| # now add to _member_map_ (even aliases) | |
| enum_class._member_map_[member_name] = enum_member | |
| try: | |
| # This may fail if value is not hashable. We can't add the value | |
| # to the map, and by-value lookups for this value will be | |
| # linear. | |
| enum_class._value2member_map_.setdefault(value, enum_member) | |
| except TypeError: | |
| # keep track of the value in a list so containment checks are quick | |
| enum_class._unhashable_values_.append(value) | |
| class _EnumDict(dict): | |
| """ | |
| Track enum member order and ensure member names are not reused. | |
| EnumType will use the names found in self._member_names as the | |
| enumeration member names. | |
| """ | |
| def __init__(self): | |
| super().__init__() | |
| self._member_names = [] | |
| self._last_values = [] | |
| self._ignore = [] | |
| self._auto_called = False | |
| def __setitem__(self, key, value): | |
| """ | |
| 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_private(self._cls_name, key): | |
| # do nothing, name will be a normal attribute | |
| pass | |
| elif _is_sunder(key): | |
| if key not in ( | |
| '_order_', | |
| '_generate_next_value_', '_missing_', '_ignore_', | |
| '_iter_member_', '_iter_member_by_value_', '_iter_member_by_def_', | |
| ): | |
| 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: | |
| raise TypeError("_generate_next_value_ must be defined before members") | |
| _gnv = value.__func__ if isinstance(value, staticmethod) else value | |
| setattr(self, '_generate_next_value', _gnv) | |
| elif key == '_ignore_': | |
| if isinstance(value, str): | |
| value = value.replace(',',' ').split() | |
| else: | |
| value = list(value) | |
| self._ignore = value | |
| already = set(value) & set(self._member_names) | |
| if 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('%r already defined as: %r' % (key, self[key])) | |
| elif key in self._ignore: | |
| pass | |
| elif not _is_descriptor(value): | |
| if key in self: | |
| # enum overwriting a descriptor? | |
| 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[:], | |
| ) | |
| 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 | |
| class EnumType(type): | |
| """ | |
| Metaclass for Enum | |
| """ | |
| @classmethod | |
| 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, | |
| ) | |
| return enum_dict | |
| def __new__(metacls, cls, bases, classdict, *, boundary=None, _simple=False, **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 | |
| # class will fail). | |
| # | |
| # remove any keys listed in _ignore_ | |
| if _simple: | |
| return super().__new__(metacls, cls, bases, classdict, **kwds) | |
| classdict.setdefault('_ignore_', []).append('_ignore_') | |
| ignore = classdict['_ignore_'] | |
| for key in ignore: | |
| classdict.pop(key, None) | |
| # | |
| # grab member names | |
| member_names = classdict._member_names | |
| # | |
| # check for illegal enum names (any others?) | |
| invalid_names = set(member_names) & {'mro', ''} | |
| if invalid_names: | |
| raise ValueError('Invalid enum member name: {0}'.format( | |
| ','.join(invalid_names))) | |
| # | |
| # adjust the sunders | |
| _order_ = classdict.pop('_order_', None) | |
| # convert to normal dict | |
| classdict = dict(classdict.items()) | |
| # | |
| # data type of member and the controlling Enum class | |
| member_type, first_enum = metacls._get_mixins_(cls, bases) | |
| __new__, save_new, use_args = metacls._find_new_( | |
| classdict, member_type, first_enum, | |
| ) | |
| classdict['_new_member_'] = __new__ | |
| classdict['_use_args_'] = use_args | |
| # | |
| # convert future enum members into temporary _proto_members | |
| # and record integer values in case this will be a Flag | |
| flag_mask = 0 | |
| for name in member_names: | |
| value = classdict[name] | |
| if isinstance(value, int): | |
| flag_mask |= value | |
| classdict[name] = _proto_member(value) | |
| # | |
| # house-keeping structures | |
| classdict['_member_names_'] = [] | |
| classdict['_member_map_'] = {} | |
| classdict['_value2member_map_'] = {} | |
| classdict['_unhashable_values_'] = [] | |
| classdict['_member_type_'] = member_type | |
| # | |
| # Flag structures (will be removed if final class is not a Flag | |
| classdict['_boundary_'] = ( | |
| boundary | |
| or getattr(first_enum, '_boundary_', None) | |
| ) | |
| classdict['_flag_mask_'] = flag_mask | |
| classdict['_all_bits_'] = 2 ** ((flag_mask).bit_length()) - 1 | |
| classdict['_inverted_'] = None | |
| # | |
| # create a default docstring if one has not been provided | |
| if '__doc__' not in classdict: | |
| classdict['__doc__'] = 'An enumeration.' | |
| try: | |
| exc = None | |
| enum_class = super().__new__(metacls, cls, bases, classdict, **kwds) | |
| except RuntimeError as e: | |
| # any exceptions raised by member.__new__ will get converted to a | |
| # RuntimeError, so get that original exception back and raise it instead | |
| exc = e.__cause__ or e | |
| if exc is not None: | |
| raise exc | |
| # | |
| # double check that repr and friends are not the mixin's or various | |
| # things break (such as pickle) | |
| # however, if the method is defined in the Enum itself, don't replace | |
| # it | |
| for name in ('__repr__', '__str__', '__format__', '__reduce_ex__'): | |
| if name in classdict: | |
| continue | |
| class_method = getattr(enum_class, name) | |
| obj_method = getattr(member_type, name, None) | |
| enum_method = getattr(first_enum, name, None) | |
| if obj_method is not None and obj_method is class_method: | |
| setattr(enum_class, name, enum_method) | |
| # | |
| # replace any other __new__ with our own (as long as Enum is not None, | |
| # anyway) -- again, this is to support pickle | |
| if Enum is not None: | |
| # if the user defined their own __new__, save it before it gets | |
| # clobbered in case they subclass later | |
| if save_new: | |
| enum_class.__new_member__ = __new__ | |
| enum_class.__new__ = Enum.__new__ | |
| # | |
| # py3 support for definition order (helps keep py2/py3 code in sync) | |
| # | |
| # _order_ checking is spread out into three/four steps | |
| # - if enum_class is a Flag: | |
| # - remove any non-single-bit flags from _order_ | |
| # - remove any aliases from _order_ | |
| # - check that _order_ and _member_names_ match | |
| # | |
| # step 1: ensure we have a list | |
| if _order_ is not None: | |
| if isinstance(_order_, str): | |
| _order_ = _order_.replace(',', ' ').split() | |
| # | |
| # remove Flag structures if final class is not a Flag | |
| if ( | |
| Flag is None and cls != 'Flag' | |
| or Flag is not None and not issubclass(enum_class, Flag) | |
| ): | |
| delattr(enum_class, '_boundary_') | |
| delattr(enum_class, '_flag_mask_') | |
| delattr(enum_class, '_all_bits_') | |
| delattr(enum_class, '_inverted_') | |
| elif Flag is not None and issubclass(enum_class, Flag): | |
| # ensure _all_bits_ is correct and there are no missing flags | |
| single_bit_total = 0 | |
| multi_bit_total = 0 | |
| for flag in enum_class._member_map_.values(): | |
| flag_value = flag._value_ | |
| if _is_single_bit(flag_value): | |
| single_bit_total |= flag_value | |
| else: | |
| # multi-bit flags are considered aliases | |
| multi_bit_total |= flag_value | |
| enum_class._flag_mask_ = single_bit_total | |
| # | |
| # set correct __iter__ | |
| member_list = [m._value_ for m in enum_class] | |
| if member_list != sorted(member_list): | |
| enum_class._iter_member_ = enum_class._iter_member_by_def_ | |
| if _order_: | |
| # _order_ step 2: remove any items from _order_ that are not single-bit | |
| _order_ = [ | |
| o | |
| for o in _order_ | |
| if o not in enum_class._member_map_ or _is_single_bit(enum_class[o]._value_) | |
| ] | |
| # | |
| if _order_: | |
| # _order_ step 3: remove aliases from _order_ | |
| _order_ = [ | |
| o | |
| for o in _order_ | |
| if ( | |
| o not in enum_class._member_map_ | |
| or | |
| (o in enum_class._member_map_ and o in enum_class._member_names_) | |
| )] | |
| # _order_ step 4: verify that _order_ and _member_names_ match | |
| if _order_ != enum_class._member_names_: | |
| raise TypeError( | |
| 'member order does not match _order_:\n%r\n%r' | |
| % (enum_class._member_names_, _order_) | |
| ) | |
| # | |
| return enum_class | |
| def __bool__(self): | |
| """ | |
| classes/types should always be True. | |
| """ | |
| return True | |
| def __call__(cls, value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None): | |
| """ | |
| 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 | |
| (i.e. Color = Enum('Color', names='RED GREEN BLUE')). | |
| When used for the functional API: | |
| `value` will be the name of the new class. | |
| `names` should be either a string of white-space/comma delimited names | |
| (values will start at `start`), or an iterator/mapping of name, value pairs. | |
| `module` should be set to the module this class is being created in; | |
| if it is not set, an attempt to find that module will be made, but if | |
| it fails the class will not be picklable. | |
| `qualname` should be set to the actual location this class can be found | |
| at in its module; by default it is set to the global scope. If this is | |
| 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, | |
| boundary=boundary, | |
| ) | |
| def __contains__(cls, member): | |
| if not isinstance(member, Enum): | |
| import warnings | |
| warnings.warn( | |
| "in 3.12 __contains__ will no longer raise TypeError, but will return True or\n" | |
| "False depending on whether the value is a member or the value of a member", | |
| DeprecationWarning, | |
| stacklevel=2, | |
| ) | |
| raise TypeError( | |
| "unsupported operand type(s) for 'in': '%s' and '%s'" % ( | |
| type(member).__qualname__, cls.__class__.__qualname__)) | |
| return isinstance(member, cls) and member._name_ in cls._member_map_ | |
| def __delattr__(cls, attr): | |
| # 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 %r." % (cls.__name__, attr)) | |
| super().__delattr__(attr) | |
| def __dir__(self): | |
| return ( | |
| ['__class__', '__doc__', '__members__', '__module__'] | |
| + self._member_names_ | |
| ) | |
| def __getattr__(cls, 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) | |
| try: | |
| return cls._member_map_[name] | |
| except KeyError: | |
| raise AttributeError(name) from None | |
| def __getitem__(cls, name): | |
| 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): | |
| return len(cls._member_names_) | |
| @_bltin_property | |
| def __members__(cls): | |
| """ | |
| 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_) | |
| def __repr__(cls): | |
| if Flag is not None and issubclass(cls, Flag): | |
| return "<flag %r>" % cls.__name__ | |
| else: | |
| 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. | |
| 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: | |
| raise AttributeError('Cannot reassign member %r.' % (name, )) | |
| super().__setattr__(name, value) | |
| def _create_(cls, class_name, names, *, module=None, qualname=None, type=None, start=1, boundary=None): | |
| """ | |
| Convenience method to create a new Enum class. | |
| `names` can be: | |
| * A string containing member names, separated either with spaces or | |
| commas. Values are incremented by 1 from `start`. | |
| * 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) | |
| _, first_enum = cls._get_mixins_(cls, bases) | |
| classdict = metacls.__prepare__(class_name, bases) | |
| # special processing needed for names? | |
| if isinstance(names, str): | |
| names = names.replace(',', ' ').split() | |
| if isinstance(names, (tuple, list)) and names and isinstance(names[0], str): | |
| original_names, names = names, [] | |
| last_values = [] | |
| for count, name in enumerate(original_names): | |
| value = first_enum._generate_next_value_(name, start, count, last_values[:]) | |
| last_values.append(value) | |
| names.append((name, value)) | |
| # Here, names is either an iterable of (name, value) or a mapping. | |
| for item in names: | |
| if isinstance(item, str): | |
| member_name, member_value = item, names[item] | |
| else: | |
| member_name, member_value = item | |
| classdict[member_name] = member_value | |
| # TODO: replace the frame hack if a blessed way to know the calling | |
| # module is ever developed | |
| if module is None: | |
| try: | |
| module = sys._getframe(2).f_globals['__name__'] | |
| except (AttributeError, ValueError, KeyError): | |
| pass | |
| if module is None: | |
| _make_class_unpicklable(classdict) | |
| else: | |
| classdict['__module__'] = module | |
| if qualname is not None: | |
| classdict['__qualname__'] = qualname | |
| return metacls.__new__(metacls, class_name, bases, classdict, boundary=boundary) | |
| def _convert_(cls, name, module, filter, source=None, *, boundary=None): | |
| """ | |
| Create a new Enum subclass that replaces a collection of global constants | |
| """ | |
| # convert all constants from source (or module) that pass filter() to | |
| # a new Enum called name, and export the enum and its members back to | |
| # module; | |
| # also, replace the __reduce_ex__ method so unpickling works in | |
| # previous Python versions | |
| module_globals = sys.modules[module].__dict__ | |
| if source: | |
| source = source.__dict__ | |
| else: | |
| source = module_globals | |
| # _value2member_map_ is populated in the same order every time | |
| # for a consistent reverse mapping of number to name when there | |
| # are multiple names for the same number. | |
| members = [ | |
| (name, value) | |
| for name, value in source.items() | |
| if filter(name)] | |
| try: | |
| # sort by value | |
| members.sort(key=lambda t: (t[1], t[0])) | |
| except TypeError: | |
| # unless some values aren't comparable, in which case sort by name | |
| members.sort(key=lambda t: t[0]) | |
| body = {t[0]: t[1] for t in members} | |
| body['__module__'] = module | |
| tmp_cls = type(name, (object, ), body) | |
| cls = _simple_enum(etype=cls, boundary=boundary or KEEP)(tmp_cls) | |
| cls.__reduce_ex__ = _reduce_ex_by_global_name | |
| global_enum(cls) | |
| module_globals[name] = cls | |
| return cls | |
| @staticmethod | |
| def _check_for_existing_members(class_name, bases): | |
| 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__) | |
| ) | |
| @staticmethod | |
| def _get_mixins_(class_name, bases): | |
| """ | |
| 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 | |
| def _find_data_type(bases): | |
| data_types = set() | |
| for chain in bases: | |
| candidate = None | |
| for base in chain.__mro__: | |
| if base is object: | |
| continue | |
| elif issubclass(base, Enum): | |
| if base._member_type_ is not object: | |
| data_types.add(base._member_type_) | |
| break | |
| elif '__new__' in base.__dict__: | |
| if issubclass(base, Enum): | |
| continue | |
| data_types.add(candidate or base) | |
| break | |
| else: | |
| candidate = candidate or base | |
| if len(data_types) > 1: | |
| raise TypeError('%r: too many data types: %r' % (class_name, data_types)) | |
| elif data_types: | |
| return data_types.pop() | |
| else: | |
| return None | |
| # ensure final parent class is an Enum derivative, find any concrete | |
| # data type, and check that Enum has no members | |
| first_enum = bases[-1] | |
| if not issubclass(first_enum, Enum): | |
| raise TypeError("new enumerations should be created as " | |
| "`EnumName([mixin_type, ...] [data_type,] enum_type)`") | |
| member_type = _find_data_type(bases) or object | |
| if first_enum._member_names_: | |
| raise TypeError("Cannot extend enumerations") | |
| return member_type, first_enum | |
| @staticmethod | |
| def _find_new_(classdict, member_type, first_enum): | |
| """ | |
| 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 | |
| # saved as __new_member__ | |
| __new__ = classdict.get('__new__', None) | |
| # should __new__ be saved as __new_member__ later? | |
| save_new = first_enum is not None and __new__ is not None | |
| if __new__ is None: | |
| # check all possibles for __new_member__ before falling back to | |
| # __new__ | |
| for method in ('__new_member__', '__new__'): | |
| for possible in (member_type, first_enum): | |
| target = getattr(possible, method, None) | |
| if target not in { | |
| None, | |
| None.__new__, | |
| object.__new__, | |
| Enum.__new__, | |
| }: | |
| __new__ = target | |
| break | |
| if __new__ is not None: | |
| break | |
| else: | |
| __new__ = object.__new__ | |
| # if a non-object.__new__ is used then whatever value/tuple was | |
| # assigned to the enum member name will be passed to __new__ and to the | |
| # new enum member's __init__ | |
| if first_enum is None or __new__ in (Enum.__new__, object.__new__): | |
| use_args = False | |
| else: | |
| use_args = True | |
| return __new__, save_new, use_args | |
| EnumMeta = EnumType | |
| class Enum(metaclass=EnumType): | |
| """ | |
| Generic enumeration. | |
| Derive from this class to define new enumerations. | |
| """ | |
| def __new__(cls, value): | |
| # all enum instances are actually created during class construction | |
| # without calling this method; this method is called by the metaclass' | |
| # __call__ (i.e. Color(3) ), and by pickle | |
| if type(value) is cls: | |
| # For lookups like Color(Color.RED) | |
| return value | |
| # by-value search for a matching enum member | |
| # see if it's in the reverse mapping (for hashable values) | |
| try: | |
| return cls._value2member_map_[value] | |
| except KeyError: | |
| # Not found, no need to do long O(n) search | |
| pass | |
| except TypeError: | |
| # not there, now do long search -- O(n) behavior | |
| for member in cls._member_map_.values(): | |
| if member._value_ == value: | |
| return member | |
| # still not found -- try _missing_ hook | |
| try: | |
| exc = None | |
| result = cls._missing_(value) | |
| except Exception as e: | |
| exc = e | |
| result = None | |
| try: | |
| if isinstance(result, cls): | |
| return result | |
| elif ( | |
| Flag is not None and issubclass(cls, Flag) | |
| and cls._boundary_ is EJECT and isinstance(result, int) | |
| ): | |
| return result | |
| else: | |
| ve_exc = ValueError("%r is not a valid %s" % (value, cls.__qualname__)) | |
| if result is None and exc is None: | |
| raise ve_exc | |
| elif exc is None: | |
| exc = TypeError( | |
| 'error in %s._missing_: returned %r instead of None or a valid member' | |
| % (cls.__name__, result) | |
| ) | |
| if not isinstance(exc, ValueError): | |
| exc.__context__ = ve_exc | |
| raise exc | |
| finally: | |
| # ensure all variables that could hold an exception are destroyed | |
| exc = None | |
| ve_exc = None | |
| 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 | |
| except TypeError: | |
| pass | |
| else: | |
| return start | |
| @classmethod | |
| def _missing_(cls, value): | |
| return None | |
| def __repr__(self): | |
| return "%s.%s" % ( self.__class__.__name__, self._name_) | |
| def __str__(self): | |
| return "%s" % (self._name_, ) | |
| def __dir__(self): | |
| """ | |
| Returns all members and all public methods | |
| """ | |
| added_behavior = [ | |
| m | |
| for cls in self.__class__.mro() | |
| for m in cls.__dict__ | |
| if m[0] != '_' and m not in self._member_map_ | |
| ] + [m for m in self.__dict__ if m[0] != '_'] | |
| 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__ not in (Enum.__str__, IntEnum.__str__, Flag.__str__) | |
| if self._member_type_ is object or str_overridden: | |
| cls = str | |
| val = str(self) | |
| # mix-in branch | |
| else: | |
| if not format_spec or format_spec in ('{}','{:}'): | |
| import warnings | |
| warnings.warn( | |
| "in 3.12 format() will use the enum member, not the enum member's value;\n" | |
| "use a format specifier, such as :d for an integer-based Enum, to maintain " | |
| "the current display", | |
| DeprecationWarning, | |
| stacklevel=2, | |
| ) | |
| cls = self._member_type_ | |
| val = self._value_ | |
| return cls.__format__(val, format_spec) | |
| def __hash__(self): | |
| return hash(self._name_) | |
| def __reduce_ex__(self, proto): | |
| return getattr, (self.__class__, self._name_) | |
| # enum.property is used to provide access to the `name` and | |
| # `value` attributes of enum members while keeping some measure of | |
| # protection from modification, while still allowing for an enumeration | |
| # to have members named `name` and `value`. This works because enumeration | |
| # members are not set directly on the enum class; they are kept in a | |
| # separate structure, _member_map_, which is where enum.property looks for | |
| # them | |
| @property | |
| def name(self): | |
| """The name of the Enum member.""" | |
| return self._name_ | |
| @property | |
| def value(self): | |
| """The value of the Enum member.""" | |
| return self._value_ | |
| class IntEnum(int, Enum): | |
| """ | |
| Enum where members are also (and must be) ints | |
| """ | |
| def __str__(self): | |
| return "%s" % (self._name_, ) | |
| def __format__(self, format_spec): | |
| """ | |
| Returns format using actual value unless __str__ has been overridden. | |
| """ | |
| str_overridden = type(self).__str__ != IntEnum.__str__ | |
| if str_overridden: | |
| cls = str | |
| val = str(self) | |
| else: | |
| cls = self._member_type_ | |
| val = self._value_ | |
| return cls.__format__(val, format_spec) | |
| class StrEnum(str, Enum): | |
| """ | |
| Enum where members are also (and must be) strings | |
| """ | |
| def __new__(cls, *values): | |
| if len(values) > 3: | |
| raise TypeError('too many arguments for str(): %r' % (values, )) | |
| if len(values) == 1: | |
| # it must be a string | |
| if not isinstance(values[0], str): | |
| raise TypeError('%r is not a string' % (values[0], )) | |
| if len(values) >= 2: | |
| # check that encoding argument is a string | |
| if not isinstance(values[1], str): | |
| raise TypeError('encoding must be a string, not %r' % (values[1], )) | |
| if len(values) == 3: | |
| # check that errors argument is a string | |
| if not isinstance(values[2], str): | |
| raise TypeError('errors must be a string, not %r' % (values[2])) | |
| value = str(*values) | |
| member = str.__new__(cls, value) | |
| member._value_ = value | |
| return member | |
| __str__ = str.__str__ | |
| __format__ = str.__format__ | |
| 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_global_name(self, proto): | |
| return self.name | |
| class FlagBoundary(StrEnum): | |
| """ | |
| control how out of range values are handled | |
| "strict" -> error is raised [default for Flag] | |
| "conform" -> extra bits are discarded | |
| "eject" -> lose flag status [default for IntFlag] | |
| "keep" -> keep flag status and all bits | |
| """ | |
| STRICT = auto() | |
| CONFORM = auto() | |
| EJECT = auto() | |
| KEEP = auto() | |
| STRICT, CONFORM, EJECT, KEEP = FlagBoundary | |
| class Flag(Enum, boundary=STRICT): | |
| """ | |
| Support for flags | |
| """ | |
| 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 | |
| """ | |
| if not count: | |
| return start if start is not None else 1 | |
| last_value = max(last_values) | |
| try: | |
| high_bit = _high_bit(last_value) | |
| except Exception: | |
| raise TypeError('Invalid Flag value: %r' % last_value) from None | |
| return 2 ** (high_bit+1) | |
| @classmethod | |
| def _iter_member_by_value_(cls, value): | |
| """ | |
| Extract all members from the value in definition (i.e. increasing value) order. | |
| """ | |
| for val in _iter_bits_lsb(value & cls._flag_mask_): | |
| yield cls._value2member_map_.get(val) | |
| _iter_member_ = _iter_member_by_value_ | |
| @classmethod | |
| def _iter_member_by_def_(cls, value): | |
| """ | |
| Extract all members from the value in definition order. | |
| """ | |
| yield from sorted( | |
| cls._iter_member_by_value_(value), | |
| key=lambda m: m._sort_order_, | |
| ) | |
| @classmethod | |
| def _missing_(cls, value): | |
| """ | |
| Create a composite member containing all canonical members present in `value`. | |
| If non-member values are present, result depends on `_boundary_` setting. | |
| """ | |
| if not isinstance(value, int): | |
| raise ValueError( | |
| "%r is not a valid %s" % (value, cls.__qualname__) | |
| ) | |
| # check boundaries | |
| # - value must be in range (e.g. -16 <-> +15, i.e. ~15 <-> 15) | |
| # - value must not include any skipped flags (e.g. if bit 2 is not | |
| # defined, then 0d10 is invalid) | |
| flag_mask = cls._flag_mask_ | |
| all_bits = cls._all_bits_ | |
| neg_value = None | |
| if ( | |
| not ~all_bits <= value <= all_bits | |
| or value & (all_bits ^ flag_mask) | |
| ): | |
| if cls._boundary_ is STRICT: | |
| max_bits = max(value.bit_length(), flag_mask.bit_length()) | |
| raise ValueError( | |
| "%s: invalid value: %r\n given %s\n allowed %s" % ( | |
| cls.__name__, value, bin(value, max_bits), bin(flag_mask, max_bits), | |
| )) | |
| elif cls._boundary_ is CONFORM: | |
| value = value & flag_mask | |
| elif cls._boundary_ is EJECT: | |
| return value | |
| elif cls._boundary_ is KEEP: | |
| if value < 0: | |
| value = ( | |
| max(all_bits+1, 2**(value.bit_length())) | |
| + value | |
| ) | |
| else: | |
| raise ValueError( | |
| 'unknown flag boundary: %r' % (cls._boundary_, ) | |
| ) | |
| if value < 0: | |
| neg_value = value | |
| value = all_bits + 1 + value | |
| # get members and unknown | |
| unknown = value & ~flag_mask | |
| member_value = value & flag_mask | |
| if unknown and cls._boundary_ is not KEEP: | |
| raise ValueError( | |
| '%s(%r) --> unknown values %r [%s]' | |
| % (cls.__name__, value, unknown, bin(unknown)) | |
| ) | |
| # normal Flag? | |
| __new__ = getattr(cls, '__new_member__', None) | |
| if cls._member_type_ is object and not __new__: | |
| # construct a singleton enum pseudo-member | |
| pseudo_member = object.__new__(cls) | |
| else: | |
| pseudo_member = (__new__ or cls._member_type_.__new__)(cls, value) | |
| if not hasattr(pseudo_member, '_value_'): | |
| pseudo_member._value_ = value | |
| if member_value: | |
| pseudo_member._name_ = '|'.join([ | |
| m._name_ for m in cls._iter_member_(member_value) | |
| ]) | |
| if unknown: | |
| pseudo_member._name_ += '|0x%x' % unknown | |
| else: | |
| pseudo_member._name_ = None | |
| # use setdefault in case another thread already created a composite | |
| # with this value, but only if all members are known | |
| # note: zero is a special case -- add it | |
| if not unknown: | |
| pseudo_member = cls._value2member_map_.setdefault(value, pseudo_member) | |
| if neg_value is not None: | |
| cls._value2member_map_[neg_value] = pseudo_member | |
| 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'" % ( | |
| type(other).__qualname__, self.__class__.__qualname__)) | |
| if other._value_ == 0 or self._value_ == 0: | |
| return False | |
| return other._value_ & self._value_ == other._value_ | |
| def __iter__(self): | |
| """ | |
| Returns flags in definition order. | |
| """ | |
| yield from self._iter_member_(self._value_) | |
| def __len__(self): | |
| return self._value_.bit_count() | |
| def __repr__(self): | |
| cls_name = self.__class__.__name__ | |
| if self._name_ is None: | |
| return "0x%x" % (self._value_, ) | |
| if _is_single_bit(self._value_): | |
| return '%s.%s' % (cls_name, self._name_) | |
| if self._boundary_ is not FlagBoundary.KEEP: | |
| return '%s.' % cls_name + ('|%s.' % cls_name).join(self.name.split('|')) | |
| else: | |
| name = [] | |
| for n in self._name_.split('|'): | |
| if n.startswith('0'): | |
| name.append(n) | |
| else: | |
| name.append('%s.%s' % (cls_name, n)) | |
| return '|'.join(name) | |
| def __str__(self): | |
| cls = self.__class__ | |
| if self._name_ is None: | |
| return '%s(%x)' % (cls.__name__, self._value_) | |
| else: | |
| return self._name_ | |
| def __bool__(self): | |
| return bool(self._value_) | |
| def __or__(self, other): | |
| if not isinstance(other, self.__class__): | |
| return NotImplemented | |
| return self.__class__(self._value_ | other._value_) | |
| def __and__(self, other): | |
| if not isinstance(other, self.__class__): | |
| return NotImplemented | |
| return self.__class__(self._value_ & other._value_) | |
| def __xor__(self, other): | |
| if not isinstance(other, self.__class__): | |
| return NotImplemented | |
| return self.__class__(self._value_ ^ other._value_) | |
| def __invert__(self): | |
| if self._inverted_ is None: | |
| if self._boundary_ is KEEP: | |
| # use all bits | |
| self._inverted_ = self.__class__(~self._value_) | |
| else: | |
| # calculate flags not in this member | |
| self._inverted_ = self.__class__(self._flag_mask_ ^ self._value_) | |
| if isinstance(self._inverted_, self.__class__): | |
| self._inverted_._inverted_ = self | |
| return self._inverted_ | |
| class IntFlag(int, Flag, boundary=EJECT): | |
| """ | |
| Support for integer-based Flags | |
| """ | |
| def __format__(self, format_spec): | |
| """ | |
| Returns format using actual value unless __str__ has been overridden. | |
| """ | |
| str_overridden = type(self).__str__ != Flag.__str__ | |
| value = self | |
| if not str_overridden: | |
| value = self._value_ | |
| return int.__format__(value, format_spec) | |
| def __or__(self, other): | |
| if isinstance(other, self.__class__): | |
| other = other._value_ | |
| elif isinstance(other, int): | |
| other = other | |
| else: | |
| return NotImplemented | |
| value = self._value_ | |
| return self.__class__(value | other) | |
| def __and__(self, other): | |
| if isinstance(other, self.__class__): | |
| other = other._value_ | |
| elif isinstance(other, int): | |
| other = other | |
| else: | |
| return NotImplemented | |
| value = self._value_ | |
| return self.__class__(value & other) | |
| def __xor__(self, other): | |
| if isinstance(other, self.__class__): | |
| other = other._value_ | |
| elif isinstance(other, int): | |
| other = other | |
| else: | |
| return NotImplemented | |
| value = self._value_ | |
| return self.__class__(value ^ other) | |
| __ror__ = __or__ | |
| __rand__ = __and__ | |
| __rxor__ = __xor__ | |
| __invert__ = Flag.__invert__ | |
| def _high_bit(value): | |
| """ | |
| 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. | |
| """ | |
| duplicates = [] | |
| for name, member in enumeration.__members__.items(): | |
| if name != member.name: | |
| duplicates.append((name, member.name)) | |
| if duplicates: | |
| alias_details = ', '.join( | |
| ["%s -> %s" % (alias, name) for (alias, name) in duplicates]) | |
| raise ValueError('duplicate values found in %r: %s' % | |
| (enumeration, alias_details)) | |
| return enumeration | |
| def _power_of_two(value): | |
| if value < 1: | |
| return False | |
| return value == 2 ** _high_bit(value) | |
| def global_enum_repr(self): | |
| return '%s.%s' % (self.__class__.__module__, self._name_) | |
| def global_flag_repr(self): | |
| module = self.__class__.__module__ | |
| cls_name = self.__class__.__name__ | |
| if self._name_ is None: | |
| return "%x" % (module, cls_name, self._value_) | |
| if _is_single_bit(self): | |
| return '%s.%s' % (module, self._name_) | |
| if self._boundary_ is not FlagBoundary.KEEP: | |
| return module + module.join(self.name.split('|')) | |
| else: | |
| name = [] | |
| for n in self._name_.split('|'): | |
| if n.startswith('0'): | |
| name.append(n) | |
| else: | |
| name.append('%s.%s' % (module, n)) | |
| return '|'.join(name) | |
| def global_enum(cls): | |
| """ | |
| decorator that makes the repr() of an enum member reference its module | |
| instead of its class; also exports all members to the enum's module's | |
| global namespace | |
| """ | |
| if issubclass(cls, Flag): | |
| cls.__repr__ = global_flag_repr | |
| else: | |
| cls.__repr__ = global_enum_repr | |
| sys.modules[cls.__module__].__dict__.update(cls.__members__) | |
| return cls | |
| def _simple_enum(etype=Enum, *, boundary=None, use_args=None): | |
| """ | |
| Class decorator that converts a normal class into an :class:`Enum`. No | |
| safety checks are done, and some advanced behavior (such as | |
| :func:`__init_subclass__`) is not available. Enum creation can be faster | |
| using :func:`simple_enum`. | |
| >>> from enum import Enum, _simple_enum | |
| >>> @_simple_enum(Enum) | |
| ... class Color: | |
| ... RED = auto() | |
| ... GREEN = auto() | |
| ... BLUE = auto() | |
| >>> Color | |
| <enum 'Color'> | |
| """ | |
| def convert_class(cls): | |
| nonlocal use_args | |
| cls_name = cls.__name__ | |
| if use_args is None: | |
| use_args = etype._use_args_ | |
| __new__ = cls.__dict__.get('__new__') | |
| if __new__ is not None: | |
| new_member = __new__.__func__ | |
| else: | |
| new_member = etype._member_type_.__new__ | |
| attrs = {} | |
| body = {} | |
| if __new__ is not None: | |
| body['__new_member__'] = new_member | |
| body['_new_member_'] = new_member | |
| body['_use_args_'] = use_args | |
| body['_generate_next_value_'] = gnv = etype._generate_next_value_ | |
| body['_member_names_'] = member_names = [] | |
| body['_member_map_'] = member_map = {} | |
| body['_value2member_map_'] = value2member_map = {} | |
| body['_unhashable_values_'] = [] | |
| body['_member_type_'] = member_type = etype._member_type_ | |
| if issubclass(etype, Flag): | |
| body['_boundary_'] = boundary or etype._boundary_ | |
| body['_flag_mask_'] = None | |
| body['_all_bits_'] = None | |
| body['_inverted_'] = None | |
| for name, obj in cls.__dict__.items(): | |
| if name in ('__dict__', '__weakref__'): | |
| continue | |
| if _is_dunder(name) or _is_private(cls_name, name) or _is_sunder(name) or _is_descriptor(obj): | |
| body[name] = obj | |
| else: | |
| attrs[name] = obj | |
| if cls.__dict__.get('__doc__') is None: | |
| body['__doc__'] = 'An enumeration.' | |
| # | |
| # double check that repr and friends are not the mixin's or various | |
| # things break (such as pickle) | |
| # however, if the method is defined in the Enum itself, don't replace | |
| # it | |
| enum_class = type(cls_name, (etype, ), body, boundary=boundary, _simple=True) | |
| for name in ('__repr__', '__str__', '__format__', '__reduce_ex__'): | |
| if name in body: | |
| continue | |
| class_method = getattr(enum_class, name) | |
| obj_method = getattr(member_type, name, None) | |
| enum_method = getattr(etype, name, None) | |
| if obj_method is not None and obj_method is class_method: | |
| setattr(enum_class, name, enum_method) | |
| gnv_last_values = [] | |
| if issubclass(enum_class, Flag): | |
| # Flag / IntFlag | |
| single_bits = multi_bits = 0 | |
| for name, value in attrs.items(): | |
| if isinstance(value, auto) and auto.value is _auto_null: | |
| value = gnv(name, 1, len(member_names), gnv_last_values) | |
| if value in value2member_map: | |
| # an alias to an existing member | |
| redirect = property() | |
| redirect.__set_name__(enum_class, name) | |
| setattr(enum_class, name, redirect) | |
| member_map[name] = value2member_map[value] | |
| else: | |
| # create the member | |
| if use_args: | |
| if not isinstance(value, tuple): | |
| value = (value, ) | |
| member = new_member(enum_class, *value) | |
| value = value[0] | |
| else: | |
| member = new_member(enum_class) | |
| if __new__ is None: | |
| member._value_ = value | |
| member._name_ = name | |
| member.__objclass__ = enum_class | |
| member.__init__(value) | |
| redirect = property() | |
| redirect.__set_name__(enum_class, name) | |
| setattr(enum_class, name, redirect) | |
| member_map[name] = member | |
| member._sort_order_ = len(member_names) | |
| value2member_map[value] = member | |
| if _is_single_bit(value): | |
| # not a multi-bit alias, record in _member_names_ and _flag_mask_ | |
| member_names.append(name) | |
| single_bits |= value | |
| else: | |
| multi_bits |= value | |
| gnv_last_values.append(value) | |
| enum_class._flag_mask_ = single_bits | |
| enum_class._all_bits_ = 2 ** ((single_bits|multi_bits).bit_length()) - 1 | |
| # set correct __iter__ | |
| member_list = [m._value_ for m in enum_class] | |
| if member_list != sorted(member_list): | |
| enum_class._iter_member_ = enum_class._iter_member_by_def_ | |
| else: | |
| # Enum / IntEnum / StrEnum | |
| for name, value in attrs.items(): | |
| if isinstance(value, auto): | |
| if value.value is _auto_null: | |
| value.value = gnv(name, 1, len(member_names), gnv_last_values) | |
| value = value.value | |
| if value in value2member_map: | |
| # an alias to an existing member | |
| redirect = property() | |
| redirect.__set_name__(enum_class, name) | |
| setattr(enum_class, name, redirect) | |
| member_map[name] = value2member_map[value] | |
| else: | |
| # create the member | |
| if use_args: | |
| if not isinstance(value, tuple): | |
| value = (value, ) | |
| member = new_member(enum_class, *value) | |
| value = value[0] | |
| else: | |
| member = new_member(enum_class) | |
| if __new__ is None: | |
| member._value_ = value | |
| member._name_ = name | |
| member.__objclass__ = enum_class | |
| member.__init__(value) | |
| member._sort_order_ = len(member_names) | |
| redirect = property() | |
| redirect.__set_name__(enum_class, name) | |
| setattr(enum_class, name, redirect) | |
| member_map[name] = member | |
| value2member_map[value] = member | |
| member_names.append(name) | |
| gnv_last_values.append(value) | |
| if '__new__' in body: | |
| enum_class.__new_member__ = enum_class.__new__ | |
| enum_class.__new__ = Enum.__new__ | |
| return enum_class | |
| return convert_class | |
| @_simple_enum(StrEnum) | |
| class EnumCheck: | |
| """ | |
| various conditions to check an enumeration for | |
| """ | |
| CONTINUOUS = "no skipped integer values" | |
| NAMED_FLAGS = "multi-flag aliases may not contain unnamed flags" | |
| UNIQUE = "one name per value" | |
| CONTINUOUS, NAMED_FLAGS, UNIQUE = EnumCheck | |
| class verify: | |
| """ | |
| Check an enumeration for various constraints. (see EnumCheck) | |
| """ | |
| def __init__(self, *checks): | |
| self.checks = checks | |
| def __call__(self, enumeration): | |
| checks = self.checks | |
| cls_name = enumeration.__name__ | |
| if Flag is not None and issubclass(enumeration, Flag): | |
| enum_type = 'flag' | |
| elif issubclass(enumeration, Enum): | |
| enum_type = 'enum' | |
| else: | |
| raise TypeError("the 'verify' decorator only works with Enum and Flag") | |
| for check in checks: | |
| if check is UNIQUE: | |
| # check for duplicate names | |
| duplicates = [] | |
| for name, member in enumeration.__members__.items(): | |
| if name != member.name: | |
| duplicates.append((name, member.name)) | |
| if duplicates: | |
| alias_details = ', '.join( | |
| ["%s -> %s" % (alias, name) for (alias, name) in duplicates]) | |
| raise ValueError('aliases found in %r: %s' % | |
| (enumeration, alias_details)) | |
| elif check is CONTINUOUS: | |
| values = set(e.value for e in enumeration) | |
| if len(values) < 2: | |
| continue | |
| low, high = min(values), max(values) | |
| missing = [] | |
| if enum_type == 'flag': | |
| # check for powers of two | |
| for i in range(_high_bit(low)+1, _high_bit(high)): | |
| if 2**i not in values: | |
| missing.append(2**i) | |
| elif enum_type == 'enum': | |
| # check for powers of one | |
| for i in range(low+1, high): | |
| if i not in values: | |
| missing.append(i) | |
| else: | |
| raise Exception('verify: unknown type %r' % enum_type) | |
| if missing: | |
| raise ValueError(('invalid %s %r: missing values %s' % ( | |
| enum_type, cls_name, ', '.join((str(m) for m in missing))) | |
| )[:256]) | |
| # limit max length to protect against DOS attacks | |
| elif check is NAMED_FLAGS: | |
| # examine each alias and check for unnamed flags | |
| member_names = enumeration._member_names_ | |
| member_values = [m.value for m in enumeration] | |
| missing_names = [] | |
| missing_value = 0 | |
| for name, alias in enumeration._member_map_.items(): | |
| if name in member_names: | |
| # not an alias | |
| continue | |
| values = list(_iter_bits_lsb(alias.value)) | |
| missed = [v for v in values if v not in member_values] | |
| if missed: | |
| missing_names.append(name) | |
| missing_value |= reduce(_or_, missed) | |
| if missing_names: | |
| if len(missing_names) == 1: | |
| alias = 'alias %s is missing' % missing_names[0] | |
| else: | |
| alias = 'aliases %s and %s are missing' % ( | |
| ', '.join(missing_names[:-1]), missing_names[-1] | |
| ) | |
| if _is_single_bit(missing_value): | |
| value = 'value 0x%x' % missing_value | |
| else: | |
| value = 'combined values of 0x%x' % missing_value | |
| raise ValueError( | |
| 'invalid Flag %r: %s %s [use enum.show_flag_values(value) for details]' | |
| % (cls_name, alias, value) | |
| ) | |
| return enumeration | |
| def _test_simple_enum(checked_enum, simple_enum): | |
| """ | |
| A function that can be used to test an enum created with :func:`_simple_enum` | |
| against the version created by subclassing :class:`Enum`:: | |
| >>> from enum import Enum, _simple_enum, _test_simple_enum | |
| >>> @_simple_enum(Enum) | |
| ... class Color: | |
| ... RED = auto() | |
| ... GREEN = auto() | |
| ... BLUE = auto() | |
| >>> class CheckedColor(Enum): | |
| ... RED = auto() | |
| ... GREEN = auto() | |
| ... BLUE = auto() | |
| >>> _test_simple_enum(CheckedColor, Color) | |
| If differences are found, a :exc:`TypeError` is raised. | |
| """ | |
| failed = [] | |
| if checked_enum.__dict__ != simple_enum.__dict__: | |
| checked_dict = checked_enum.__dict__ | |
| checked_keys = list(checked_dict.keys()) | |
| simple_dict = simple_enum.__dict__ | |
| simple_keys = list(simple_dict.keys()) | |
| member_names = set( | |
| list(checked_enum._member_map_.keys()) | |
| + list(simple_enum._member_map_.keys()) | |
| ) | |
| for key in set(checked_keys + simple_keys): | |
| if key in ('__module__', '_member_map_', '_value2member_map_'): | |
| # keys known to be different | |
| continue | |
| elif key in member_names: | |
| # members are checked below | |
| continue | |
| elif key not in simple_keys: | |
| failed.append("missing key: %r" % (key, )) | |
| elif key not in checked_keys: | |
| failed.append("extra key: %r" % (key, )) | |
| else: | |
| checked_value = checked_dict[key] | |
| simple_value = simple_dict[key] | |
| if callable(checked_value): | |
| continue | |
| if key == '__doc__': | |
| # remove all spaces/tabs | |
| compressed_checked_value = checked_value.replace(' ','').replace('\t','') | |
| compressed_simple_value = simple_value.replace(' ','').replace('\t','') | |
| if compressed_checked_value != compressed_simple_value: | |
| failed.append("%r:\n %s\n %s" % ( | |
| key, | |
| "checked -> %r" % (checked_value, ), | |
| "simple -> %r" % (simple_value, ), | |
| )) | |
| elif checked_value != simple_value: | |
| failed.append("%r:\n %s\n %s" % ( | |
| key, | |
| "checked -> %r" % (checked_value, ), | |
| "simple -> %r" % (simple_value, ), | |
| )) | |
| failed.sort() | |
| for name in member_names: | |
| failed_member = [] | |
| if name not in simple_keys: | |
| failed.append('missing member from simple enum: %r' % name) | |
| elif name not in checked_keys: | |
| failed.append('extra member in simple enum: %r' % name) | |
| else: | |
| checked_member_dict = checked_enum[name].__dict__ | |
| checked_member_keys = list(checked_member_dict.keys()) | |
| simple_member_dict = simple_enum[name].__dict__ | |
| simple_member_keys = list(simple_member_dict.keys()) | |
| for key in set(checked_member_keys + simple_member_keys): | |
| if key in ('__module__', '__objclass__', '_inverted_'): | |
| # keys known to be different or absent | |
| continue | |
| elif key not in simple_member_keys: | |
| failed_member.append("missing key %r not in the simple enum member %r" % (key, name)) | |
| elif key not in checked_member_keys: | |
| failed_member.append("extra key %r in simple enum member %r" % (key, name)) | |
| else: | |
| checked_value = checked_member_dict[key] | |
| simple_value = simple_member_dict[key] | |
| if checked_value != simple_value: | |
| failed_member.append("%r:\n %s\n %s" % ( | |
| key, | |
| "checked member -> %r" % (checked_value, ), | |
| "simple member -> %r" % (simple_value, ), | |
| )) | |
| if failed_member: | |
| failed.append('%r member mismatch:\n %s' % ( | |
| name, '\n '.join(failed_member), | |
| )) | |
| for method in ( | |
| '__str__', '__repr__', '__reduce_ex__', '__format__', | |
| '__getnewargs_ex__', '__getnewargs__', '__reduce_ex__', '__reduce__' | |
| ): | |
| if method in simple_keys and method in checked_keys: | |
| # cannot compare functions, and it exists in both, so we're good | |
| continue | |
| elif method not in simple_keys and method not in checked_keys: | |
| # method is inherited -- check it out | |
| checked_method = getattr(checked_enum, method, None) | |
| simple_method = getattr(simple_enum, method, None) | |
| if hasattr(checked_method, '__func__'): | |
| checked_method = checked_method.__func__ | |
| simple_method = simple_method.__func__ | |
| if checked_method != simple_method: | |
| failed.append("%r: %-30s %s" % ( | |
| method, | |
| "checked -> %r" % (checked_method, ), | |
| "simple -> %r" % (simple_method, ), | |
| )) | |
| else: | |
| # if the method existed in only one of the enums, it will have been caught | |
| # in the first checks above | |
| pass | |
| if failed: | |
| raise TypeError('enum mismatch:\n %s' % '\n '.join(failed)) | |
| def _old_convert_(etype, name, module, filter, source=None, *, boundary=None): | |
| """ | |
| Create a new Enum subclass that replaces a collection of global constants | |
| """ | |
| # convert all constants from source (or module) that pass filter() to | |
| # a new Enum called name, and export the enum and its members back to | |
| # module; | |
| # also, replace the __reduce_ex__ method so unpickling works in | |
| # previous Python versions | |
| module_globals = sys.modules[module].__dict__ | |
| if source: | |
| source = source.__dict__ | |
| else: | |
| source = module_globals | |
| # _value2member_map_ is populated in the same order every time | |
| # for a consistent reverse mapping of number to name when there | |
| # are multiple names for the same number. | |
| members = [ | |
| (name, value) | |
| for name, value in source.items() | |
| if filter(name)] | |
| try: | |
| # sort by value | |
| members.sort(key=lambda t: (t[1], t[0])) | |
| except TypeError: | |
| # unless some values aren't comparable, in which case sort by name | |
| members.sort(key=lambda t: t[0]) | |
| cls = etype(name, members, module=module, boundary=boundary or KEEP) | |
| cls.__reduce_ex__ = _reduce_ex_by_global_name | |
| cls.__repr__ = global_enum_repr | |
| return cls |