Why Gemfury?
Push, build, and install
RubyGems
npm packages
Python packages
Maven artifacts
PHP packages
Go Modules
Debian packages
RPM packages
NuGet packages
duality-group / aenum python
Repository URL to install this package:
|
Version:
3.1.8 ▾
|
aenum
/
__init__.py
|
|---|
"""Python Advanced Enumerations & NameTuples"""
from __future__ import print_function
# imports
import sys as _sys
pyver = _sys.version_info[:2]
PY2 = pyver < (3, )
PY3 = pyver >= (3, )
PY2_6 = (2, 6)
PY3_3 = (3, 3)
PY3_4 = (3, 4)
PY3_5 = (3, 5)
PY3_6 = (3, 6)
PY3_11 = (3, 11)
import re
_bltin_property = property
_bltin_bin = bin
try:
from collections import OrderedDict
except ImportError:
OrderedDict = dict
from collections import defaultdict
try:
import sqlite3
except ImportError:
sqlite3 = None
from operator import or_ as _or_, and_ as _and_, xor as _xor_, inv as _inv_
from operator import abs as _abs_, add as _add_, floordiv as _floordiv_
from operator import lshift as _lshift_, rshift as _rshift_, mod as _mod_
from operator import mul as _mul_, neg as _neg_, pos as _pos_, pow as _pow_
from operator import truediv as _truediv_, sub as _sub_
if PY2:
from operator import div as _div_
if PY3:
from inspect import getfullargspec
def getargspec(method):
args, varargs, keywords, defaults, _, _, _ = getfullargspec(method)
return args, varargs, keywords, defaults
else:
from inspect import getargspec
obj_type = type
__all__ = [
'NamedConstant', 'constant', 'skip', 'nonmember', 'member', 'no_arg',
'Enum', 'IntEnum', 'AutoNumberEnum', 'OrderedEnum', 'UniqueEnum',
'StrEnum', 'UpperStrEnum', 'LowerStrEnum',
'Flag', 'IntFlag',
'AddValue', 'MagicValue', 'MultiValue', 'NoAlias', 'Unique',
'AddValueEnum', 'MultiValueEnum', 'NoAliasEnum',
'enum', 'extend_enum', 'unique', 'property',
'NamedTuple', 'SqliteEnum',
'FlagBoundary', 'STRICT', 'CONFORM', 'EJECT', 'KEEP',
]
if sqlite3 is None:
__all__.remove('SqliteEnum')
version = 3, 1, 8
# shims
try:
any
except NameError:
def any(iterable):
for element in iterable:
if element:
return True
return False
try:
unicode
unicode = unicode
except NameError:
# In Python 3 unicode no longer exists (it's just str)
unicode = str
try:
basestring
basestring = bytes, unicode
except NameError:
# In Python 2 basestring is the ancestor of both str and unicode
# in Python 3 it's just str, but was missing in 3.1
basestring = str,
try:
long
baseinteger = int, long
except NameError:
baseinteger = int,
long = int
# deprecated
baseint = baseinteger
try:
NoneType
except NameError:
NoneType = type(None)
try:
# derive from stdlib enum if possible
import enum
if hasattr(enum, 'version'):
raise ImportError('wrong version')
else:
from enum import EnumMeta as StdlibEnumMeta, Enum as StdlibEnum, IntEnum as StdlibIntEnum
StdlibFlag = StdlibIntFlag = StdlibStrEnum = None
except ImportError:
StdlibEnumMeta = StdlibEnum = StdlibIntEnum = StdlibIntFlag = StdlibFlag = StdlibStrEnum = None
if StdlibEnum:
try:
from enum import IntFlag as StdlibIntFlag, Flag as StdlibFlag
except ImportError:
pass
try:
from enum import StrEnum as StdlibStrEnum
except ImportError:
pass
# helpers
# will be exported later
MagicValue = AddValue = MultiValue = NoAlias = Unique = None
def _bit_count(num):
"""
return number of set bits
Counting bits set, Brian Kernighan's way*
unsigned int v; // count the number of bits set in v
unsigned int c; // c accumulates the total bits set in v
for (c = 0; v; c++)
{ v &= v - 1; } //clear the least significant bit set
This method goes through as many iterations as there are set bits. So if we
have a 32-bit word with only the high bit set, then it will only go once
through the loop.
* The C Programming Language 2nd Ed., Kernighan & Ritchie, 1988.
This works because each subtraction "borrows" from the lowest 1-bit. For
example:
loop pass 1 loop pass 2
----------- -----------
101000 100000
- 1 - 1
= 100111 = 011111
& 101000 & 100000
= 100000 = 0
It is an excellent technique for Python, since the size of the integer need
not be determined beforehand.
(from https://wiki.python.org/moin/BitManipulation)
"""
count = 0
while num:
num &= num - 1
count += 1
return count
def _is_single_bit(value):
"""
True if only one bit set in value (should be an int)
"""
if value == 0:
return False
value &= value - 1
return value == 0
def _iter_bits_lsb(value):
"""
Return each bit value one at a time.
>>> list(_iter_bits_lsb(6))
[2, 4]
"""
while value:
bit = value & (~value + 1)
yield bit
value ^= bit
def bin(value, 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 ** (value).bit_length()
if value >= 0:
s = _bltin_bin(value + ceiling).replace('1', '0', 1)
else:
s = _bltin_bin(~value ^ (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)
try:
from types import DynamicClassAttribute
base = DynamicClassAttribute
except ImportError:
base = object
DynamicClassAttribute = None
class property(base):
"""
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 look in the class' _member_map_.
"""
# inherit from DynamicClassAttribute if we can in order to get `inspect`
# support
def __init__(self, fget=None, fset=None, fdel=None, doc=None):
self.fget = fget
self.fset = fset
self.fdel = fdel
# next two lines make property act the same as _bltin_property
self.__doc__ = doc or fget.__doc__
self.overwrite_doc = doc is None
# support for abstract methods
self.__isabstractmethod__ = bool(getattr(fget, '__isabstractmethod__', False))
# names, if possible
def getter(self, fget):
fdoc = fget.__doc__ if self.overwrite_doc else None
result = type(self)(fget, self.fset, self.fdel, fdoc or self.__doc__)
result.overwrite_doc = self.__doc__ is None
return result
def setter(self, fset):
fdoc = fget.__doc__ if self.overwrite_doc else None
result = type(self)(self.fget, fset, self.fdel, self.__doc__)
result.overwrite_doc = self.__doc__ is None
return result
def deleter(self, fdel):
fdoc = fget.__doc__ if self.overwrite_doc else None
result = type(self)(self.fget, self.fset, fdel, self.__doc__)
result.overwrite_doc = self.__doc__ is None
return result
def __repr__(self):
member = self.ownerclass._member_map_.get(self.name)
func = self.fget or self.fset or self.fdel
strings = []
if member:
strings.append('%r' % member)
if func:
strings.append('function=%s' % func.__name__)
return 'property(%s)' % ', '.join(strings)
def __get__(self, instance, ownerclass=None):
if instance is None:
try:
return ownerclass._member_map_[self.name]
except KeyError:
raise AttributeError(
'%r has no attribute %r' % (ownerclass, self.name)
)
else:
if self.fget is not None:
return self.fget(instance)
else:
if self.fset is not None:
raise AttributeError(
'cannot read attribute %r on %r' % (self.name, ownerclass)
)
else:
try:
return instance.__dict__[self.name]
except KeyError:
raise AttributeError(
'%r member has no attribute %r' % (ownerclass, self.name)
)
def __set__(self, instance, value):
if self.fset is None:
if self.fget is not None:
raise AttributeError(
"cannot set attribute %r on <aenum %r>" % (self.name, self.clsname)
)
else:
instance.__dict__[self.name] = value
else:
return self.fset(instance, value)
def __delete__(self, instance):
if self.fdel is None:
if self.fget or self.fset:
raise AttributeError(
"cannot delete attribute %r on <aenum %r>" % (self.name, self.clsname)
)
elif self.name in instance.__dict__:
del instance.__dict__[self.name]
else:
raise AttributeError(
"no attribute %r on <aenum %r> member" % (self.name, self.clsname)
)
else:
return self.fdel(instance)
def __set_name__(self, ownerclass, name):
self.name = name
self.clsname = ownerclass.__name__
self.ownerclass = ownerclass
_RouteClassAttributeToGetattr = property
if DynamicClassAttribute is None:
DynamicClassAttribute = property
# deprecated
enum_property = property
class NonMember(object):
"""
Protects item from becaming an Enum member during class creation.
"""
def __init__(self, value):
self.value = value
def __get__(self, instance, ownerclass=None):
return self.value
skip = nonmember = NonMember
class Member(object):
"""
Forces item to became an Enum member during class creation.
"""
def __init__(self, value):
self.value = value
member = Member
class SentinelType(type):
def __repr__(cls):
return '<%s>' % cls.__name__
Sentinel = SentinelType('Sentinel', (object, ), {})
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] != '_' and
name[-2] != '_')
def _is_internal_class(cls_name, obj):
# only 3.3 and up, always return False in 3.2 and below
if pyver < PY3_3:
return False
else:
qualname = getattr(obj, '__qualname__', False)
return not _is_descriptor(obj) and qualname and re.search(r"\.?%s\.\w+$" % cls_name, qualname)
def _is_private_name(cls_name, name):
pattern = r'^_%s__\w+[^_]_?$' % (cls_name, )
return re.search(pattern, name)
def _power_of_two(value):
if value < 1:
return False
return value == 2 ** _high_bit(value)
def bits(num):
if num in (0, 1):
return str(num)
negative = False
if num < 0:
negative = True
num = ~num
result = bits(num>>1) + str(num&1)
if negative:
result = '1' + ''.join(['10'[d=='1'] for d in result])
return result
def bit_count(num):
"""
return number of set bits
Counting bits set, Brian Kernighan's way*
unsigned int v; // count the number of bits set in v
unsigned int c; // c accumulates the total bits set in v
for (c = 0; v; c++)
{ v &= v - 1; } //clear the least significant bit set
This method goes through as many iterations as there are set bits. So if we
have a 32-bit word with only the high bit set, then it will only go once
through the loop.
* The C Programming Language 2nd Ed., Kernighan & Ritchie, 1988.
This works because each subtraction "borrows" from the lowest 1-bit. For example:
loop pass 1 loop pass 2
----------- -----------
101000 100000
- 1 - 1
= 100111 = 011111
& 101000 & 100000
= 100000 = 0
It is an excellent technique for Python, since the size of the integer need not
be determined beforehand.
"""
count = 0
while(num):
num &= num - 1
count += 1
return(count)
def bit_len(num):
length = 0
while num:
length += 1
num >>= 1
return length
def is_single_bit(num):
"""
True if only one bit set in num (should be an int)
"""
num &= num - 1
return num == 0
def _make_class_unpicklable(obj):
"""
Make the given obj un-picklable.
obj should be either a dictionary, on 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 _check_auto_args(method):
"""check if new generate method supports *args and **kwds"""
if isinstance(method, staticmethod):
method = method.__get__(type)
method = getattr(method, 'im_func', method)
args, varargs, keywords, defaults = getargspec(method)
return varargs is not None and keywords is not None
def _get_attr_from_chain(cls, attr):
sentinel = object()
for basecls in cls.mro():
obj = basecls.__dict__.get(attr, sentinel)
if obj is not sentinel:
return obj
def _value(obj):
if isinstance(obj, (auto, constant)):
return obj.value
else:
return obj
def enumsort(things):
"""
sorts things by value if all same type; otherwise by name
"""
if not things:
return things
sort_type = type(things[0])
if not issubclass(sort_type, tuple):
# direct sort or type error
if not all((type(v) is sort_type) for v in things[1:]):
raise TypeError('cannot sort items of different types')
return sorted(things)
else:
# expecting list of (name, value) tuples
sort_type = type(things[0][1])
try:
if all((type(v[1]) is sort_type) for v in things[1:]):
return sorted(things, key=lambda i: i[1])
else:
raise TypeError('try name sort instead')
except TypeError:
return sorted(things, key=lambda i: i[0])
def export(collection, namespace=None):
"""
export([collection,] namespace) -> Export members to target namespace.
If collection is not given, act as a decorator.
"""
if namespace is None:
namespace = collection
def export_decorator(collection):
return export(collection, namespace)
return export_decorator
elif issubclass(collection, NamedConstant):
for n, c in collection.__dict__.items():
if isinstance(c, NamedConstant):
namespace[n] = c
elif issubclass(collection, Enum):
data = collection.__members__.items()
for n, m in data:
namespace[n] = m
else:
raise TypeError('%r is not a supported collection' % (collection,) )
return collection
class _Addendum(object):
def __init__(self, dict, doc, ns):
# dict is the dict to update with functions
# doc is the docstring to put in the dict
# ns is the namespace to remove the function names from
self.dict = dict
self.ns = ns
self.added = set()
def __call__(self, func):
if isinstance(func, (staticmethod, classmethod)):
name = func.__func__.__name__
elif isinstance(func, (property, _bltin_property)):
name = (func.fget or func.fset or func.fdel).__name__
else:
name = func.__name__
self.dict[name] = func
self.added.add(name)
def resolve(self):
ns = self.ns
for name in self.added:
del ns[name]
return self.dict
# Constant / NamedConstant
class constant(object):
'''
Simple constant descriptor for NamedConstant and Enum use.
'''
def __init__(self, value, doc=None):
self.value = value
self.__doc__ = doc
def __get__(self, *args):
return self.value
def __repr__(self):
return '%s(%r)' % (self.__class__.__name__, self.value)
def __and__(self, other):
return _and_(self.value, _value(other))
def __rand__(self, other):
return _and_(_value(other), self.value)
def __invert__(self):
return _inv_(self.value)
def __or__(self, other):
return _or_(self.value, _value(other))
def __ror__(self, other):
return _or_(_value(other), self.value)
def __xor__(self, other):
return _xor_(self.value, _value(other))
def __rxor__(self, other):
return _xor_(_value(other), self.value)
def __abs__(self):
return _abs_(self.value)
def __add__(self, other):
return _add_(self.value, _value(other))
def __radd__(self, other):
return _add_(_value(other), self.value)
def __neg__(self):
return _neg_(self.value)
def __pos__(self):
return _pos_(self.value)
if PY2:
def __div__(self, other):
return _div_(self.value, _value(other))
def __rdiv__(self, other):
return _div_(_value(other), (self.value))
def __floordiv__(self, other):
return _floordiv_(self.value, _value(other))
def __rfloordiv__(self, other):
return _floordiv_(_value(other), self.value)
def __truediv__(self, other):
return _truediv_(self.value, _value(other))
def __rtruediv__(self, other):
return _truediv_(_value(other), self.value)
def __lshift__(self, other):
return _lshift_(self.value, _value(other))
def __rlshift__(self, other):
return _lshift_(_value(other), self.value)
def __rshift__(self, other):
return _rshift_(self.value, _value(other))
def __rrshift__(self, other):
return _rshift_(_value(other), self.value)
def __mod__(self, other):
return _mod_(self.value, _value(other))
def __rmod__(self, other):
return _mod_(_value(other), self.value)
def __mul__(self, other):
return _mul_(self.value, _value(other))
def __rmul__(self, other):
return _mul_(_value(other), self.value)
def __pow__(self, other):
return _pow_(self.value, _value(other))
def __rpow__(self, other):
return _pow_(_value(other), self.value)
def __sub__(self, other):
return _sub_(self.value, _value(other))
def __rsub__(self, other):
return _sub_(_value(other), self.value)
def __set_name__(self, ownerclass, name):
self.name = name
self.clsname = ownerclass.__name__
NamedConstant = None
class _NamedConstantDict(dict):
"""Track constant order and ensure names are not reused.
NamedConstantMeta will use the names found in self._names as the
Constant names.
"""
def __init__(self):
super(_NamedConstantDict, self).__init__()
self._names = []
def __setitem__(self, key, value):
"""Changes anything not dundered or not a constant descriptor.
If an constant name is used twice, an error is raised; duplicate
values are not checked for.
Single underscore (sunder) names are reserved.
"""
if _is_sunder(key):
raise ValueError(
'_sunder_ names, such as %r, are reserved for future NamedConstant use'
% (key, )
)
elif _is_dunder(key):
pass
elif key in self._names:
# overwriting an existing constant?
raise TypeError('attempt to reuse name: %r' % (key, ))
elif isinstance(value, constant) or not _is_descriptor(value):
if key in self:
# overwriting a descriptor?
raise TypeError('%s already defined as: %r' % (key, self[key]))
self._names.append(key)
super(_NamedConstantDict, self).__setitem__(key, value)
class NamedConstantMeta(type):
"""
Block attempts to reassign NamedConstant attributes.
"""
@classmethod
def __prepare__(metacls, cls, bases, **kwds):
return _NamedConstantDict()
def __new__(metacls, cls, bases, clsdict):
if type(clsdict) is dict:
original_dict = clsdict
clsdict = _NamedConstantDict()
for k, v in original_dict.items():
clsdict[k] = v
newdict = {}
constants = {}
for name, obj in clsdict.items():
if name in clsdict._names:
constants[name] = obj
continue
elif isinstance(obj, nonmember):
obj = obj.value
newdict[name] = obj
newcls = super(NamedConstantMeta, metacls).__new__(metacls, cls, bases, newdict)
newcls._named_constant_cache_ = {}
newcls._members_ = {}
for name, obj in constants.items():
new_k = newcls.__new__(newcls, name, obj)
newcls._members_[name] = new_k
return newcls
def __bool__(cls):
return True
def __delattr__(cls, attr):
cur_obj = cls.__dict__.get(attr)
if NamedConstant is not None and isinstance(cur_obj, NamedConstant):
raise AttributeError('cannot delete constant <%s.%s>' % (cur_obj.__class__.__name__, cur_obj._name_))
super(NamedConstantMeta, cls).__delattr__(attr)
def __iter__(cls):
return (k for k in cls._members_.values())
def __reversed__(cls):
return (k for k in reversed(cls._members_.values()))
def __len__(cls):
return len(cls._members_)
__nonzero__ = __bool__
def __setattr__(cls, name, value):
"""Block attempts to reassign NamedConstants.
"""
cur_obj = cls.__dict__.get(name)
if NamedConstant is not None and isinstance(cur_obj, NamedConstant):
raise AttributeError('cannot rebind constant <%s.%s>' % (cur_obj.__class__.__name__, cur_obj._name_))
super(NamedConstantMeta, cls).__setattr__(name, value)
constant_dict = _Addendum(
dict=NamedConstantMeta.__prepare__('NamedConstant', (object, )),
doc="NamedConstants protection.\n\n Derive from this class to lock NamedConstants.\n\n",
ns=globals(),
)
@constant_dict
def __new__(cls, name, value=None, doc=None):
if value is None:
# lookup, name is value
value = name
for name, obj in cls.__dict__.items():
if isinstance(obj, cls) and obj._value_ == value:
return obj
else:
raise ValueError('%r does not exist in %r' % (value, cls.__name__))
cur_obj = cls.__dict__.get(name)
if isinstance(cur_obj, NamedConstant):
raise AttributeError('cannot rebind constant <%s.%s>' % (cur_obj.__class__.__name__, cur_obj._name_))
elif isinstance(value, constant):
doc = doc or value.__doc__
value = value.value
metacls = cls.__class__
if isinstance(value, NamedConstant):
# constants from other classes are reduced to their actual value
value = value._value_
actual_type = type(value)
value_type = cls._named_constant_cache_.get(actual_type)
if value_type is None:
value_type = type(cls.__name__, (cls, type(value)), {})
cls._named_constant_cache_[type(value)] = value_type
obj = actual_type.__new__(value_type, value)
obj._name_ = name
obj._value_ = value
obj.__doc__ = doc
cls._members_[name] = obj
metacls.__setattr__(cls, name, obj)
return obj
@constant_dict
def __repr__(self):
return "<%s.%s: %r>" % (
self.__class__.__name__, self._name_, self._value_)
@constant_dict
def __reduce_ex__(self, proto):
return getattr, (self.__class__, self._name_)
NamedConstant = NamedConstantMeta('NamedConstant', (object, ), constant_dict.resolve())
Constant = NamedConstant
del constant_dict
# NamedTuple
class _NamedTupleDict(OrderedDict):
"""Track field order and ensure field names are not reused.
NamedTupleMeta will use the names found in self._field_names to translate
to indices.
"""
def __init__(self, *args, **kwds):
self._field_names = []
super(_NamedTupleDict, self).__init__(*args, **kwds)
def __setitem__(self, key, value):
"""Records anything not dundered or not a descriptor.
If a field name is used twice, an error is raised.
Single underscore (sunder) names are reserved.
"""
if _is_sunder(key):
if key not in ('_size_', '_order_', '_fields_'):
raise ValueError(
'_sunder_ names, such as %r, are reserved for future NamedTuple use'
% (key, )
)
elif _is_dunder(key):
if key == '__order__':
key = '_order_'
elif key in self._field_names:
# overwriting a field?
raise TypeError('attempt to reuse field name: %r' % (key, ))
elif not _is_descriptor(value):
if key in self:
# field overwriting a descriptor?
raise TypeError('%s already defined as: %r' % (key, self[key]))
self._field_names.append(key)
super(_NamedTupleDict, self).__setitem__(key, value)
class _TupleAttributeAtIndex(object):
def __init__(self, name, index, doc, default):
self.name = name
self.index = index
if doc is undefined:
doc = None
self.__doc__ = doc
self.default = default
def __get__(self, instance, owner):
if instance is None:
return self
if len(instance) <= self.index:
raise AttributeError('%s instance has no value for %s' % (instance.__class__.__name__, self.name))
return instance[self.index]
def __repr__(self):
return '%s(%d)' % (self.__class__.__name__, self.index)
class undefined(object):
def __repr__(self):
return 'undefined'
def __bool__(self):
return False
__nonzero__ = __bool__
undefined = undefined()
class TupleSize(NamedConstant):
fixed = constant('fixed', 'tuple length is static')
minimum = constant('minimum', 'tuple must be at least x long (x is calculated during creation')
variable = constant('variable', 'tuple length can be anything')
class NamedTupleMeta(type):
"""Metaclass for NamedTuple"""
@classmethod
def __prepare__(metacls, cls, bases, size=undefined, **kwds):
return _NamedTupleDict()
def __init__(cls, *args , **kwds):
super(NamedTupleMeta, cls).__init__(*args)
def __new__(metacls, cls, bases, clsdict, size=undefined, **kwds):
if bases == (object, ):
bases = (tuple, object)
elif tuple not in bases:
if object in bases:
index = bases.index(object)
bases = bases[:index] + (tuple, ) + bases[index:]
else:
bases = bases + (tuple, )
# include any fields from base classes
base_dict = _NamedTupleDict()
namedtuple_bases = []
for base in bases:
if isinstance(base, NamedTupleMeta):
namedtuple_bases.append(base)
i = 0
if namedtuple_bases:
for name, index, doc, default in metacls._convert_fields(*namedtuple_bases):
base_dict[name] = index, doc, default
i = max(i, index)
# construct properly ordered dict with normalized indexes
for k, v in clsdict.items():
base_dict[k] = v
original_dict = base_dict
if size is not undefined and '_size_' in original_dict:
raise TypeError('_size_ cannot be set if "size" is passed in header')
add_order = isinstance(clsdict, _NamedTupleDict)
clsdict = _NamedTupleDict()
clsdict.setdefault('_size_', size or TupleSize.fixed)
unnumbered = OrderedDict()
numbered = OrderedDict()
_order_ = original_dict.pop('_order_', [])
if _order_ :
_order_ = _order_.replace(',',' ').split()
add_order = False
# and process this class
for k, v in original_dict.items():
if k not in original_dict._field_names:
clsdict[k] = v
else:
# TODO:normalize v here
if isinstance(v, baseinteger):
# assume an offset
v = v, undefined, undefined
i = v[0] + 1
target = numbered
elif isinstance(v, basestring):
# assume a docstring
if add_order:
v = i, v, undefined
i += 1
target = numbered
else:
v = undefined, v, undefined
target = unnumbered
elif isinstance(v, tuple) and len(v) in (2, 3) and isinstance(v[0], baseinteger) and isinstance(v[1], (basestring, NoneType)):
# assume an offset, a docstring, and (maybe) a default
if len(v) == 2:
v = v + (undefined, )
v = v
i = v[0] + 1
target = numbered
elif isinstance(v, tuple) and len(v) in (1, 2) and isinstance(v[0], (basestring, NoneType)):
# assume a docstring, and (maybe) a default
if len(v) == 1:
v = v + (undefined, )
if add_order:
v = (i, ) + v
i += 1
target = numbered
else:
v = (undefined, ) + v
target = unnumbered
else:
# refuse to guess further
raise ValueError('not sure what to do with %s=%r (should be OFFSET [, DOC [, DEFAULT]])' % (k, v))
target[k] = v
# all index values have been normalized
# deal with _order_ (or lack thereof)
fields = []
aliases = []
seen = set()
max_len = 0
if not _order_:
if unnumbered:
raise ValueError("_order_ not specified and OFFSETs not declared for %r" % (unnumbered.keys(), ))
for name, (index, doc, default) in sorted(numbered.items(), key=lambda nv: (nv[1][0], nv[0])):
if index in seen:
aliases.append(name)
else:
fields.append(name)
seen.add(index)
max_len = max(max_len, index + 1)
offsets = numbered
else:
# check if any unnumbered not in _order_
missing = set(unnumbered) - set(_order_)
if missing:
raise ValueError("unable to order fields: %s (use _order_ or specify OFFSET" % missing)
offsets = OrderedDict()
# if any unnumbered, number them from their position in _order_
i = 0
for k in _order_:
try:
index, doc, default = unnumbered.pop(k, None) or numbered.pop(k)
except IndexError:
raise ValueError('%s (from _order_) not found in %s' % (k, cls))
if index is not undefined:
i = index
if i in seen:
aliases.append(k)
else:
fields.append(k)
seen.add(i)
offsets[k] = i, doc, default
i += 1
max_len = max(max_len, i)
# now handle anything in numbered
for k, (index, doc, default) in sorted(numbered.items(), key=lambda nv: (nv[1][0], nv[0])):
if index in seen:
aliases.append(k)
else:
fields.append(k)
seen.add(index)
offsets[k] = index, doc, default
max_len = max(max_len, index+1)
# at this point fields and aliases should be ordered lists, offsets should be an
# OrdededDict with each value an int, str or None or undefined, default or None or undefined
assert len(fields) + len(aliases) == len(offsets), "number of fields + aliases != number of offsets"
assert set(fields) & set(offsets) == set(fields), "some fields are not in offsets: %s" % set(fields) & set(offsets)
assert set(aliases) & set(offsets) == set(aliases), "some aliases are not in offsets: %s" % set(aliases) & set(offsets)
for name, (index, doc, default) in offsets.items():
assert isinstance(index, baseinteger), "index for %s is not an int (%s:%r)" % (name, type(index), index)
assert isinstance(doc, (basestring, NoneType)) or doc is undefined, "doc is not a str, None, nor undefined (%s:%r)" % (name, type(doc), doc)
# create descriptors for fields
for name, (index, doc, default) in offsets.items():
clsdict[name] = _TupleAttributeAtIndex(name, index, doc, default)
clsdict['__slots__'] = ()
# create our new NamedTuple type
namedtuple_class = super(NamedTupleMeta, metacls).__new__(metacls, cls, bases, clsdict)
namedtuple_class._fields_ = fields
namedtuple_class._aliases_ = aliases
namedtuple_class._defined_len_ = max_len
return namedtuple_class
@staticmethod
def _convert_fields(*namedtuples):
"create list of index, doc, default triplets for cls in namedtuples"
all_fields = []
for cls in namedtuples:
base = len(all_fields)
for field in cls._fields_:
desc = getattr(cls, field)
all_fields.append((field, base+desc.index, desc.__doc__, desc.default))
return all_fields
def __add__(cls, other):
"A new NamedTuple is created by concatenating the _fields_ and adjusting the descriptors"
if not isinstance(other, NamedTupleMeta):
return NotImplemented
return NamedTupleMeta('%s%s' % (cls.__name__, other.__name__), (cls, other), {})
def __call__(cls, *args, **kwds):
"""Creates a new NamedTuple class or an instance of a NamedTuple subclass.
NamedTuple should have args of (class_name, names, module)
`names` can be:
* A string containing member names, separated either with spaces or
commas. Values are auto-numbered from 1.
* An iterable of member names. Values are auto-numbered from 1.
* An iterable of (member name, value) pairs.
* A mapping of member name -> value.
`module`, if set, will be stored in the new class' __module__ attribute;
Note: if `module` is not set this routine will attempt to discover the
calling module by walking the frame stack; if this is unsuccessful
the resulting class will not be pickleable.
subclass should have whatever arguments and/or keywords will be used to create an
instance of the subclass
"""
if cls is NamedTuple:
original_args = args
original_kwds = kwds.copy()
# create a new subclass
try:
if 'class_name' in kwds:
class_name = kwds.pop('class_name')
else:
class_name, args = args[0], args[1:]
if 'names' in kwds:
names = kwds.pop('names')
else:
names, args = args[0], args[1:]
if 'module' in kwds:
module = kwds.pop('module')
elif args:
module, args = args[0], args[1:]
else:
module = None
if 'type' in kwds:
type = kwds.pop('type')
elif args:
type, args = args[0], args[1:]
else:
type = None
except IndexError:
raise TypeError('too few arguments to NamedTuple: %s, %s' % (original_args, original_kwds))
if args or kwds:
raise TypeError('too many arguments to NamedTuple: %s, %s' % (original_args, original_kwds))
if PY2:
# if class_name is unicode, attempt a conversion to ASCII
if isinstance(class_name, unicode):
try:
class_name = class_name.encode('ascii')
except UnicodeEncodeError:
raise TypeError('%r is not representable in ASCII' % (class_name, ))
# quick exit if names is a NamedTuple
if isinstance(names, NamedTupleMeta):
names.__name__ = class_name
if type is not None and type not in names.__bases__:
names.__bases__ = (type, ) + names.__bases__
return names
metacls = cls.__class__
bases = (cls, )
clsdict = metacls.__prepare__(class_name, bases)
# special processing needed for names?
if isinstance(names, basestring):
names = names.replace(',', ' ').split()
if isinstance(names, (tuple, list)) and isinstance(names[0], basestring):
names = [(e, i) for (i, e) in enumerate(names)]
# Here, names is either an iterable of (name, index) or (name, index, doc, default) or a mapping.
item = None # in case names is empty
for item in names:
if isinstance(item, basestring):
# mapping
field_name, field_index = item, names[item]
else:
# non-mapping
if len(item) == 2:
field_name, field_index = item
else:
field_name, field_index = item[0], item[1:]
clsdict[field_name] = field_index
if type is not None:
if not isinstance(type, tuple):
type = (type, )
bases = type + bases
namedtuple_class = metacls.__new__(metacls, class_name, bases, clsdict)
# 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(1).f_globals['__name__']
except (AttributeError, ValueError, KeyError):
pass
if module is None:
_make_class_unpicklable(namedtuple_class)
else:
namedtuple_class.__module__ = module
return namedtuple_class
else:
# instantiate a subclass
namedtuple_instance = cls.__new__(cls, *args, **kwds)
if isinstance(namedtuple_instance, cls):
namedtuple_instance.__init__(*args, **kwds)
return namedtuple_instance
@_bltin_property
def __fields__(cls):
return list(cls._fields_)
# collections.namedtuple compatibility
_fields = __fields__
@_bltin_property
def __aliases__(cls):
return list(cls._aliases_)
def __repr__(cls):
return "<NamedTuple %r>" % (cls.__name__, )
namedtuple_dict = _Addendum(
dict=NamedTupleMeta.__prepare__('NamedTuple', (object, )),
doc="NamedTuple base class.\n\n Derive from this class to define new NamedTuples.\n\n",
ns=globals(),
)
@namedtuple_dict
def __new__(cls, *args, **kwds):
if cls._size_ is TupleSize.fixed and len(args) > cls._defined_len_:
raise TypeError('%d fields expected, %d received' % (cls._defined_len_, len(args)))
unknown = set(kwds) - set(cls._fields_) - set(cls._aliases_)
if unknown:
raise TypeError('unknown fields: %r' % (unknown, ))
final_args = list(args) + [undefined] * (len(cls.__fields__) - len(args))
for field, value in kwds.items():
index = getattr(cls, field).index
if final_args[index] != undefined:
raise TypeError('field %s specified more than once' % field)
final_args[index] = value
missing = []
for index, value in enumerate(final_args):
if value is undefined:
# look for default values
name = cls.__fields__[index]
default = getattr(cls, name).default
if default is undefined:
missing.append(name)
else:
final_args[index] = default
if missing:
if cls._size_ in (TupleSize.fixed, TupleSize.minimum):
raise TypeError('values not provided for field(s): %s' % ', '.join(missing))
while final_args and final_args[-1] is undefined:
final_args.pop()
missing.pop()
if cls._size_ is not TupleSize.variable or undefined in final_args:
raise TypeError('values not provided for field(s): %s' % ', '.join(missing))
return tuple.__new__(cls, tuple(final_args))
@namedtuple_dict
def __reduce_ex__(self, proto):
return self.__class__, tuple(getattr(self, f) for f in self._fields_)
@namedtuple_dict
def __repr__(self):
if len(self) == len(self._fields_):
return "%s(%s)" % (
self.__class__.__name__, ', '.join(['%s=%r' % (f, o) for f, o in zip(self._fields_, self)])
)
else:
return '%s(%s)' % (self.__class__.__name__, ', '.join([repr(o) for o in self]))
@namedtuple_dict
def __str__(self):
return "%s(%s)" % (
self.__class__.__name__, ', '.join(['%r' % (getattr(self, f), ) for f in self._fields_])
)
@namedtuple_dict
@_bltin_property
def _fields_(self):
return list(self.__class__._fields_)
# compatibility methods with stdlib namedtuple
@namedtuple_dict
@_bltin_property
def __aliases__(self):
return list(self.__class__._aliases_)
@namedtuple_dict
@_bltin_property
def _fields(self):
return list(self.__class__._fields_)
@namedtuple_dict
@classmethod
def _make(cls, iterable, new=None, len=None):
return cls.__new__(cls, *iterable)
@namedtuple_dict
def _asdict(self):
return OrderedDict(zip(self._fields_, self))
@namedtuple_dict
def _replace(self, **kwds):
current = self._asdict()
current.update(kwds)
return self.__class__(**current)
NamedTuple = NamedTupleMeta('NamedTuple', (object, ), namedtuple_dict.resolve())
del namedtuple_dict
# Enum
# _init_ and value and AddValue
# -----------------------------
# by default, when defining a member everything after the = is "the value", everything is
# passed to __new__, everything is passed to __init__
#
# if _init_ is present then
# if `value` is not in _init_, everything is "the value", defaults apply
# if `value` is in _init_, only the first thing after the = is the value, and the rest will
# be passed to __init__
# if fewer values are present for member assignment than _init_ calls for, _generate_next_value_
# will be called in an attempt to generate them
#
# if AddValue is present then
# _generate_next_value_ is always called, and any generated values are prepended to provided
# values (custom _gnv_s can change that)
# default _init_ rules apply
# Constants used in Enum
@export(globals())
class EnumConstants(NamedConstant):
AddValue = constant('addvalue', 'prepends value(s) from _generate_next_value_ to each member')
MagicValue = constant('magicvalue', 'calls _generate_next_value_ when no arguments are given')
MultiValue = constant('multivalue', 'each member can have several values')
NoAlias = constant('noalias', 'duplicate valued members are distinct, not aliased')
Unique = constant('unique', 'duplicate valued members are not allowed')
def __repr__(self):
return self._name_
# Dummy value for Enum as EnumType explicity checks for it, but of course until
# EnumType finishes running the first time the Enum class doesn't exist. This
# is also why there are checks in EnumType like `if Enum is not None`.
#
# Ditto for Flag.
Enum = ReprEnum = Flag = EJECT = KEEP = None
class enum(object):
"""
Helper class to track args, kwds.
"""
def __init__(self, *args, **kwds):
self._args = args
self._kwds = dict(kwds.items())
self._hash = hash(args)
self.name = None
@_bltin_property
def args(self):
return self._args
@_bltin_property
def kwds(self):
return self._kwds.copy()
def __hash__(self):
return self._hash
def __eq__(self, other):
if not isinstance(other, self.__class__):
return NotImplemented
return self.args == other.args and self.kwds == other.kwds
def __ne__(self, other):
if not isinstance(other, self.__class__):
return NotImplemented
return self.args != other.args or self.kwds != other.kwds
def __repr__(self):
final = []
args = ', '.join(['%r' % (a, ) for a in self.args])
if args:
final.append(args)
kwds = ', '.join([('%s=%r') % (k, v) for k, v in enumsort(list(self.kwds.items()))])
if kwds:
final.append(kwds)
return '%s(%s)' % (self.__class__.__name__, ', '.join(final))
_auto_null = SentinelType('no_value', (object, ), {})
class auto(enum):
"""
Instances are replaced with an appropriate value in Enum class suites.
"""
enum_member = _auto_null
_value = _auto_null
_operations = []
def __and__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_and_, (self, other)))
return new_auto
def __rand__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_and_, (other, self)))
return new_auto
def __invert__(self):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_inv_, (self,)))
return new_auto
def __or__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_or_, (self, other)))
return new_auto
def __ror__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_or_, (other, self)))
return new_auto
def __xor__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_xor_, (self, other)))
return new_auto
def __rxor__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_xor_, (other, self)))
return new_auto
def __abs__(self):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_abs_, (self, )))
return new_auto
def __add__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_add_, (self, other)))
return new_auto
def __radd__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_add_, (other, self)))
return new_auto
def __neg__(self):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_neg_, (self, )))
return new_auto
def __pos__(self):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_pos_, (self, )))
return new_auto
if PY2:
def __div__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_div_, (self, other)))
return new_auto
def __rdiv__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_div_, (other, self)))
return new_auto
def __floordiv__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_floordiv_, (self, other)))
return new_auto
def __rfloordiv__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_floordiv_, (other, self)))
return new_auto
def __truediv__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_truediv_, (self, other)))
return new_auto
def __rtruediv__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_truediv_, (other, self)))
return new_auto
def __lshift__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_lshift_, (self, other)))
return new_auto
def __rlshift__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_lshift_, (other, self)))
return new_auto
def __rshift__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_rshift_, (self, other)))
return new_auto
def __rrshift__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_rshift_, (other, self)))
return new_auto
def __mod__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_mod_, (self, other)))
return new_auto
def __rmod__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_mod_, (other, self)))
return new_auto
def __mul__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_mul_, (self, other)))
return new_auto
def __rmul__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_mul_, (other, self)))
return new_auto
def __pow__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_pow_, (self, other)))
return new_auto
def __rpow__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_pow_, (other, self)))
return new_auto
def __sub__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_sub_, (self, other)))
return new_auto
def __rsub__(self, other):
new_auto = self.__class__()
new_auto._operations = self._operations[:]
new_auto._operations.append((_sub_, (other, self)))
return new_auto
def __repr__(self):
if self._operations:
return 'auto(...)'
else:
return 'auto(%r, *%r, **%r)' % (self._value, self._args, self._kwds)
@_bltin_property
def value(self):
if self._value is not _auto_null and self._operations:
raise TypeError('auto() object out of sync')
elif self._value is _auto_null and not self._operations:
return self._value
elif self._value is not _auto_null:
return self._value
else:
return self._resolve()
@value.setter
def value(self, value):
if self._operations:
value = self._resolve(value)
self._value = value
def _resolve(self, base_value=None):
cls = self.__class__
for op, params in self._operations:
values = []
for param in params:
if isinstance(param, cls):
if param.value is _auto_null:
if base_value is None:
return _auto_null
else:
values.append(base_value)
else:
values.append(param.value)
else:
values.append(param)
value = op(*values)
self._operations[:] = []
self._value = value
return value
class _EnumArgSpec(NamedTuple):
args = 0, 'all args except *args and **kwds'
varargs = 1, 'the name of the *args variable'
keywords = 2, 'the name of the **kwds variable'
defaults = 3, 'any default values'
required = 4, 'number of required values (no default available)'
def __new__(cls, _new_func):
argspec = getargspec(_new_func)
args, varargs, keywords, defaults = argspec
if defaults:
reqs = args[1:-len(defaults)]
else:
reqs = args[1:]
return tuple.__new__(_EnumArgSpec, (args, varargs, keywords, defaults, reqs))
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
kwds = {}
args = ()
init_args = ()
extra_mv_args = ()
multivalue = None
if isinstance(value, tuple) and value and isinstance(value[0], auto):
multivalue = value
value = value[0]
if isinstance(value, auto) and value.value is _auto_null:
args = value.args
kwds = value.kwds
elif isinstance(value, auto):
kwds = value.kwds
args = (value.value, ) + value.args
value = value.value
elif isinstance(value, enum):
args = value.args
kwds = value.kwds
elif isinstance(value, Member):
value = value.value
args = (value, )
elif not isinstance(value, tuple):
args = (value, )
else:
args = value
if multivalue is not None:
value = (value, ) + multivalue[1:]
kwds = {}
args = value
del multivalue
# possibilities
#
# - no init, multivalue -> __new__[0], __init__(*[:]), extra=[1:]
# - init w/o value, multivalue -> __new__[0], __init__(*[:]), extra=[1:]
#
# - init w/value, multivalue -> __new__[0], __init__(*[1:]), extra=[1:]
#
# - init w/value, no multivalue -> __new__[0], __init__(*[1:]), extra=[]
#
# - init w/o value, no multivalue -> __new__[:], __init__(*[:]), extra=[]
# - no init, no multivalue -> __new__[:], __init__(*[:]), extra=[]
if enum_class._multivalue_ or 'value' in enum_class._creating_init_:
if enum_class._multivalue_:
# when multivalue is True, creating_init can be anything
mv_arg = args[0]
extra_mv_args = args[1:]
if 'value' in enum_class._creating_init_:
init_args = args[1:]
else:
init_args = args
args = args[0:1]
value = args[0]
else:
# 'value' is definitely in creating_init
if enum_class._auto_init_ and enum_class._new_args_:
# we have a custom __new__ and an auto __init__
# divvy up according to number of params in each
init_args = args[-len(enum_class._creating_init_)+1:]
if not enum_class._auto_args_:
args = args[:len(enum_class._new_args_.args)]
value = args[0]
elif enum_class._auto_init_:
# don't pass in value
init_args = args[1:]
args = args[0:1]
value = args[0]
elif enum_class._new_args_:
# do not modify args
value = args[0]
else:
# keep all args for user-defined __init__
# keep value as-is
init_args = args
else:
# either no creating_init, or it doesn't have 'value'
init_args = args
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, **kwds)
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, **kwds)
except Exception:
te = TypeError('_value_ not set in __new__, unable to create it')
te.__cause__ = None
raise te
value = enum_member._value_
enum_member._name_ = member_name
enum_member.__objclass__ = enum_class
enum_member.__init__(*init_args, **kwds)
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.
if enum_class._noalias_:
# unless NoAlias was specified
enum_class._member_names_.append(member_name)
else:
nonunique = defaultdict(list)
try:
try:
# try to do a fast lookup to avoid the quadratic loop
enum_member = enum_class._value2member_map_[value]
if enum_class._unique_:
nonunique[enum_member.name].append(member_name)
except TypeError:
# unhashable members are stored elsewhere
for unhashable_value, canonical_member in enum_class._value2member_seq_:
name = canonical_member.name
if unhashable_value == enum_member._value_:
if enum_class._unique_:
nonunique[name].append(member_name)
enum_member = canonical_member
break
else:
raise KeyError
except KeyError:
# 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)
if nonunique:
# duplicates not allowed if Unique specified
message = []
for name, aliases in nonunique.items():
bad_aliases = ','.join(aliases)
message.append('%s --> %s [%r]' % (name, bad_aliases, enum_class[name].value))
raise ValueError(
'%s: duplicate names found: %s' %
(enum_class.__name__, '; '.join(message))
)
# if self.value is an `auto()`, replace the value attribute with the new enum member
if isinstance(self.value, auto):
self.value.enum_member = enum_member
# get redirect in place before adding to _member_map_
# but check for other instances in parent classes first
need_override = False
descriptor = None
descriptor_property = 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
if isinstance(descriptor, _bltin_property) and descriptor_property is None:
descriptor_property = descriptor
# keep looking for an enum.property
descriptor = descriptor or descriptor_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
#
# process (possible) MultiValues
values = (value, ) + extra_mv_args
if enum_class._multivalue_ and mv_arg not in values:
values += (mv_arg, )
enum_member._values_ = values
for value in values:
# first check if value has already been used
if enum_class._multivalue_ and (
value in enum_class._value2member_map_
or any(v == value for (v, m) in enum_class._value2member_seq_)
):
raise ValueError('%r has already been used' % (value, ))
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.
if enum_class._noalias_:
raise TypeError('cannot use dict to store value')
enum_class._value2member_map_[value] = enum_member
except TypeError:
enum_class._value2member_seq_ += ((value, enum_member), )
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, cls_name, settings, start, constructor_init, constructor_start, constructor_boundary):
super(_EnumDict, self).__init__()
self._cls_name = cls_name
self._constructor_init = constructor_init
self._constructor_start = constructor_start
self._constructor_boundary = constructor_boundary
self._generate_next_value = None
self._member_names = []
self._member_names_set = set()
self._settings = settings
self._addvalue = addvalue = AddValue in settings
self._magicvalue = MagicValue in settings
self._multivalue = MultiValue in settings
if self._addvalue and self._magicvalue:
raise TypeError('%r: AddValue and MagicValue are mutually exclusive' % cls_name)
if self._multivalue and self._magicvalue:
raise TypeError('%r: MultiValue and MagicValue are mutually exclusive' % cls_name)
self._start = start
self._addvalue_value = start
self._new_args = ()
self._auto_args = False
# when the magic turns off
self._locked = MagicValue not in settings
# if init fields are specified
self._init = []
# list of temporary names
self._ignore = []
if self._magicvalue:
self._ignore = ['property', 'staticmethod', 'classmethod']
self._ignore_init_done = False
# if _sunder_ values can be changed via the class body
self._allow_init = True
self._last_values = []
def __getitem__(self, key):
if key == self._cls_name and self._cls_name not in self:
return enum
elif (
self._locked
or key in self
or key in self._ignore
or _is_sunder(key)
or _is_dunder(key)
):
return super(_EnumDict, self).__getitem__(key)
elif self._magicvalue:
value = self._generate_next_value(key, self._start, len(self._member_names), self._last_values[:])
self.__setitem__(key, value)
return value
else:
raise Exception('Magic is not set -- why am I here?')
def __setitem__(self, key, value):
"""Changes anything not sundured, dundered, nor 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.
"""
# Flag classes that have MagicValue and __new__ will get a generated _gnv_
if _is_internal_class(self._cls_name, value):
pass
elif _is_private_name(self._cls_name, key):
pass
elif _is_sunder(key):
if key not in (
'_init_', '_settings_', '_order_', '_ignore_', '_start_',
'_create_pseudo_member_', '_create_pseudo_member_values_',
'_generate_next_value_', '_boundary_', '_numeric_repr_',
'_missing_', '_missing_value_', '_missing_name_',
'_iter_member_', '_iter_member_by_value_', '_iter_member_by_def_',
):
raise ValueError('%r: _sunder_ names, such as %r, are reserved for future Enum use'
% (self._cls_name, key)
)
elif not self._allow_init and key not in (
'create_pseudo_member_', '_missing_', '_missing_value_', '_missing_name_',
):
# sunder is used during creation, must be specified first
raise ValueError('%r: cannot set %r after init phase' % (self._cls_name, key))
elif key == '_ignore_':
if self._ignore_init_done:
raise TypeError('%r: ignore can only be specified once' % self._cls_name)
if isinstance(value, basestring):
value = value.split()
else:
value = list(value)
self._ignore = value
already = set(value) & self._member_names_set
if already:
raise ValueError('%r: _ignore_ cannot specify already set names %s' % (
self._cls_name,
', '.join(repr(a) for a in already)
))
self._ignore_init_done = True
elif key == '_boundary_':
if self._constructor_boundary:
raise TypeError('%r: boundary specified in constructor and class body' % self._cls_name)
elif key == '_start_':
if self._constructor_start:
raise TypeError('%r: start specified in constructor and class body' % self._cls_name)
self._start = value
elif key == '_settings_':
if not isinstance(value, (set, tuple)):
value = (value, )
if not isinstance(value, set):
value = set(value)
self._settings |= value
if NoAlias in value and Unique in value:
raise TypeError('%r: NoAlias and Unique are mutually exclusive' % self._cls_name)
elif MultiValue in value and NoAlias in value:
raise TypeError('cannot specify both MultiValue and NoAlias' % self._cls_name)
allowed_settings = dict.fromkeys(['addvalue', 'magicvalue', 'noalias', 'unique', 'multivalue'])
for arg in self._settings:
if arg not in allowed_settings:
raise TypeError('%r: unknown qualifier %r (from %r)' % (self._cls_name, arg, value))
allowed_settings[arg] = True
self._multivalue = allowed_settings['multivalue']
self._addvalue = allowed_settings['addvalue']
self._magicvalue = allowed_settings['magicvalue']
self._locked = not self._magicvalue
if self._magicvalue and not self._ignore_init_done:
self._ignore = ['property', 'classmethod', 'staticmethod']
if self._addvalue and self._init and 'value' not in self._init:
self._init.insert(0, 'value')
value = tuple(self._settings)
elif key == '_init_':
if self._constructor_init:
raise TypeError('%r: init specified in constructor and in class body' % self._cls_name)
_init_ = value
if isinstance(_init_, basestring):
_init_ = _init_.replace(',',' ').split()
if self._addvalue and 'value' not in self._init:
self._init.insert(0, 'value')
if self._magicvalue:
raise TypeError("%r: _init_ and MagicValue are mutually exclusive" % self._cls_name)
self._init = _init_
value = _init_
elif key == '_generate_next_value_':
gnv = value
if value is not None:
if isinstance(value, staticmethod):
gnv = value.__func__
elif isinstance(value, classmethod):
raise TypeError('%r: _generate_next_value must be a staticmethod, not a classmethod' % self._cls_name)
else:
gnv = value
value = staticmethod(value)
self._auto_args = _check_auto_args(value)
setattr(self, '_generate_next_value', gnv)
elif _is_dunder(key):
if key == '__order__':
key = '_order_'
if not self._allow_init:
# _order_ is used during creation, must be specified first
raise ValueError('%r: cannot set %r after init phase' % (self._cls_name, key))
elif key == '__new__': # and self._new_to_init:
if isinstance(value, staticmethod):
value = value.__func__
self._new_args = _EnumArgSpec(value)
elif key == '__init_subclass__':
if not isinstance(value, classmethod):
value = classmethod(value)
if _is_descriptor(value):
self._locked = True
elif key in self._member_names_set:
# descriptor overwriting an enum?
raise TypeError('%r: attempt to reuse name: %r' % (self._cls_name, key))
elif key in self._ignore:
pass
elif not _is_descriptor(value):
self._allow_init = False
if key in self:
# enum overwriting a descriptor?
raise TypeError('%r: %s already defined as %r' % (self._cls_name, key, self[key]))
if type(value) is enum:
value.name = key
if self._addvalue:
raise TypeError('%r: enum() and AddValue are incompatible' % self._cls_name)
elif self._addvalue and not self._multivalue:
# generate a value
value = self._gnv(key, value)
elif self._multivalue:
# make sure it's a tuple
if not isinstance(value, tuple):
value = (value, )
if isinstance(value[0], auto):
value = (self._convert_auto(key, value[0]), ) + value[1:]
if self._addvalue:
value = self._gnv(key, value)
elif isinstance(value, auto):
value = self._convert_auto(key, value)
elif isinstance(value, tuple) and value and isinstance(value[0], auto):
value = (self._convert_auto(key, value[0]), ) + value[1:]
elif not isinstance(value, auto):
# call generate maybe if
# - init is specified; or
# - __new__ is specified;
# and either of them call for more values than are present
new_args = () or self._new_args and self._new_args.required
target_len = len(self._init or new_args)
if isinstance(value, tuple):
source_len = len(value)
else:
source_len = 1
multi_args = len(self._init) > 1 or new_args
if source_len < target_len :
value = self._gnv(key, value)
else:
pass
if self._init:
if isinstance(value, auto):
test_value = value.args
elif not isinstance(value, tuple):
test_value = (value, )
else:
test_value = value
if len(self._init) != len(test_value):
raise TypeError(
'%s.%s: number of fields provided do not match init [%r != %r]'
% (self._cls_name, key, self._init, test_value)
)
self._member_names.append(key)
self._member_names_set.add(key)
else:
# not a new member, turn off the autoassign magic
self._locked = True
self._allow_init = False
if not (_is_sunder(key) or _is_dunder(key) or _is_private_name(self._cls_name, key) or _is_descriptor(value)):
if isinstance(value, auto):
self._last_values.append(value.value)
elif isinstance(value, tuple) and value and isinstance(value[0], auto):
self._last_values.append(value[0].value)
elif isinstance(value, tuple):
if value:
self._last_values.append(value[0])
else:
self._last_values.append(value)
super(_EnumDict, self).__setitem__(key, value)
def _convert_auto(self, key, value):
# if auto.args or auto.kwds, compare to _init_ and __new__ -- if lacking, call gnv
# if not auto.args|kwds but auto.value is _auto_null -- call gnv
if value.args or value.kwds or value.value is _auto_null:
if value.args or value.kwds:
values = value.args
else:
values = ()
new_args = () or self._new_args and self._new_args.required
target_len = len(self._init or new_args) or 1
if isinstance(values, tuple):
source_len = len(values)
else:
source_len = 1
multi_args = len(self._init) > 1 or new_args
if source_len < target_len :
values = self._gnv(key, values)
if value.args:
value._args = values
else:
value.value = values
return value
def _gnv(self, key, value):
# generate a value
if self._auto_args:
if not isinstance(value, tuple):
value = (value, )
value = self._generate_next_value(key, self._start, len(self._member_names), self._last_values[:], *value)
else:
value = self._generate_next_value(key, self._start, len(self._member_names), self._last_values[:])
if isinstance(value, tuple) and len(value) == 1:
value = value[0]
return value
no_arg = SentinelType('no_arg', (object, ), {})
class EnumType(StdlibEnumMeta or type):
"""Metaclass for Enum"""
@classmethod
def __prepare__(metacls, cls, bases, init=None, start=None, settings=(), boundary=None, **kwds):
metacls._check_for_existing_members_(cls, bases)
if Flag is None and cls == 'Flag':
initial_flag = True
else:
initial_flag = False
# settings are a combination of current and all past settings
constructor_init = init is not None
constructor_start = start is not None
constructor_boundary = boundary is not None
if not isinstance(settings, tuple):
settings = settings,
settings = set(settings)
generate = None
order = None
# inherit previous flags
member_type, first_enum = metacls._get_mixins_(cls, bases)
if first_enum is not None:
generate = getattr(first_enum, '_generate_next_value_', None)
generate = getattr(generate, 'im_func', generate)
settings |= metacls._get_settings_(bases)
init = init or first_enum._auto_init_[:]
order = first_enum._order_function_
if start is None:
start = first_enum._start_
else:
# first time through -- creating Enum itself
start = 1
# check for custom settings
if AddValue in settings and init and 'value' not in init:
if isinstance(init, list):
init.insert(0, 'value')
else:
init = 'value ' + init
if NoAlias in settings and Unique in settings:
raise TypeError('%r: NoAlias and Unique are mutually exclusive' % cls)
if MultiValue in settings and NoAlias in settings:
raise TypeError('%r: MultiValue and NoAlias are mutually exclusive' % cls)
allowed_settings = dict.fromkeys(['addvalue', 'magicvalue', 'noalias', 'unique', 'multivalue'])
for arg in settings:
if arg not in allowed_settings:
raise TypeError('%r: unknown qualifier %r' % (cls, arg))
enum_dict = _EnumDict(cls_name=cls, settings=settings, start=start, constructor_init=constructor_init, constructor_start=constructor_start, constructor_boundary=constructor_boundary)
enum_dict._member_type = member_type
enum_dict._base_type = ('enum', 'flag')[
Flag is None and cls == 'Flag'
or
Flag is not None and any(issubclass(b, Flag) for b in bases)
]
if Flag is not None and any(b is Flag for b in bases) and member_type not in (baseinteger + (object, )):
if Flag in bases:
# when a non-int data type is mixed in with Flag, we end up
# needing two values for two `__new__`s:
# - the integer value for the Flag itself; and
# - the mix-in value for the mix-in
#
# we provide a default `_generate_next_value_` to supply the int
# argument, and a default `__new__` to keep the two straight
def _generate_next_value_(name, start, count, values, *args, **kwds):
return (2 ** count, ) + args
enum_dict['_generate_next_value_'] = staticmethod(_generate_next_value_)
def __new__(cls, flag_value, type_value):
obj = member_type.__new__(cls, type_value)
obj._value_ = flag_value
return obj
enum_dict['__new__'] = __new__
else:
try:
enum_dict._new_args = _EnumArgSpec(first_enum.__new_member__)
except TypeError:
pass
elif not initial_flag:
if hasattr(first_enum, '__new_member__'):
enum_dict._new_args = _EnumArgSpec(first_enum.__new_member__)
if generate:
enum_dict['_generate_next_value_'] = generate
enum_dict._inherited_gnv = True
if init is not None:
if isinstance(init, basestring):
init = init.replace(',',' ').split()
enum_dict._init = init
elif hasattr(first_enum, '__new_member__'):
enum_dict._new_args = _EnumArgSpec(first_enum.__new_member__)
if order is not None:
enum_dict['_order_'] = staticmethod(order)
return enum_dict
def __init__(cls, *args , **kwds):
pass
def __new__(metacls, cls, bases, clsdict, init=None, start=None, settings=(), boundary=None, **kwds):
# handle py2 case first
if type(clsdict) is not _EnumDict:
# py2 and/or functional API gyrations
init = clsdict.pop('_init_', None)
start = clsdict.pop('_start_', None)
settings = clsdict.pop('_settings_', ())
_order_ = clsdict.pop('_order_', clsdict.pop('__order__', None))
_ignore_ = clsdict.pop('_ignore_', None)
_create_pseudo_member_ = clsdict.pop('_create_pseudo_member_', None)
_create_pseudo_member_values_ = clsdict.pop('_create_pseudo_member_values_', None)
_generate_next_value_ = clsdict.pop('_generate_next_value_', None)
_missing_ = clsdict.pop('_missing_', None)
_missing_value_ = clsdict.pop('_missing_value_', None)
_missing_name_ = clsdict.pop('_missing_name_', None)
_boundary_ = clsdict.pop('_boundary_', None)
_iter_member_ = clsdict.pop('_iter_member_', None)
_iter_member_by_value_ = clsdict.pop('_iter_member_by_value_', None)
_iter_member_by_def_ = clsdict.pop('_iter_member_by_def_', None)
__new__ = clsdict.pop('__new__', None)
__new__ = getattr(__new__, 'im_func', __new__)
__new__ = getattr(__new__, '__func__', __new__)
enum_members = dict([
(k, v) for (k, v) in clsdict.items()
if not (_is_sunder(k) or _is_dunder(k) or _is_private_name(cls, k) or _is_descriptor(v))
])
original_dict = clsdict
clsdict = metacls.__prepare__(cls, bases, init=init, start=start)
if settings:
clsdict['_settings_'] = settings
init = init or clsdict._init
if _order_ is None:
_order_ = clsdict.get('_order_')
if _order_ is not None:
_order_ = _order_.__get__(cls)
if isinstance(original_dict, OrderedDict):
calced_order = original_dict
elif _order_ is None:
calced_order = [name for (name, value) in enumsort(list(enum_members.items()))]
elif isinstance(_order_, basestring):
calced_order = _order_ = _order_.replace(',', ' ').split()
elif callable(_order_):
if init:
if not isinstance(init, basestring):
init = ' '.join(init)
member = NamedTuple('member', init and 'name ' + init or ['name', 'value'])
calced_order = []
for name, value in enum_members.items():
if init:
if not isinstance(value, tuple):
value = (value, )
name_value = (name, ) + value
else:
name_value = tuple((name, value))
if member._defined_len_ != len(name_value):
raise TypeError('%d values expected (%s), %d received (%s)' % (
member._defined_len_,
', '.join(member._fields_),
len(name_value),
', '.join([repr(v) for v in name_value]),
))
calced_order.append(member(*name_value))
calced_order = [m.name for m in sorted(calced_order, key=_order_)]
else:
calced_order = _order_
for name in (
'_missing_', '_missing_value_', '_missing_name_',
'_ignore_', '_create_pseudo_member_', '_create_pseudo_member_values_',
'_generate_next_value_', '_order_', '__new__',
'_missing_', '_missing_value_', '_missing_name_',
'_boundary_',
'_iter_member_', '_iter_member_by_value_', '_iter_member_by_def_',
):
attr = locals()[name]
if attr is not None:
clsdict[name] = attr
# now add members
for k in calced_order:
try:
clsdict[k] = original_dict[k]
except KeyError:
# this error will be handled when _order_ is checked
pass
for k, v in original_dict.items():
if k not in calced_order:
clsdict[k] = v
del _order_, _ignore_, _create_pseudo_member_, _create_pseudo_member_values_,
del _generate_next_value_, _missing_, _missing_value_, _missing_name_
#
# resume normal path
clsdict._locked = True
#
# check for illegal enum names (any others?)
member_names = clsdict._member_names
invalid_names = set(member_names) & set(['mro', ''])
if invalid_names:
raise ValueError('invalid enum member name(s): %s' % (
', '.join(invalid_names), ))
_order_ = clsdict.pop('_order_', None)
if isinstance(_order_, basestring):
_order_ = _order_.replace(',',' ').split()
init = clsdict._init
start = clsdict._start
settings = clsdict._settings
creating_init = []
new_args = clsdict._new_args
auto_args = clsdict._auto_args
auto_init = False
if init is not None:
auto_init = True
creating_init = init[:]
if 'value' in creating_init and creating_init[0] != 'value':
raise TypeError("'value', if specified, must be the first item in 'init'")
magicvalue = MagicValue in settings
multivalue = MultiValue in settings
noalias = NoAlias in settings
unique = Unique in settings
# an Enum class 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).
# an Enum class is final once enumeration items have been defined;
#
# remove any keys listed in _ignore_
clsdict.setdefault('_ignore_', []).append('_ignore_')
ignore = clsdict['_ignore_']
for key in ignore:
clsdict.pop(key, None)
#
boundary = boundary or clsdict.pop('_boundary_', None)
# convert to regular dict
clsdict = dict(clsdict.items())
member_type, first_enum = metacls._get_mixins_(cls, bases)
# get the method to create enum members
__new__, save_new, new_uses_args = metacls._find_new_(
clsdict,
member_type,
first_enum,
)
clsdict['_new_member_'] = staticmethod(__new__)
clsdict['_use_args_'] = new_uses_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 = test_value = clsdict[name]
if isinstance(value, auto) and value.value is not _auto_null:
test_value = value.value
if isinstance(test_value, baseinteger):
flag_mask |= test_value
if isinstance(test_value, tuple) and test_value and isinstance(test_value[0], baseinteger):
flag_mask |= test_value[0]
clsdict[name] = _proto_member(value)
#
# temp stuff
clsdict['_creating_init_'] = creating_init
clsdict['_multivalue_'] = multivalue
clsdict['_magicvalue_'] = magicvalue
clsdict['_noalias_'] = noalias
clsdict['_unique_'] = unique
#
# house-keeping structures
clsdict['_member_names_'] = []
clsdict['_member_map_'] = OrderedDict()
clsdict['_member_type_'] = member_type
clsdict['_value2member_map_'] = {}
clsdict['_value2member_seq_'] = ()
clsdict['_settings_'] = settings
clsdict['_start_'] = start
clsdict['_auto_init_'] = init
clsdict['_new_args_'] = new_args
clsdict['_auto_args_'] = auto_args
clsdict['_order_function_'] = None
# now set the __repr__ for the value
clsdict['_value_repr_'] = metacls._find_data_repr_(cls, bases)
#
# Flag structures (will be removed if final class is not a Flag
clsdict['_boundary_'] = (
boundary
or getattr(first_enum, '_boundary_', None)
)
clsdict['_flag_mask_'] = flag_mask
clsdict['_all_bits_'] = 2 ** ((flag_mask).bit_length()) - 1
clsdict['_inverted_'] = None
#
# move skipped values out of the descriptor
for name, obj in clsdict.items():
if isinstance(obj, nonmember):
clsdict[name] = obj.value
#
# If a custom type is mixed into the Enum, and it does not know how
# to pickle itself, pickle.dumps will succeed but pickle.loads will
# fail. Rather than have the error show up later and possibly far
# from the source, sabotage the pickle protocol for this class so
# that pickle.dumps also fails.
#
# However, if the new class implements its own __reduce_ex__, do not
# sabotage -- it's on them to make sure it works correctly. We use
# __reduce_ex__ instead of any of the others as it is preferred by
# pickle over __reduce__, and it handles all pickle protocols.
unpicklable = False
if '__reduce_ex__' not in clsdict:
if member_type is not object:
methods = ('__getnewargs_ex__', '__getnewargs__',
'__reduce_ex__', '__reduce__')
if not any(m in member_type.__dict__ for m in methods):
_make_class_unpicklable(clsdict)
unpicklable = True
#
# create a default docstring if one has not been provided
if '__doc__' not in clsdict:
clsdict['__doc__'] = 'An enumeration.'
#
# create our new Enum type
try:
exc = None
enum_class = type.__new__(metacls, cls, bases, clsdict)
except RuntimeError as e:
# any exceptions raised by _proto_member (aka 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
#
# if Python 3.5 or ealier, implement the __set_name__ and
# __init_subclass__ protocols
if pyver < PY3_6:
for name in member_names:
enum_class.__dict__[name].__set_name__(enum_class, name)
for name, obj in enum_class.__dict__.items():
if name in member_names:
continue
if hasattr(obj, '__set_name__'):
obj.__set_name__(enum_class, name)
if Enum is not None:
super(enum_class, enum_class).__init_subclass__()
#
# double check that repr and friends are not the mixin's or various
# things break (such as pickle)
#
# Also, special handling for ReprEnum
if ReprEnum is not None and ReprEnum in bases:
if member_type is object:
raise TypeError(
'ReprEnum subclasses must be mixed with a data type (i.e.'
' int, str, float, etc.)'
)
if '__format__' not in clsdict:
enum_class.__format__ = member_type.__format__
clsdict['__format__'] = enum_class.__format__
if '__str__' not in clsdict:
method = member_type.__str__
if method is object.__str__:
# if member_type does not define __str__, object.__str__ will use
# its __repr__ instead, so we'll also use its __repr__
method = member_type.__repr__
enum_class.__str__ = method
clsdict['__str__'] = enum_class.__str__
for name in ('__repr__', '__str__', '__format__', '__reduce_ex__'):
if name in clsdict:
# class has defined/imported/copied the method
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 == class_method:
if name == '__reduce_ex__' and unpicklable:
continue
setattr(enum_class, name, enum_method)
clsdict[name] = enum_method
#
# for Flag, add __or__, __and__, __xor__, and __invert__
if Flag is not None and issubclass(enum_class, Flag):
for name in (
'__or__', '__and__', '__xor__',
'__ror__', '__rand__', '__rxor__',
'__invert__'
):
if name not in clsdict:
setattr(enum_class, name, getattr(Flag, name))
clsdict[name] = enum_method
#
# method resolution and int's are not playing nice
# Python's less than 2.6 use __cmp__
if pyver < PY2_6:
#
if issubclass(enum_class, int):
setattr(enum_class, '__cmp__', getattr(int, '__cmp__'))
#
elif PY2:
#
if issubclass(enum_class, int):
for method in (
'__le__',
'__lt__',
'__gt__',
'__ge__',
'__eq__',
'__ne__',
'__hash__',
):
setattr(enum_class, method, getattr(int, 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:
setattr(enum_class, '__new_member__', enum_class.__dict__['__new__'])
setattr(enum_class, '__new__', Enum.__dict__['__new__'])
#
# _order_ checking is spread out into three/four steps
# - ensure _order_ is a list, not a string nor a function
# - 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
#
# _order_ step 1: ensure _order_ is a list
if _order_:
if isinstance(_order_, staticmethod):
_order_ = _order_.__func__
if callable(_order_):
# save order for future subclasses
enum_class._order_function_ = staticmethod(_order_)
# create ordered list for comparison
_order_ = [m.name for m in sorted(enum_class, key=_order_)]
#
# 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():
if _is_single_bit(flag._value_):
single_bit_total |= flag._value_
else:
# multi-bit flags are considered aliases
multi_bit_total |= flag._value_
if enum_class._boundary_ is not KEEP:
missed = list(_iter_bits_lsb(multi_bit_total & ~single_bit_total))
if missed:
raise TypeError(
'invalid Flag %r -- missing values: %s'
% (cls, ', '.join((str(i) for i in missed)))
)
enum_class._flag_mask_ = single_bit_total
enum_class._all_bits_ = 2 ** ((single_bit_total).bit_length()) - 1
#
# set correct __iter__
if [m._value_ for m in enum_class] != sorted([m._value_ for m in enum_class]):
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_)
]
#
# check for constants with auto() values
for k, v in enum_class.__dict__.items():
if isinstance(v, constant) and isinstance(v.value, auto):
v.value = enum_class(v.value.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__(cls):
"""
classes/types should always be True.
"""
return True
def __call__(cls, value=no_arg, names=None, module=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: `module`, if set, will be stored in
the new class' __module__ attribute; `type`, if set, will be mixed in
as the first base class.
Note: if `module` is not set this routine will attempt to discover the
calling module by walking the frame stack; if this is unsuccessful
the resulting class will not be pickleable.
"""
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, type=type, start=start, boundary=boundary)
def __contains__(cls, member):
if not isinstance(member, Enum):
raise TypeError("%r (%r) is not an <aenum 'Enum'>" % (member, type(member)))
if not isinstance(member, cls):
return False
return True
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),
)
found_attr = _get_attr_from_chain(cls, attr)
if isinstance(found_attr, constant):
raise AttributeError(
"%s: cannot delete constant %r" % (cls.__name__, attr),
)
elif isinstance(found_attr, property):
raise AttributeError(
"%s: cannot delete property %r" % (cls.__name__, attr),
)
super(EnumType, cls).__delattr__(attr)
def __dir__(cls):
interesting = set(cls._member_names_ + [
'__class__', '__contains__', '__doc__', '__getitem__',
'__iter__', '__len__', '__members__', '__module__',
'__name__',
])
if cls._new_member_ is not object.__new__:
interesting.add('__new__')
if cls.__init_subclass__ is not Enum.__init_subclass__:
interesting.add('__init_subclass__')
if hasattr(object, '__qualname__'):
interesting.add('__qualname__')
for method in ('__init__', '__format__', '__repr__', '__str__'):
if getattr(cls, method) not in (getattr(Enum, method), getattr(Flag, method)):
interesting.add(method)
if cls._member_type_ is object:
return sorted(interesting)
else:
# return whatever mixed-in data type has
return sorted(set(dir(cls._member_type_)) | interesting)
@_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 copy of the internal mapping.
"""
return cls._member_map_.copy()
def __getitem__(cls, name):
try:
return cls._member_map_[name]
except KeyError:
exc = _sys.exc_info()[1]
if Flag is not None and issubclass(cls, Flag) and '|' in name:
try:
# may be an __or__ed name
result = cls(0)
for n in name.split('|'):
result |= cls[n]
return result
except KeyError:
raise exc
result = cls._missing_name_(name)
if isinstance(result, cls):
return result
else:
raise exc
def __iter__(cls):
return (cls._member_map_[name] for name in cls._member_names_)
def __reversed__(cls):
return (cls._member_map_[name] for name in reversed(cls._member_names_))
def __len__(cls):
return len(cls._member_names_)
__nonzero__ = __bool__
def __repr__(cls):
return "<aenum %r>" % (cls.__name__, )
def __setattr__(cls, name, value):
"""Block attempts to reassign Enum members/constants.
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(
'%s: cannot rebind member %r.' % (cls.__name__, name),
)
found_attr = _get_attr_from_chain(cls, name)
if isinstance(found_attr, constant):
raise AttributeError(
"%s: cannot rebind constant %r" % (cls.__name__, name),
)
elif isinstance(found_attr, property):
raise AttributeError(
"%s: cannot rebind property %r" % (cls.__name__, name),
)
super(EnumType, cls).__setattr__(name, value)
def _convert(cls, *args, **kwds):
import warnings
warnings.warn("_convert is deprecated and will be removed, use"
" _convert_ instead.", DeprecationWarning, stacklevel=2)
return cls._convert_(*args, **kwds)
def _convert_(cls, name, module, filter, source=None, boundary=None, as_global=False):
"""
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 = vars(_sys.modules[module])
if source:
source = vars(source)
else:
source = module_globals
members = [(key, source[key]) for key in source.keys() if filter(key)]
try:
# sort by value, name
members.sort(key=lambda t: (t[1], t[0]))
except TypeError:
# unless some values aren't comparable, in which case sort by just name
members.sort(key=lambda t: t[0])
cls = cls(name, members, module=module, boundary=boundary or KEEP)
cls.__reduce_ex__ = _reduce_ex_by_name
if as_global:
global_enum(cls)
else:
module_globals.update(cls.__members__)
module_globals[name] = cls
return cls
def _create_(cls, class_name, names, module=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 auto-numbered from 1.
* An iterable of member names. Values are auto-numbered from 1.
* An iterable of (member name, value) pairs.
* A mapping of member name -> value.
"""
if PY2:
# if class_name is unicode, attempt a conversion to ASCII
if isinstance(class_name, unicode):
try:
class_name = class_name.encode('ascii')
except UnicodeEncodeError:
raise TypeError('%r is not representable in ASCII' % (class_name, ))
metacls = cls.__class__
if type is None:
bases = (cls, )
else:
bases = (type, cls)
_, first_enum = cls._get_mixins_(class_name, bases)
generate = getattr(first_enum, '_generate_next_value_', None)
generate = getattr(generate, 'im_func', generate)
# special processing needed for names?
if isinstance(names, basestring):
names = names.replace(',', ' ').split()
if isinstance(names, (tuple, list)) and names and isinstance(names[0], basestring):
original_names, names = names, []
last_values = []
for count, name in enumerate(original_names):
value = generate(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.
item = None # in case names is empty
clsdict = None
for item in names:
if clsdict is None:
# first time initialization
if isinstance(item, basestring):
clsdict = {}
else:
# remember the order
clsdict = metacls.__prepare__(class_name, bases)
if isinstance(item, basestring):
member_name, member_value = item, names[item]
else:
member_name, member_value = item
clsdict[member_name] = member_value
if clsdict is None:
# in case names was empty
clsdict = metacls.__prepare__(class_name, bases)
enum_class = metacls.__new__(metacls, class_name, bases, clsdict, boundary=boundary)
# 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, KeyError):
pass
if module is None:
_make_class_unpicklable(enum_class)
else:
enum_class.__module__ = module
return enum_class
@classmethod
def _check_for_existing_members_(mcls, class_name, bases):
if Enum is None:
return
for chain in bases:
for base in chain.__mro__:
if issubclass(base, Enum) and base._member_names_:
raise TypeError(
"<aenum %r> cannot extend %r"
% (class_name, base)
)
@classmethod
def _get_mixins_(mcls, 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 or Enum is None:
return object, Enum
mcls._check_for_existing_members_(class_name, bases)
# 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 = mcls._find_data_type_(class_name, bases) or object
if first_enum._member_names_:
raise TypeError("cannot extend enumerations via subclassing")
#
return member_type, first_enum
@classmethod
def _find_data_repr_(mcls, class_name, bases):
for chain in bases:
for base in chain.__mro__:
if base is object:
continue
elif issubclass(base, Enum):
# if we hit an Enum, use it's _value_repr_
return base._value_repr_
elif '__repr__' in base.__dict__:
# this is our data repr
return base.__dict__['__repr__']
return None
@classmethod
def _find_data_type_(mcls, class_name, bases):
data_types = set()
for chain in bases:
candidate = None
for base in chain.__mro__:
if base is object or base is StdlibEnum or base is StdlibFlag:
continue
elif issubclass(base, Enum):
if base._member_type_ is not object:
data_types.add(base._member_type_)
elif '__new__' in base.__dict__:
if issubclass(base, Enum):
continue
elif StdlibFlag is not None and issubclass(base, StdlibFlag):
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
@staticmethod
def _get_settings_(bases):
"""Returns the combined _settings_ of all Enum base classes
bases: the tuple of bases given to __new__
"""
settings = set()
for chain in bases:
for base in chain.__mro__:
if issubclass(base, Enum):
for s in base._settings_:
settings.add(s)
return settings
@classmethod
def _find_new_(mcls, clsdict, member_type, first_enum):
"""Returns the __new__ to be used for creating the enum members.
clsdict: 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__ = clsdict.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__,
StdlibEnum.__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 __new__ is object.__new__:
new_uses_args = False
else:
new_uses_args = True
#
return __new__, save_new, new_uses_args
# In order to support Python 2 and 3 with a single
# codebase we have to create the Enum methods separately
# and then use the `type(name, bases, dict)` method to
# create the class.
EnumMeta = EnumType
enum_dict = _Addendum(
dict=EnumType.__prepare__('Enum', (object, )),
doc="Generic enumeration.\n\n Derive from this class to define new enumerations.\n\n",
ns=globals(),
)
@enum_dict
def __init__(self, *args, **kwds):
# auto-init method
_auto_init_ = self._auto_init_
if _auto_init_ is None:
return
if 'value' in _auto_init_:
# remove 'value' from _auto_init_ as it has already been handled
_auto_init_ = _auto_init_[1:]
if _auto_init_:
if len(_auto_init_) < len(args):
raise TypeError('%d arguments expected (%s), %d received (%s)'
% (len(_auto_init_), _auto_init_, len(args), args))
for name, arg in zip(_auto_init_, args):
setattr(self, name, arg)
if len(args) < len(_auto_init_):
remaining_args = _auto_init_[len(args):]
for name in remaining_args:
value = kwds.pop(name, undefined)
if value is undefined:
raise TypeError('missing value for: %r' % (name, ))
setattr(self, name, value)
if kwds:
# too many keyword arguments
raise TypeError('invalid keyword(s): %s' % ', '.join(kwds.keys()))
@enum_dict
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 NoAlias in cls._settings_:
raise TypeError('NoAlias enumerations cannot be looked up by value')
if type(value) is cls:
# For lookups like Color(Color.red)
# value = value.value
return value
# by-value search for a matching enum member
# see if it's in the reverse mapping (for hashable values)
try:
if value in cls._value2member_map_:
return cls._value2member_map_[value]
except TypeError:
# not there, now do long search -- O(n) behavior
for name, member in cls._value2member_seq_:
if name == value:
return member
# still not found -- try _missing_ hook
try:
exc = None
result = cls._missing_value_(value)
except Exception as e:
exc = e
result = None
if isinstance(result, cls) or getattr(cls, '_boundary_', None) is EJECT:
return result
else:
if value is no_arg:
ve_exc = ValueError('%s() should be called with a value' % (cls.__name__, ))
else:
ve_exc = ValueError("%r is not a valid %s" % (value, cls.__name__))
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.__cause__ = ve_exc
raise exc
@enum_dict
@classmethod
def __init_subclass__(cls, **kwds):
if pyver < PY3_6:
# end of the line
if kwds:
raise TypeError('unconsumed keyword arguments: %r' % (kwds, ))
else:
super(Enum, cls).__init_subclass__(**kwds)
@enum_dict
@staticmethod
def _generate_next_value_(name, start, count, last_values, *args, **kwds):
for last_value in reversed(last_values):
try:
new_value = last_value + 1
break
except TypeError:
pass
else:
new_value = start
if args:
return (new_value, ) + args
else:
return new_value
@enum_dict
@classmethod
def _missing_(cls, value):
"deprecated, use _missing_value_ instead"
return None
@enum_dict
@classmethod
def _missing_value_(cls, value):
"used for failed value access"
return cls._missing_(value)
@enum_dict
@classmethod
def _missing_name_(cls, name):
"used for failed item access"
return None
@enum_dict
def __repr__(self):
v_repr = self.__class__._value_repr_ or self._value_.__class__.__repr__
return "<%s.%s: %s>" % (self.__class__.__name__, self._name_, v_repr(self._value_))
@enum_dict
def __str__(self):
return "%s.%s" % (self.__class__.__name__, self._name_)
if PY3:
@enum_dict
def __dir__(self):
"""
Returns all members and all public methods
"""
if self.__class__._member_type_ is object:
interesting = set(['__class__', '__doc__', '__eq__', '__hash__', '__module__', 'name', 'value'])
else:
interesting = set(object.__dir__(self))
for name in getattr(self, '__dict__', []):
if name[0] != '_':
interesting.add(name)
for cls in self.__class__.mro():
for name, obj in cls.__dict__.items():
if name[0] == '_':
continue
if isinstance(obj, property):
# that's an enum.property
if obj.fget is not None or name not in self._member_map_:
interesting.add(name)
else:
# in case it was added by `dir(self)`
interesting.discard(name)
else:
interesting.add(name)
return sorted(interesting)
@enum_dict
def __format__(self, format_spec):
# 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 / overridden __str__ branch
overridden_str = self.__class__.__str__ != Enum.__str__
if self._member_type_ is object or overridden_str:
cls = str
val = str(self)
# mix-in branch
else:
cls = self._member_type_
val = self.value
return cls.__format__(val, format_spec)
@enum_dict
def __hash__(self):
return hash(self._name_)
@enum_dict
def __reduce_ex__(self, proto):
return self.__class__, (self._value_, )
####################################
# Python's less than 2.6 use __cmp__
if pyver < PY2_6:
@enum_dict
def __cmp__(self, other):
if type(other) is self.__class__:
if self is other:
return 0
return -1
return NotImplemented
raise TypeError("unorderable types: %s() and %s()" % (self.__class__.__name__, other.__class__.__name__))
else:
@enum_dict
def __le__(self, other):
raise TypeError("unorderable types: %s() <= %s()" % (self.__class__.__name__, other.__class__.__name__))
@enum_dict
def __lt__(self, other):
raise TypeError("unorderable types: %s() < %s()" % (self.__class__.__name__, other.__class__.__name__))
@enum_dict
def __ge__(self, other):
raise TypeError("unorderable types: %s() >= %s()" % (self.__class__.__name__, other.__class__.__name__))
@enum_dict
def __gt__(self, other):
raise TypeError("unorderable types: %s() > %s()" % (self.__class__.__name__, other.__class__.__name__))
@enum_dict
def __eq__(self, other):
if type(other) is self.__class__:
return self is other
return NotImplemented
@enum_dict
def __ne__(self, other):
if type(other) is self.__class__:
return self is not other
return NotImplemented
@enum_dict
def __hash__(self):
return hash(self._name_)
@enum_dict
def __reduce_ex__(self, proto):
return self.__class__, (self._value_, )
# enum.property is used to provide access to the `name`, `value', etc.,
# properties of enum members while keeping some measure of protection
# from modification, while still allowing for an enumeration to have
# members named `name`, `value`, etc.. This works because enumeration
# members are not set directly on the enum class -- enum.property will
# look them up in _member_map_.
@enum_dict
@property
def name(self):
return self._name_
@enum_dict
@property
def value(self):
return self._value_
@enum_dict
@property
def values(self):
return self._values_
def _reduce_ex_by_name(self, proto):
return self.name
Enum = EnumType('Enum', (object, ), enum_dict.resolve())
del enum_dict
# Enum has now been created
class ReprEnum(Enum):
"""
Only changes the repr(), leaving str() and format() to the mixed-in type.
"""
class IntEnum(int, ReprEnum):
"""
Enum where members are also (and must be) ints
"""
class StrEnum(str, ReprEnum):
"""
Enum where members are also (and must already be) strings
default value is member name, lower-cased
"""
def __new__(cls, *values, **kwds):
if kwds:
raise TypeError('%r: keyword arguments not supported' % (cls.__name__))
if values:
if not isinstance(values[0], str):
raise TypeError('%s: values must be str [%r is a %r]' % (cls.__name__, values[0], type(values[0])))
value = str(*values)
member = str.__new__(cls, value)
member._value_ = value
return member
__str__ = str.__str__
def _generate_next_value_(name, start, count, last_values):
"""
Return the lower-cased version of the member name.
"""
return name.lower()
class LowerStrEnum(StrEnum):
"""
Enum where members are also (and must already be) lower-case strings
default value is member name, lower-cased
"""
def __new__(cls, value, *args, **kwds):
obj = StrEnum.__new_member__(cls, value, *args, **kwds)
if value != value.lower():
raise ValueError('%r is not lower-case' % value)
return obj
class UpperStrEnum(StrEnum):
"""
Enum where members are also (and must already be) upper-case strings
default value is member name, upper-cased
"""
def __new__(cls, value, *args, **kwds):
obj = StrEnum.__new_member__(cls, value, *args, **kwds)
if value != value.upper():
raise ValueError('%r is not upper-case' % value)
return obj
def _generate_next_value_(name, start, count, last_values, *args, **kwds):
return name.upper()
if PY3:
class AutoEnum(Enum):
"""
automatically use _generate_next_value_ when values are missing (Python 3 only)
"""
_settings_ = MagicValue
class AutoNumberEnum(Enum):
"""
Automatically assign increasing values to members.
Py3: numbers match creation order
Py2: numbers are assigned alphabetically by member name
(unless `_order_` is specified)
"""
def __new__(cls, *args, **kwds):
value = len(cls.__members__) + 1
if cls._member_type_ is int:
obj = int.__new__(cls, value)
elif cls._member_type_ is long:
obj = long.__new__(cls, value)
else:
obj = object.__new__(cls)
obj._value_ = value
return obj
class AddValueEnum(Enum):
_settings_ = AddValue
class MultiValueEnum(Enum):
"""
Multiple values can map to each member.
"""
_settings_ = MultiValue
class NoAliasEnum(Enum):
"""
Duplicate value members are distinct, but cannot be looked up by value.
"""
_settings_ = NoAlias
class OrderedEnum(Enum):
"""
Add ordering based on values of Enum members.
"""
def __ge__(self, other):
if self.__class__ is other.__class__:
return self._value_ >= other._value_
return NotImplemented
def __gt__(self, other):
if self.__class__ is other.__class__:
return self._value_ > other._value_
return NotImplemented
def __le__(self, other):
if self.__class__ is other.__class__:
return self._value_ <= other._value_
return NotImplemented
def __lt__(self, other):
if self.__class__ is other.__class__:
return self._value_ < other._value_
return NotImplemented
if sqlite3:
class SqliteEnum(Enum):
def __conform__(self, protocol):
if protocol is sqlite3.PrepareProtocol:
return self.name
class UniqueEnum(Enum):
"""
Ensure no duplicate values exist.
"""
_settings_ = Unique
def convert(enum, name, module, filter, source=None):
"""
Create a new Enum subclass that replaces a collection of global constants
enum: Enum, IntEnum, ...
name: name of new Enum
module: name of module (__name__ in global context)
filter: function that returns True if name should be converted to Enum member
source: namespace to check (defaults to 'module')
"""
# 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 = vars(_sys.modules[module])
if source:
source = vars(source)
else:
source = module_globals
members = dict((name, value) for name, value in source.items() if filter(name))
enum = enum(name, members, module=module)
enum.__reduce_ex__ = _reduce_ex_by_name
module_globals.update(enum.__members__)
module_globals[name] = enum
def extend_enum(enumeration, name, *args, **kwds):
"""
Add a new member to an existing Enum.
"""
# there are four possibilities:
# - extending an aenum Enum or 3.11+ enum Enum
# - extending an aenum Flag or 3.11+ enum Flag
# - extending a pre-3.11 stdlib Enum Flag
# - extending a 3.11+ stdlib Flag
#
# fail early if name is already in the enumeration
if (
name in enumeration.__dict__
or name in enumeration._member_map_
or name in [t[1] for t in getattr(enumeration, '_value2member_seq_', ())]
):
raise TypeError('%r already in use as %r' % (name, enumeration.__dict__.get(name, enumeration[name])))
# and check for other instances in parent classes
descriptor = None
for base in enumeration.__mro__[1:]:
descriptor = base.__dict__.get(name)
if descriptor is not None:
if isinstance(descriptor, (property, DynamicClassAttribute)):
break
else:
raise TypeError('%r already in use in superclass %r' % (name, base.__name__))
try:
_member_map_ = enumeration._member_map_
_member_names_ = enumeration._member_names_
_member_type_ = enumeration._member_type_
_value2member_map_ = enumeration._value2member_map_
base_attributes = set([a for b in enumeration.mro() for a in b.__dict__])
except AttributeError:
raise TypeError('%r is not a supported Enum' % (enumeration, ))
try:
_value2member_seq_ = enumeration._value2member_seq_
_multi_value_ = MultiValue in enumeration._settings_
_no_alias_ = NoAlias in enumeration._settings_
_unique_ = Unique in enumeration._settings_
_auto_init_ = enumeration._auto_init_ or []
except AttributeError:
# standard Enum
_value2member_seq_ = []
_multi_value_ = False
_no_alias_ = False
_unique_ = False
_auto_init_ = []
if _multi_value_ and not args:
# must specify values for multivalue enums
raise ValueError('no values specified for MultiValue enum %r' % enumeration.__name__)
mt_new = _member_type_.__new__
_new = getattr(enumeration, '__new_member__', mt_new)
if not args:
last_values = [m.value for m in enumeration]
count = len(enumeration)
start = getattr(enumeration, '_start_', None)
if start is None:
start = last_values and (last_values[-1] + 1) or 1
_gnv = getattr(enumeration, '_generate_next_value_', None)
if _gnv is not None:
args = ( _gnv(name, start, count, last_values), )
else:
# must be a 3.4 or 3.5 Enum
args = (start, )
if _new is object.__new__:
new_uses_args = False
else:
new_uses_args = True
if len(args) == 1:
[value] = args
else:
value = args
more_values = ()
kwds = {}
if isinstance(value, enum):
args = value.args
kwds = value.kwds
if not isinstance(value, tuple):
args = (value, )
else:
args = value
# tease value out of auto-init if specified
if 'value' in _auto_init_:
if 'value' in kwds:
value = kwds.pop('value')
else:
value, args = args[0], args[1:]
elif _multi_value_:
value, more_values, args = args[0], args[1:], ()
if new_uses_args:
args = (value, )
if _member_type_ is tuple:
args = (args, )
if not new_uses_args:
new_member = _new(enumeration)
if not hasattr(new_member, '_value_'):
new_member._value_ = value
else:
new_member = _new(enumeration, *args, **kwds)
if not hasattr(new_member, '_value_'):
new_member._value_ = _member_type_(*args)
value = new_member._value_
if _multi_value_:
if 'value' in _auto_init_:
args = more_values
else:
# put all the values back into args for the init call
args = (value, ) + more_values
new_member._name_ = name
new_member.__objclass__ = enumeration.__class__
new_member.__init__(*args)
new_member._values_ = (value, ) + more_values
# do final checks before modifying enum structures:
# - is new member a flag?
# - does the new member fit in the enum's declared _boundary_?
# - is new member an alias?
#
_all_bits_ = _flag_mask_ = None
if hasattr(enumeration, '_all_bits_'):
_all_bits_ = enumeration._all_bits_ | value
_flag_mask_ = enumeration._flag_mask_ | value
if enumeration._boundary_ != 'keep':
missed = list(_iter_bits_lsb(_flag_mask_ & ~_all_bits_))
if missed:
raise TypeError(
'invalid Flag %r -- missing values: %s'
% (cls, ', '.join((str(i) for i in missed)))
)
# If another member with the same value was already defined, the
# new member becomes an alias to the existing one.
if _no_alias_:
# unless NoAlias was specified
return _finalize_extend_enum(enumeration, new_member, bits=_all_bits_, mask=_flag_mask_)
else:
# handle "normal" aliases
new_values = new_member._values_
for canonical_member in _member_map_.values():
canonical_values_ = getattr(canonical_member, '_values_', [canonical_member._value_])
for canonical_value in canonical_values_:
for new_value in new_values:
if canonical_value == new_value:
# name is an alias
if _unique_ or _multi_value_:
# aliases not allowed in Unique and MultiValue enums
raise ValueError('%r is a duplicate of %r' % (new_member, canonical_member))
else:
# aliased name can be added, remaining checks irrelevant
# aliases don't appear in member names (only in __members__ and _member_map_).
return _finalize_extend_enum(enumeration, canonical_member, name=name, bits=_all_bits_, mask=_flag_mask_, is_alias=True)
# not a standard alias, but maybe a flag alias
if pyver < PY3_6:
flag_bases = Flag,
else:
flag_bases = Flag, StdlibFlag
if issubclass(enumeration, flag_bases) and hasattr(enumeration, '_all_bits_'):
# handle the new flag type
if _is_single_bit(value):
# a new member! (an aliase would have been discovered in the previous loop)
return _finalize_extend_enum(enumeration, new_member, bits=_all_bits_, mask=_flag_mask_)
else:
# might be an 3.11 Flag alias
if value & enumeration._flag_mask_ == value and _value2member_map_.get(value) is not None:
# yup, it's an alias to existing members... and its an alias of an alias
canonical = _value2member_map_.get(value)
return _finalize_extend_enum(enumeration, canonical, name=name, bits=_all_bits_, mask=_flag_mask_, is_alias=True)
else:
return _finalize_extend_enum(enumeration, new_member, bits=_all_bits_, mask=_flag_mask_, is_alias=True)
else:
# if we get here, we have a brand new member
return _finalize_extend_enum(enumeration, new_member)
def _finalize_extend_enum(enumeration, new_member, name=None, bits=None, mask=None, is_alias=False):
name = name or new_member.name
descriptor = None
for base in enumeration.__mro__[1:]:
descriptor = base.__dict__.get(name)
if descriptor is not None:
if isinstance(descriptor, (property, DynamicClassAttribute)):
break
else:
raise TypeError('%r already in use in superclass %r' % (name, base.__name__))
if not descriptor:
# get redirect in place before adding to _member_map_
redirect = property()
redirect.__set_name__(enumeration, name)
setattr(enumeration, name, redirect)
if not is_alias:
enumeration._member_names_.append(name)
enumeration._member_map_[name] = new_member
for v in getattr(new_member, '_values_', [new_member._value_]):
try:
enumeration._value2member_map_[v] = new_member
except TypeError:
enumeration._value2member_seq_ += ((v, new_member), )
if bits:
enumeration._all_bits_ = bits
enumeration._flag_mask_ = mask
return new_member
def unique(enumeration):
"""
Class decorator that ensures only unique members exist in an enumeration.
"""
duplicates = []
for name, member in enumeration.__members__.items():
if name != member.name:
duplicates.append((name, member.name))
if duplicates:
duplicate_names = ', '.join(
["%s -> %s" % (alias, name) for (alias, name) in duplicates]
)
raise ValueError('duplicate names found in %r: %s' %
(enumeration, duplicate_names)
)
return enumeration
# Flag
@export(globals())
class FlagBoundary(StrEnum):
"""
control how out of range values are handled
"strict" -> error is raised [default]
"conform" -> extra bits are discarded
"eject" -> lose flag status (becomes a normal integer)
"""
STRICT = auto()
CONFORM = auto()
EJECT = auto()
KEEP = auto()
assert FlagBoundary.STRICT == 'strict', (FlagBoundary.STRICT, FlagBoundary.CONFORM)
class Flag(Enum):
"""
Generic flag enumeration.
Derive from this class to define new flag enumerations.
"""
_boundary_ = STRICT
_numeric_repr_ = repr
def _generate_next_value_(name, start, count, last_values, *args, **kwds):
"""
Generate the next value when not given.
name: the name of the member
start: the initital start value or None
count: the number of existing members
last_value: the last value assigned or None
"""
if not count:
if args:
return ((1, start)[start is not None], ) + args
else:
return (1, start)[start is not None]
else:
last_value = max(last_values)
try:
high_bit = _high_bit(last_value)
result = 2 ** (high_bit+1)
if args:
return (result,) + args
else:
return result
except Exception:
pass
raise TypeError('invalid Flag value: %r' % last_value)
@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.
"""
members = list(cls._iter_member_by_value_(value))
members.sort(key=lambda m: m._sort_order_)
for member in members:
yield member
@classmethod
def _missing_(cls, value):
"""
return a member matching the given value, or None
"""
return cls._create_pseudo_member_(value)
@classmethod
def _create_pseudo_member_(cls, *values):
"""
Create a composite member.
"""
value = values[0]
if not isinstance(value, baseinteger):
raise ValueError(
"%r is not a valid %s" % (value, getattr(cls, '__qualname__', cls.__name__))
)
# 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)
neg_value = None
if (
not ~cls._all_bits_ <= value <= cls._all_bits_
or value & (cls._all_bits_ ^ cls._flag_mask_)
):
if cls._boundary_ is STRICT:
max_bits = max(value.bit_length(), cls._flag_mask_.bit_length())
raise ValueError(
"%s: invalid value: %r\n given %s\n allowed %s"
% (cls.__name__, value, bin(value, max_bits), bin(cls._flag_mask_, max_bits))
)
elif cls._boundary_ is CONFORM:
value = value & cls._flag_mask_
elif cls._boundary_ is EJECT:
return value
elif cls._boundary_ is KEEP:
if value < 0:
value = (
max(cls._all_bits_+1, 2**(value.bit_length()))
+ value
)
else:
raise ValueError(
'unknown flag boundary: %r' % (cls._boundary_, )
)
if value < 0:
neg_value = value
value = cls._all_bits_ + 1 + value
# get members and unknown
unknown = value & ~cls._flag_mask_
members = list(cls._iter_member_(value))
if unknown and cls._boundary_ is not KEEP:
raise ValueError(
'%s(%r) --> unknown values %r [%s]'
% (cls.__name__, value, unknown, bin(unknown))
)
# let class adjust values
values = cls._create_pseudo_member_values_(members, *values)
__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, *values)
if not hasattr(pseudo_member, 'value'):
pseudo_member._value_ = value
if members:
pseudo_member._name_ = '|'.join([m._name_ for m in members])
if unknown:
pseudo_member._name_ += '|%s' % cls._numeric_repr_(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
@classmethod
def _create_pseudo_member_values_(cls, members, *values):
"""
Return values to be fed to __new__ to create new member.
"""
if cls._member_type_ in (baseinteger + (object, )):
return values
elif len(values) < 2:
return values + (cls._member_type_(), )
else:
return values
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).__name__, self.__class__.__name__))
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.
"""
for member in self._iter_member_(self._value_):
yield member
def __len__(self):
return _bit_count(self._value_)
def __repr__(self):
cls = self.__class__
if self._name_ is None:
# only zero is unnamed by default
return '<%s: %r>' % (cls.__name__, self._value_)
else:
return '<%s.%s: %r>' % (cls.__name__, self._name_, self._value_)
def __str__(self):
cls = self.__class__
if self._name_ is None:
return '%s(%s)' % (cls.__name__, self._value_)
else:
return '%s.%s' % (cls.__name__, self._name_)
if PY2:
def __nonzero__(self):
return bool(self._value_)
else:
def __bool__(self):
return bool(self._value_)
def __or__(self, other):
if isinstance(other, self.__class__):
other_value = other._value_
elif self._member_type_ is not object and isinstance(other, self._member_type_):
other_value = other
else:
return NotImplemented
return self.__class__(self._value_ | other_value)
def __and__(self, other):
if isinstance(other, self.__class__):
other_value = other._value_
elif self._member_type_ is not object and isinstance(other, self._member_type_):
other_value = other
else:
return NotImplemented
return self.__class__(self._value_ & other_value)
def __xor__(self, other):
if isinstance(other, self.__class__):
other_value = other._value_
elif self._member_type_ is not object and isinstance(other, self._member_type_):
other_value = other
else:
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_)
self._inverted_._inverted_ = self
return self._inverted_
__ror__ = __or__
__rand__ = __and__
__rxor__ = __xor__
class IntFlag(int, ReprEnum, Flag):
"""Support for integer-based Flags"""
_boundary_ = EJECT
def _high_bit(value):
"""returns index of highest bit, or -1 if value is zero or negative"""
return value.bit_length() - 1
def global_enum_repr(self):
"""
use module.enum_name instead of class.enum_name
the module is the last module in case of a multi-module name
"""
module = self.__class__.__module__.split('.')[-1]
return '%s.%s' % (module, self._name_)
def global_flag_repr(self):
"""
use module.flag_name instead of class.flag_name
the module is the last module in case of a multi-module name
"""
module = self.__class__.__module__.split('.')[-1]
cls_name = self.__class__.__name__
if self._name_ is None:
return "%s.%s(%r)" % (module, cls_name, self._value_)
if _is_single_bit(self):
return '%s.%s' % (module, self._name_)
if self._boundary_ is not FlagBoundary.KEEP:
return '|'.join(['%s.%s' % (module, name) for name in self.name.split('|')])
else:
name = []
for n in self._name_.split('|'):
if n[0].isdigit():
name.append(n)
else:
name.append('%s.%s' % (module, n))
return '|'.join(name)
def global_str(self):
"""
use enum_name instead of class.enum_name
"""
if self._name_ is None:
return "%s(%r)" % (cls_name, self._value_)
else:
return self._name_
def global_enum(cls, update_str=False):
"""
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
if not issubclass(cls, ReprEnum) or update_str:
cls.__str__ = global_str
_sys.modules[cls.__module__].__dict__.update(cls.__members__)
return cls
class module(object):
def __init__(self, cls, *args):
self.__name__ = cls.__name__
self._parent_module = cls.__module__
self.__all__ = []
all_objects = cls.__dict__
if not args:
args = [k for k, v in all_objects.items() if isinstance(v, (NamedConstant, Enum))]
for name in args:
self.__dict__[name] = all_objects[name]
self.__all__.append(name)
def register(self):
_sys.modules["%s.%s" % (self._parent_module, self.__name__)] = self
if StdlibEnumMeta:
from _weakrefset import WeakSet
def __subclasscheck__(cls, subclass):
"""
Override for issubclass(subclass, cls).
"""
if not isinstance(subclass, type):
raise TypeError('issubclass() arg 1 must be a class (got %r)' % (subclass, ))
# Check cache
try:
cls.__dict__['_subclass_cache_']
except KeyError:
cls._subclass_cache_ = WeakSet()
cls._subclass_negative_cache_ = WeakSet()
if subclass in cls._subclass_cache_:
return True
# Check negative cache
elif subclass in cls._subclass_negative_cache_:
return False
if cls is subclass:
cls._subclass_cache_.add(subclass)
return True
# Check if it's a direct subclass
if cls in getattr(subclass, '__mro__', ()):
cls._subclass_cache_.add(subclass)
return True
# Check if it's a subclass of a subclass (recursive)
for scls in cls.__subclasses__():
if issubclass(subclass, scls):
cls._subclass_cache_.add(subclass)
return True
# Check if it's an aenum.Enum|IntEnum|IntFlag|Flag subclass
if cls is StdlibIntFlag and issubclass(subclass, IntFlag):
cls._subclass_cache_.add(subclass)
return True
elif cls is StdlibFlag and issubclass(subclass, Flag):
cls._subclass_cache_.add(subclass)
return True
elif cls is StdlibIntEnum and issubclass(subclass, IntEnum):
cls._subclass_cache_.add(subclass)
return True
if cls is StdlibEnum and issubclass(subclass, Enum):
cls._subclass_cache_.add(subclass)
return True
# No dice; update negative cache
cls._subclass_negative_cache_.add(subclass)
return False
def __instancecheck__(cls, instance):
subclass = instance.__class__
return cls.__subclasscheck__(subclass)
StdlibEnumMeta.__subclasscheck__ = __subclasscheck__
StdlibEnumMeta.__instancecheck__ = __instancecheck__