diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -30,55 +30,89 @@ one decorator, :func:`unique`. .. class:: Enum Base class for creating enumerated constants. See section `Functional API`_ for an alternate construction syntax. .. class:: IntEnum Base class for creating enumerated constants that are also subclasses of :class:`int`. +.. class:: AutoEnum + + Base class for creating automatically numbered members (may + be combined with IntEnum if desired). + + .. versionadded:: 3.6 + .. function:: unique Enum class decorator that ensures only one name is bound to any one value. Creating an Enum ---------------- Enumerations are created using the :keyword:`class` syntax, which makes them easy to read and write. An alternative creation method is described in -`Functional API`_. To define an enumeration, subclass :class:`Enum` as -follows:: +`Functional API`_. To define a simple enumeration, subclass :class:`AutoEnum` +as follows:: - >>> from enum import Enum - >>> class Color(Enum): - ... red = 1 - ... green = 2 - ... blue = 3 + >>> from enum import AutoEnum + >>> class Color(AutoEnum): + ... red + ... green + ... blue ... .. note:: Nomenclature - The class :class:`Color` is an *enumeration* (or *enum*) - The attributes :attr:`Color.red`, :attr:`Color.green`, etc., are *enumeration members* (or *enum members*). - The enum members have *names* and *values* (the name of :attr:`Color.red` is ``red``, the value of :attr:`Color.blue` is ``3``, etc.) .. note:: Even though we use the :keyword:`class` syntax to create Enums, Enums are not normal Python classes. See `How are Enums different?`_ for more details. +To create your own automatic :class:`Enum` classes, you need to add a +:meth:`_generate_next_value_` method; it will be used to create missing values +for any members after its definition. + +.. versionadded:: 3.6 + +If you need full control of the member values, use :class:`Enum` as the base +class and specify the values manually:: + + >>> from enum import Enum + >>> class Color(Enum): + ... red = 19 + ... green = 7.9182 + ... blue = 'periwinkle' + ... + +We'll use the following Enum for the examples below:: + + >>> class Color(Enum): + ... red = 1 + ... green = 2 + ... blue = 3 + ... + +Enum Details +------------ + Enumeration members have human readable string representations:: >>> print(Color.red) Color.red ...while their ``repr`` has more information:: >>> print(repr(Color.red)) @@ -250,21 +284,21 @@ Enumeration members are compared by iden False >>> Color.red is not Color.blue True Ordered comparisons between enumeration values are *not* supported. Enum members are not integers (but see `IntEnum`_ below):: >>> Color.red < Color.blue Traceback (most recent call last): File "", line 1, in - TypeError: unorderable types: Color() < Color() + TypeError: '<' not supported between instances of 'Color' and 'Color' Equality comparisons are defined though:: >>> Color.blue == Color.red False >>> Color.blue != Color.red True >>> Color.blue == Color.blue True @@ -273,24 +307,24 @@ Comparisons against non-enumeration valu below):: >>> Color.blue == 2 False Allowed members and attributes of enumerations ---------------------------------------------- The examples above use integers for enumeration values. Using integers is -short and handy (and provided by default by the `Functional API`_), but not -strictly enforced. In the vast majority of use-cases, one doesn't care what -the actual value of an enumeration is. But if the value *is* important, -enumerations can have arbitrary values. +short and handy (and provided by default by :class:`AutoEnum` and the +`Functional API`_), but not strictly enforced. In the vast majority of +use-cases, one doesn't care what the actual value of an enumeration is. +But if the value *is* important, enumerations can have arbitrary values. Enumerations are Python classes, and can have methods and special methods as usual. If we have this enumeration:: >>> class Mood(Enum): ... funky = 1 ... happy = 3 ... ... def describe(self): ... # self is the member here @@ -386,47 +420,51 @@ The :class:`Enum` class is callable, pro >>> Animal = Enum('Animal', 'ant bee cat dog') >>> Animal >>> Animal.ant >>> Animal.ant.value 1 >>> list(Animal) [, , , ] -The semantics of this API resemble :class:`~collections.namedtuple`. The first -argument of the call to :class:`Enum` is the name of the enumeration. +The semantics of this API resemble :class:`~collections.namedtuple`. -The second argument is the *source* of enumeration member names. It can be a -whitespace-separated string of names, a sequence of names, a sequence of -2-tuples with key/value pairs, or a mapping (e.g. dictionary) of names to -values. The last two options enable assigning arbitrary values to -enumerations; the others auto-assign increasing integers starting with 1 (use -the ``start`` parameter to specify a different starting value). A -new class derived from :class:`Enum` is returned. In other words, the above -assignment to :class:`Animal` is equivalent to:: +- the first argument of the call to :class:`Enum` is the name of the + enumeration; + +- the second argument is the *source* of enumeration member names. It can be a + whitespace-separated string of names, a sequence of names, a sequence of + 2-tuples with key/value pairs, or a mapping (e.g. dictionary) of names to + values; + +- the last two options enable assigning arbitrary values to enumerations; the + others auto-assign increasing integers starting with 1 (use the ``start`` + parameter to specify a different starting value). A new class derived from + :class:`Enum` is returned. In other words, the above assignment to + :class:`Animal` is equivalent to:: >>> class Animal(Enum): ... ant = 1 ... bee = 2 ... cat = 3 ... dog = 4 ... The reason for defaulting to ``1`` as the starting number and not ``0`` is that ``0`` is ``False`` in a boolean sense, but enum members all evaluate to ``True``. Pickling enums created with the functional API can be tricky as frame stack implementation details are used to try and figure out which module the enumeration is being created in (e.g. it will fail if you use a utility -function in separate module, and also may not work on IronPython or Jython). +function in a separate module, and also may not work on IronPython or Jython). The solution is to specify the module name explicitly as follows:: >>> Animal = Enum('Animal', 'ant bee cat dog', module=__name__) .. warning:: If ``module`` is not supplied, and Enum cannot determine what it is, the new Enum members will not be unpicklable; to keep errors closer to the source, pickling will be disabled. @@ -468,24 +506,55 @@ The complete signature is:: :start: number to start counting at if only names are passed in. .. versionchanged:: 3.5 The *start* parameter was added. Derived Enumerations -------------------- +AutoEnum +^^^^^^^^ + +This version of :class:`Enum` automatically assigns numbers as the values +for the enumeration members, while still allowing values to be specified +when needed:: + + >>> from enum import AutoEnum + >>> class Color(AutoEnum): + ... red + ... green = 5 + ... blue + ... + >>> list(Color) + [, , ] + +.. note:: Name Lookup + + By default the names :func:`property`, :func:`classmethod`, and + :func:`staticmethod` are shielded from becoming members. To enable + them, or to specify a different set of shielded names, specify the + ignore list:: + + >>> class AddressType(AutoEnum, ignore='classmethod staticmethod'): + ... pobox + ... mailbox + ... property + ... + +.. versionadded:: 3.6 + IntEnum ^^^^^^^ -A variation of :class:`Enum` is provided which is also a subclass of +Another variation of :class:`Enum` which is also a subclass of :class:`int`. Members of an :class:`IntEnum` can be compared to integers; by extension, integer enumerations of different types can also be compared to each other:: >>> from enum import IntEnum >>> class Shape(IntEnum): ... circle = 1 ... square = 2 ... >>> class Request(IntEnum): @@ -514,40 +583,41 @@ However, they still can't be compared to :class:`IntEnum` values behave like integers in other ways you'd expect:: >>> int(Shape.circle) 1 >>> ['a', 'b', 'c'][Shape.circle] 'b' >>> [i for i in range(Shape.square)] [0, 1] -For the vast majority of code, :class:`Enum` is strongly recommended, -since :class:`IntEnum` breaks some semantic promises of an enumeration (by -being comparable to integers, and thus by transitivity to other +For the vast majority of code, :class:`Enum` and :class:`AutoEnum` are strongly +recommended, since :class:`IntEnum` breaks some semantic promises of an +enumeration (by being comparable to integers, and thus by transitivity to other unrelated enumerations). It should be used only in special cases where -there's no other choice; for example, when integer constants are -replaced with enumerations and backwards compatibility is required with code -that still expects integers. - +there's no other choice; for example, when integer constants are replaced with +enumerations and backwards compatibility is required with code that still +expects integers. Others ^^^^^^ While :class:`IntEnum` is part of the :mod:`enum` module, it would be very simple to implement independently:: class IntEnum(int, Enum): pass This demonstrates how similar derived enumerations can be defined; for example -a :class:`StrEnum` that mixes in :class:`str` instead of :class:`int`. +an :class:`AutoIntEnum` that mixes in :class:`int` with :class:`AutoEnum` +to get members that are :class:`int` (but keep in mind the warnings for +:class:`IntEnum`). Some rules: 1. When subclassing :class:`Enum`, mix-in types must appear before :class:`Enum` itself in the sequence of bases, as in the :class:`IntEnum` example above. 2. While :class:`Enum` can have members of any type, once you mix in an additional type, all the members must have values of that type, e.g. :class:`int` above. This restriction does not apply to mix-ins which only add methods and don't specify another data type such as :class:`int` or @@ -560,52 +630,73 @@ 4. %-style formatting: `%s` and `%r` ca `%i` or `%h` for IntEnum) treat the enum member as its mixed-in type. 5. :ref:`Formatted string literals `, :meth:`str.format`, and :func:`format` will use the mixed-in type's :meth:`__format__`. If the :class:`Enum` class's :func:`str` or :func:`repr` is desired, use the `!s` or `!r` format codes. Interesting examples -------------------- -While :class:`Enum` and :class:`IntEnum` are expected to cover the majority of -use-cases, they cannot cover them all. Here are recipes for some different -types of enumerations that can be used directly, or as examples for creating -one's own. +While :class:`Enum`, :class:`AutoEnum`, and :class:`IntEnum` are expected +to cover the majority of use-cases, they cannot cover them all. Here are +recipes for some different types of enumerations that can be used directly, +or as examples for creating one's own. -AutoNumber -^^^^^^^^^^ +AutoDocEnum +^^^^^^^^^^^ -Avoids having to specify the value for each enumeration member:: +Automatically numbers the members, and uses the given value as the +:attr:`__doc__` string:: - >>> class AutoNumber(Enum): - ... def __new__(cls): + >>> class AutoDocEnum(Enum): + ... def __new__(cls, doc): ... value = len(cls.__members__) + 1 ... obj = object.__new__(cls) ... obj._value_ = value + ... obj.__doc__ = doc ... return obj ... - >>> class Color(AutoNumber): - ... red = () - ... green = () - ... blue = () + >>> class Color(AutoDocEnum): + ... red = 'stop' + ... green = 'go' + ... blue = 'what?' ... >>> Color.green.value == 2 True + >>> Color.green.__doc__ + 'go' .. note:: The :meth:`__new__` method, if defined, is used during creation of the Enum members; it is then replaced by Enum's :meth:`__new__` which is used after class creation for lookup of existing members. +AutoNameEnum +^^^^^^^^^^^^ + +Automatically sets the member's value to its name:: + + >>> class AutoNameEnum(Enum): + ... def _generate_next_value_(name, start, count, last_value): + ... return name + ... + >>> class Color(AutoNameEnum): + ... red + ... green + ... blue + ... + >>> Color.green.value == 'green' + True + OrderedEnum ^^^^^^^^^^^ An ordered enumeration that is not based on :class:`IntEnum` and so maintains the normal :class:`Enum` invariants (such as not being comparable to other enumerations):: >>> class OrderedEnum(Enum): ... def __ge__(self, other): @@ -724,55 +815,99 @@ Enum Members (aka instances) The most interesting thing about Enum members is that they are singletons. :class:`EnumMeta` creates them all while it is creating the :class:`Enum` class itself, and then puts a custom :meth:`__new__` in place to ensure that no new ones are ever instantiated by returning only the existing member instances. Finer Points ^^^^^^^^^^^^ -:class:`Enum` members are instances of an :class:`Enum` class, and even -though they are accessible as `EnumClass.member`, they should not be accessed +Enum class signature +~~~~~~~~~~~~~~~~~~~~ + + ``class SomeName(AnEnum, start=None, ignore='staticmethod classmethod property'):`` + +``start`` can be used by a :meth:`_generate_next_value_` to specify a +starting value. + +``ignore`` specifies which names, if any, will not attempt to auto-generate +a new value (they will also be removed from the class body). + + +Supported ``__dunder__`` names +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :attr:`__members__` attribute is only available on the class. + +:meth:`__new__`, if specified, must create and return the enum members; it is +also a very good idea to set the member's :attr:`_value_` appropriately. Once +all the members are created it is no longer used. + + +Supported ``_sunder_`` names +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``_order_`` -- used in Python 2/3 code to ensure member order is consistent [class attribute] + +- ``_name_`` -- name of the member +- ``_value_`` -- value of the member; can be set / modified in ``__new__`` +- ``_missing_`` -- a lookup function used when a value is not found +- ``_generate_next_value_`` -- a function to generate missing values during class creation + + +:meth:`_generate_next_value_` signature +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + ``def _generate_next_value_(name, start, count, last_value):`` + +- ``name`` is the name of the member +- ``start`` is the initital start value (if any) or None +- ``count`` is the number of existing members in the enumeration +- ``last_value`` is the value of the last enum member (if any) or None + + +Enum member type +~~~~~~~~~~~~~~~~ + +``Enum`` members are instances of an ``Enum`` class, and even +though they are accessible as ``EnumClass.member``, they should not be accessed directly from the member as that lookup may fail or, worse, return something -besides the :class:`Enum` member you looking for:: +besides the ``Enum`` member you are looking for:: >>> class FieldTypes(Enum): ... name = 0 ... value = 1 ... size = 2 ... >>> FieldTypes.value.size >>> FieldTypes.size.value 2 .. versionchanged:: 3.5 -Boolean evaluation: Enum classes that are mixed with non-Enum types (such as + +Boolean value of ``Enum`` classes and members +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enum classes that are mixed with non-Enum types (such as :class:`int`, :class:`str`, etc.) are evaluated according to the mixed-in -type's rules; otherwise, all members evaluate as ``True``. To make your own +type's rules; otherwise, all members evaluate as :data:`True`. To make your own Enum's boolean evaluation depend on the member's value add the following to your class:: def __bool__(self): return bool(self.value) -The :attr:`__members__` attribute is only available on the class. -If you give your :class:`Enum` subclass extra methods, like the `Planet`_ +Enum classes with methods +~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you give your ``Enum`` subclass extra methods, like the `Planet`_ class above, those methods will show up in a :func:`dir` of the member, but not of the class:: >>> dir(Planet) ['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', 'VENUS', '__class__', '__doc__', '__members__', '__module__'] >>> dir(Planet.EARTH) ['__class__', '__doc__', '__module__', 'name', 'surface_gravity', 'value'] - -The :meth:`__new__` method will only be used for the creation of the -:class:`Enum` members -- after that it is replaced. Any custom :meth:`__new__` -method must create the object and set the :attr:`_value_` attribute -appropriately. - -If you wish to change how :class:`Enum` members are looked up you should either -write a helper function or a :func:`classmethod` for the :class:`Enum` -subclass. diff --git a/Lib/enum.py b/Lib/enum.py --- a/Lib/enum.py +++ b/Lib/enum.py @@ -1,21 +1,23 @@ import sys from types import MappingProxyType, DynamicClassAttribute # try _collections first to reduce startup cost try: from _collections import OrderedDict except ImportError: from collections import OrderedDict -__all__ = ['EnumMeta', 'Enum', 'IntEnum', 'unique'] +__all__ = [ + 'EnumMeta', 'Enum', 'IntEnum', 'AutoEnum', 'unique', + ] 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__')) @@ -45,76 +47,164 @@ def _make_class_unpicklable(cls): class _EnumDict(dict): """Track enum member order and ensure member names are not reused. EnumMeta will use the names found in self._member_names as the enumeration member names. """ def __init__(self): super().__init__() + # list of enum members self._member_names = [] + # starting value + self._start = None + # last assigned value + self._last_value = None + # when the magic turns off + self._locked = True + # list of temporary names + self._ignore = [] + + def __getitem__(self, key): + if ( + self._generate_next_value_ is None + or 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) + next_value = self._generate_next_value_(key, self._start, len(self._member_names), self._last_value) + self[key] = next_value + return next_value def __setitem__(self, key, value): """Changes anything not dundered or not a descriptor. If an enum member name is used twice, an error is raised; duplicate values are not checked for. Single underscore (sunder) names are reserved. """ if _is_sunder(key): - raise ValueError('_names_ are reserved for future Enum use') + if key not in ('_settings_', '_order_', '_ignore_', '_start_', '_generate_next_value_'): + raise ValueError('_names_ are reserved for future Enum use') + elif key == '_generate_next_value_': + if isinstance(value, staticmethod): + value = value.__get__(None, self) + self._generate_next_value_ = value + self._locked = False + elif key == '_ignore_': + if isinstance(value, str): + value = value.split() + else: + value = list(value) + self._ignore = value + already = set(value) & set(self._member_names) + if already: + raise ValueError( + '_ignore_ cannot specify already set names: %r' + % (already, )) + elif key == '_start_': + self._start = value + self._locked = False elif _is_dunder(key): - pass + if key == '__order__': + key = '_order_' + if _is_descriptor(value): + self._locked = True elif key in self._member_names: # descriptor overwriting an enum? raise TypeError('Attempted to reuse key: %r' % key) + elif key in self._ignore: + pass elif not _is_descriptor(value): if key in self: # enum overwriting a descriptor? - raise TypeError('Key already defined as: %r' % self[key]) + raise TypeError('%r already defined as: %r' % (key, self[key])) self._member_names.append(key) + if self._generate_next_value_ is not None: + self._last_value = value + else: + # not a new member, turn off the autoassign magic + self._locked = True super().__setitem__(key, value) + # for magic "auto values" an Enum class should specify a `_generate_next_value_` + # method; that method will be used to generate missing values, and is + # implicitly a staticmethod; + # the signature should be `def _generate_next_value_(name, last_value)` + # last_value will be the last value created and/or assigned, or None + _generate_next_value_ = None # Dummy value for Enum as EnumMeta explicitly checks for it, but of course # until EnumMeta finishes running the first time the Enum class doesn't exist. # This is also why there are checks in EnumMeta like `if Enum is not None` Enum = None - +_ignore_sentinel = object() class EnumMeta(type): """Metaclass for Enum""" @classmethod - def __prepare__(metacls, cls, bases): - return _EnumDict() + def __prepare__(metacls, cls, bases, start=None, ignore=_ignore_sentinel): + # create the namespace dict + enum_dict = _EnumDict() + # inherit previous flags and _generate_next_value_ function + member_type, first_enum = metacls._get_mixins_(bases) + if first_enum is not None: + enum_dict['_generate_next_value_'] = getattr(first_enum, '_generate_next_value_', None) + if start is None: + start = getattr(first_enum, '_start_', None) + if ignore is _ignore_sentinel: + enum_dict['_ignore_'] = 'property classmethod staticmethod'.split() + elif ignore: + enum_dict['_ignore_'] = ignore + if start is not None: + enum_dict['_start_'] = start + return enum_dict - def __new__(metacls, cls, bases, classdict): + def __init__(cls, *args , **kwds): + super(EnumMeta, cls).__init__(*args) + + def __new__(metacls, cls, bases, classdict, **kwds): # an Enum class is final once enumeration items have been defined; it # cannot be mixed with other types (int, float, etc.) if it has an # inherited __new__ unless a new __new__ is defined (or the resulting # class will fail). member_type, first_enum = metacls._get_mixins_(bases) __new__, save_new, use_args = metacls._find_new_(classdict, member_type, first_enum) # save enum items into separate mapping so they don't get baked into # the new class - members = {k: classdict[k] for k in classdict._member_names} + enum_members = {k: classdict[k] for k in classdict._member_names} for name in classdict._member_names: del classdict[name] + # adjust the sunders + _order_ = classdict.pop('_order_', None) + classdict.pop('_ignore_', None) + + # py3 support for definition order (helps keep py2/py3 code in sync) + if _order_ is not None: + if isinstance(_order_, str): + _order_ = _order_.replace(',', ' ').split() + unique_members = [n for n in clsdict._member_names if n in _order_] + if _order_ != unique_members: + raise TypeError('member order does not match _order_') + # check for illegal enum names (any others?) - invalid_names = set(members) & {'mro', } + invalid_names = set(enum_members) & {'mro', } if invalid_names: raise ValueError('Invalid enum member name: {0}'.format( ','.join(invalid_names))) # create a default docstring if one has not been provided if '__doc__' not in classdict: classdict['__doc__'] = 'An enumeration.' # create our new Enum type enum_class = super().__new__(metacls, cls, bases, classdict) @@ -144,35 +234,38 @@ class EnumMeta(type): methods = ('__getnewargs_ex__', '__getnewargs__', '__reduce_ex__', '__reduce__') if not any(m in member_type.__dict__ for m in methods): _make_class_unpicklable(enum_class) # instantiate them, checking for duplicates as we go # we instantiate first instead of checking for duplicates first in case # a custom __new__ is doing something funky with the values -- such as # auto-numbering ;) for member_name in classdict._member_names: - value = members[member_name] + value = enum_members[member_name] if not isinstance(value, tuple): args = (value, ) else: args = value if member_type is tuple: # special case for tuple enums args = (args, ) # wrap it one more time if not use_args: enum_member = __new__(enum_class) if not hasattr(enum_member, '_value_'): enum_member._value_ = value else: enum_member = __new__(enum_class, *args) if not hasattr(enum_member, '_value_'): - enum_member._value_ = member_type(*args) + if member_type is object: + enum_member._value_ = value + else: + enum_member._value_ = member_type(*args) value = enum_member._value_ enum_member._name_ = member_name enum_member.__objclass__ = enum_class enum_member.__init__(*args) # If another member with the same value was already defined, the # new member becomes an alias to the existing one. for name, canonical_member in enum_class._member_map_.items(): if canonical_member._value_ == enum_member._value_: enum_member = canonical_member break @@ -565,20 +658,36 @@ class Enum(metaclass=EnumMeta): return cls class IntEnum(int, Enum): """Enum where members are also (and must be) ints""" def _reduce_ex_by_name(self, proto): return self.name +class AutoEnum(Enum): + """Enum where values are automatically assigned.""" + def _generate_next_value_(name, start, count, last_value): + """ + 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 + """ + # add one to the last assigned value + if not count: + return start if start is not None else 1 + return last_value + 1 + def unique(enumeration): """Class decorator for enumerations ensuring unique member values.""" duplicates = [] for name, member in enumeration.__members__.items(): if name != member.name: duplicates.append((name, member.name)) if duplicates: alias_details = ', '.join( ["%s -> %s" % (alias, name) for (alias, name) in duplicates]) raise ValueError('duplicate values found in %r: %s' % diff --git a/Lib/test/test_enum.py b/Lib/test/test_enum.py --- a/Lib/test/test_enum.py +++ b/Lib/test/test_enum.py @@ -1,16 +1,16 @@ import enum import inspect import pydoc import unittest from collections import OrderedDict -from enum import Enum, IntEnum, EnumMeta, unique +from enum import EnumMeta, Enum, IntEnum, AutoEnum, unique from io import StringIO from pickle import dumps, loads, PicklingError, HIGHEST_PROTOCOL from test import support # for pickle tests try: class Stooges(Enum): LARRY = 1 CURLY = 2 MOE = 3 @@ -1563,20 +1563,342 @@ class TestEnum(unittest.TestCase): return obj class LabelledList(LabelledIntEnum): unprocessed = (1, "Unprocessed") payment_complete = (2, "Payment Complete") self.assertEqual(list(LabelledList), [LabelledList.unprocessed, LabelledList.payment_complete]) self.assertEqual(LabelledList.unprocessed, 1) self.assertEqual(LabelledList(1), LabelledList.unprocessed) + def test_ignore_as_str(self): + from datetime import timedelta + class Period(Enum, ignore='Period i'): + """ + different lengths of time + """ + def __new__(cls, value, period): + obj = object.__new__(cls) + obj._value_ = value + obj.period = period + return obj + Period = vars() + for i in range(367): + Period['Day%d' % i] = timedelta(days=i), 'day' + for i in range(53): + Period['Week%d' % i] = timedelta(days=i*7), 'week' + for i in range(13): + Period['Month%d' % i] = i, 'month' + OneDay = Day1 + OneWeek = Week1 + self.assertEqual(Period.Day7.value, timedelta(days=7)) + self.assertEqual(Period.Day7.period, 'day') + + def test_ignore_as_list(self): + from datetime import timedelta + class Period(Enum, ignore=['Period', 'i']): + """ + different lengths of time + """ + def __new__(cls, value, period): + obj = object.__new__(cls) + obj._value_ = value + obj.period = period + return obj + Period = vars() + for i in range(367): + Period['Day%d' % i] = timedelta(days=i), 'day' + for i in range(53): + Period['Week%d' % i] = timedelta(days=i*7), 'week' + for i in range(13): + Period['Month%d' % i] = i, 'month' + OneDay = Day1 + OneWeek = Week1 + self.assertEqual(Period.Day7.value, timedelta(days=7)) + self.assertEqual(Period.Day7.period, 'day') + + def test_new_with_no_value_and_int_base_class(self): + class NoValue(int, Enum): + def __new__(cls, value): + obj = int.__new__(cls, value) + obj.index = len(cls.__members__) + return obj + this = 1 + that = 2 + self.assertEqual(list(NoValue), [NoValue.this, NoValue.that]) + self.assertEqual(NoValue.this, 1) + self.assertEqual(NoValue.this.value, 1) + self.assertEqual(NoValue.this.index, 0) + self.assertEqual(NoValue.that, 2) + self.assertEqual(NoValue.that.value, 2) + self.assertEqual(NoValue.that.index, 1) + + def test_new_with_no_value(self): + class NoValue(Enum): + def __new__(cls, value): + obj = object.__new__(cls) + obj.index = len(cls.__members__) + return obj + this = 1 + that = 2 + self.assertEqual(list(NoValue), [NoValue.this, NoValue.that]) + self.assertEqual(NoValue.this.value, 1) + self.assertEqual(NoValue.this.index, 0) + self.assertEqual(NoValue.that.value, 2) + self.assertEqual(NoValue.that.index, 1) + + +class TestAutoNumber(unittest.TestCase): + + def test_autonumbering(self): + class Color(AutoEnum): + red + green + blue + self.assertEqual(list(Color), [Color.red, Color.green, Color.blue]) + self.assertEqual(Color.red.value, 1) + self.assertEqual(Color.green.value, 2) + self.assertEqual(Color.blue.value, 3) + + def test_autointnumbering(self): + class Color(int, AutoEnum): + red + green + blue + self.assertTrue(isinstance(Color.red, int)) + self.assertEqual(Color.green, 2) + self.assertTrue(Color.blue > Color.red) + + def test_autonumbering_with_start(self): + class Color(AutoEnum, start=7): + red + green + blue + self.assertEqual(list(Color), [Color.red, Color.green, Color.blue]) + self.assertEqual(Color.red.value, 7) + self.assertEqual(Color.green.value, 8) + self.assertEqual(Color.blue.value, 9) + + def test_autonumbering_with_start_and_skip(self): + class Color(AutoEnum, start=7): + red + green + blue = 11 + brown + self.assertEqual(list(Color), [Color.red, Color.green, Color.blue, Color.brown]) + self.assertEqual(Color.red.value, 7) + self.assertEqual(Color.green.value, 8) + self.assertEqual(Color.blue.value, 11) + self.assertEqual(Color.brown.value, 12) + + + def test_badly_overridden_ignore(self): + with self.assertRaisesRegex(TypeError, "'int' object is not callable"): + class Color(AutoEnum): + _ignore_ = () + red + green + blue + @property + def whatever(self): + pass + with self.assertRaisesRegex(TypeError, "'int' object is not callable"): + class Color(AutoEnum, ignore=None): + red + green + blue + @property + def whatever(self): + pass + with self.assertRaisesRegex(TypeError, "'int' object is not callable"): + class Color(AutoEnum, ignore='classmethod staticmethod'): + red + green + blue + @property + def whatever(self): + pass + + def test_property(self): + class Color(AutoEnum): + red + green + blue + @property + def cap_name(self): + return self.name.title() + self.assertEqual(Color.blue.cap_name, 'Blue') + + def test_magic_turns_off(self): + with self.assertRaisesRegex(NameError, "brown"): + class Color(AutoEnum): + red + green + blue + @property + def cap_name(self): + return self.name.title() + brown + + with self.assertRaisesRegex(NameError, "rose"): + class Color(AutoEnum): + red + green + blue + def hello(self): + print('Hello! My serial is %s.' % self.value) + rose + + with self.assertRaisesRegex(NameError, "cyan"): + class Color(AutoEnum): + red + green + blue + def __init__(self, *args): + pass + cyan + + +class TestGenerateMethod(unittest.TestCase): + + def test_autonaming(self): + class Color(Enum): + def _generate_next_value_(name, start, count, last_value): + return name + Red + Green + Blue + self.assertEqual(list(Color), [Color.Red, Color.Green, Color.Blue]) + self.assertEqual(Color.Red.value, 'Red') + self.assertEqual(Color.Green.value, 'Green') + self.assertEqual(Color.Blue.value, 'Blue') + + def test_autonamestr(self): + class Color(str, Enum): + def _generate_next_value_(name, start, count, last_value): + return name + Red + Green + Blue + self.assertTrue(isinstance(Color.Red, str)) + self.assertEqual(Color.Green, 'Green') + self.assertTrue(Color.Blue < Color.Red) + + def test_generate_as_staticmethod(self): + class Color(str, Enum): + @staticmethod + def _generate_next_value_(name, start, count, last_value): + return name.lower() + Red + Green + Blue + self.assertTrue(isinstance(Color.Red, str)) + self.assertEqual(Color.Green, 'green') + self.assertTrue(Color.Blue < Color.Red) + + + def test_overridden_ignore(self): + with self.assertRaisesRegex(TypeError, "'str' object is not callable"): + class Color(Enum): + def _generate_next_value_(name, start, count, last_value): + return name + _ignore_ = () + red + green + blue + @property + def whatever(self): + pass + with self.assertRaisesRegex(TypeError, "'str' object is not callable"): + class Color(Enum, ignore=None): + def _generate_next_value_(name, start, count, last_value): + return name + red + green + blue + @property + def whatever(self): + pass + + def test_property(self): + class Color(Enum): + def _generate_next_value_(name, start, count, last_value): + return name + red + green + blue + @property + def upper_name(self): + return self.name.upper() + self.assertEqual(Color.blue.upper_name, 'BLUE') + + def test_magic_turns_off(self): + with self.assertRaisesRegex(NameError, "brown"): + class Color(Enum): + def _generate_next_value_(name, start, count, last_value): + return name + red + green + blue + @property + def cap_name(self): + return self.name.title() + brown + + with self.assertRaisesRegex(NameError, "rose"): + class Color(Enum): + def _generate_next_value_(name, start, count, last_value): + return name + red + green + blue + def hello(self): + print('Hello! My value %s.' % self.value) + rose + + with self.assertRaisesRegex(NameError, "cyan"): + class Color(Enum): + def _generate_next_value_(name, start, count, last_value): + return name + red + green + blue + def __init__(self, *args): + pass + cyan + + def test_powers_of_two(self): + class Bits(Enum): + def _generate_next_value_(name, start, count, last_value): + return 2 ** count + one + two + four + eight + self.assertEqual(Bits.one.value, 1) + self.assertEqual(Bits.two.value, 2) + self.assertEqual(Bits.four.value, 4) + self.assertEqual(Bits.eight.value, 8) + + def test_powers_of_two_as_int(self): + class Bits(int, Enum): + def _generate_next_value_(name, start, count, last_value): + return 2 ** count + one + two + four + eight + self.assertEqual(Bits.one, 1) + self.assertEqual(Bits.two, 2) + self.assertEqual(Bits.four, 4) + self.assertEqual(Bits.eight, 8) + class TestUnique(unittest.TestCase): def test_unique_clean(self): @unique class Clean(Enum): one = 1 two = 'dos' tres = 4.0 @unique diff --git a/Misc/NEWS b/Misc/NEWS --- a/Misc/NEWS +++ b/Misc/NEWS @@ -64,20 +64,22 @@ Library - Issue #27533: Release GIL in nt._isdir - Issue #17711: Fixed unpickling by the persistent ID with protocol 0. Original patch by Alexandre Vassalotti. - Issue #27522: Avoid an unintentional reference cycle in email.feedparser. - Issue 27512: Fix a segfault when os.fspath() called a an __fspath__() method that raised an exception. Patch by Xiang Zhang. +- Issue 26988: Add AutoEnum. + Tests ----- - Issue #27472: Add test.support.unix_shell as the path to the default shell. - Issue #27369: In test_pyexpat, avoid testing an error message detail that changed in Expat 2.2.0. Windows -------