[3.10] bpo-44559: [Enum] revert enum module to 3.9 (GH-27010)
* [Enum] revert enum module to 3.9
diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst
index d3df151b..e8e4942 100644
--- a/Doc/library/enum.rst
+++ b/Doc/library/enum.rst
@@ -13,722 +13,1190 @@
**Source code:** :source:`Lib/enum.py`
-.. sidebar:: Important
+----------------
- This page contains the API reference information. For tutorial
- information and discussion of more advanced topics, see
+An enumeration is a set of symbolic names (members) bound to unique,
+constant values. Within an enumeration, the members can be compared
+by identity, and the enumeration itself can be iterated over.
- * :ref:`Basic Tutorial <enum-basic-tutorial>`
- * :ref:`Advanced Tutorial <enum-advanced-tutorial>`
- * :ref:`Enum Cookbook <enum-cookbook>`
+.. note:: Case of Enum Members
----------------
+ Because Enums are used to represent constants we recommend using
+ UPPER_CASE names for enum members, and will be using that style
+ in our examples.
-An enumeration:
-
-* is a set of symbolic names (members) bound to unique values
-* can be iterated over to return its members in definition order
-* uses *call* syntax to return members by value
-* uses *index* syntax to return members by name
-
-Enumerations are created either by using the :keyword:`class` syntax, or by
-using function-call syntax::
-
- >>> from enum import Enum
-
- >>> # class syntax
- >>> class Color(Enum):
- ... RED = 1
- ... GREEN = 2
- ... BLUE = 3
-
- >>> # functional syntax
- >>> Color = Enum('Color', ['RED', 'GREEN', 'BLUE'])
-
-Even though we can use the :keyword:`class` syntax to create Enums, Enums
-are not normal Python classes. See
-:ref:`How are Enums different? <enum-class-differences>` for more details.
-
-.. 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*) and are functionally constants.
- - The enum members have *names* and *values* (the name of
- :attr:`Color.RED` is ``RED``, the value of :attr:`Color.BLUE` is
- ``3``, etc.)
-
----------------
Module Contents
---------------
- :class:`EnumType`
-
- The ``type`` for Enum and its subclasses.
-
- :class:`Enum`
-
- Base class for creating enumerated constants.
-
- :class:`IntEnum`
-
- Base class for creating enumerated constants that are also
- subclasses of :class:`int`. (`Notes`_)
-
- :class:`StrEnum`
-
- Base class for creating enumerated constants that are also
- subclasses of :class:`str`. (`Notes`_)
-
- :class:`Flag`
-
- Base class for creating enumerated constants that can be combined using
- the bitwise operations without losing their :class:`Flag` membership.
-
- :class:`IntFlag`
-
- Base class for creating enumerated constants that can be combined using
- the bitwise operators without losing their :class:`IntFlag` membership.
- :class:`IntFlag` members are also subclasses of :class:`int`. (`Notes`_)
-
- :class:`EnumCheck`
-
- An enumeration with the values ``CONTINUOUS``, ``NAMED_FLAGS``, and
- ``UNIQUE``, for use with :func:`verify` to ensure various constraints
- are met by a given enumeration.
-
- :class:`FlagBoundary`
-
- An enumeration with the values ``STRICT``, ``CONFORM``, ``EJECT``, and
- ``KEEP`` which allows for more fine-grained control over how invalid values
- are dealt with in an enumeration.
-
- :class:`auto`
-
- Instances are replaced with an appropriate value for Enum members.
- :class:`StrEnum` defaults to the lower-cased version of the member name,
- while other Enums default to 1 and increase from there.
-
- :func:`global_enum`
-
- :class:`Enum` class decorator to apply the appropriate global `__repr__`,
- and export its members into the global name space.
-
- :func:`.property`
-
- Allows :class:`Enum` members to have attributes without conflicting with
- other members' names.
-
- :func:`unique`
-
- Enum class decorator that ensures only one name is bound to any one value.
-
- :func:`verify`
-
- Enum class decorator that checks user-selectable constraints on an
- enumeration.
-
-
-.. versionadded:: 3.6 ``Flag``, ``IntFlag``, ``auto``
-.. versionadded:: 3.10 ``StrEnum``, ``EnumCheck``, ``FlagBoundary``
-
----------------
-
-Data Types
-----------
-
-
-.. class:: EnumType
-
- *EnumType* is the :term:`metaclass` for *enum* enumerations. It is possible
- to subclass *EnumType* -- see :ref:`Subclassing EnumType <enumtype-examples>`
- for details.
-
- .. method:: EnumType.__contains__(cls, member)
-
- Returns ``True`` if member belongs to the ``cls``::
-
- >>> some_var = Color.RED
- >>> some_var in Color
- True
-
- .. note::
-
- In Python 3.12 it will be possible to check for member values and not
- just members; until then, a ``TypeError`` will be raised if a
- non-Enum-member is used in a containment check.
-
- .. method:: EnumType.__dir__(cls)
-
- Returns ``['__class__', '__doc__', '__members__', '__module__']`` and the
- names of the members in *cls*::
-
- >>> dir(Color)
- ['BLUE', 'GREEN', 'RED', '__class__', '__doc__', '__members__', '__module__']
-
- .. method:: EnumType.__getattr__(cls, name)
-
- Returns the Enum member in *cls* matching *name*, or raises an :exc:`AttributeError`::
-
- >>> Color.GREEN
- Color.GREEN
-
- .. method:: EnumType.__getitem__(cls, name)
-
- Returns the Enum member in *cls* matching *name*, or raises an :exc:`KeyError`::
-
- >>> Color['BLUE']
- Color.BLUE
-
- .. method:: EnumType.__iter__(cls)
-
- Returns each member in *cls* in definition order::
-
- >>> list(Color)
- [Color.RED, Color.GREEN, Color.BLUE]
-
- .. method:: EnumType.__len__(cls)
-
- Returns the number of member in *cls*::
-
- >>> len(Color)
- 3
-
- .. method:: EnumType.__reversed__(cls)
-
- Returns each member in *cls* in reverse definition order::
-
- >>> list(reversed(Color))
- [Color.BLUE, Color.GREEN, Color.RED]
-
+This module defines four enumeration classes that can be used to define unique
+sets of names and values: :class:`Enum`, :class:`IntEnum`, :class:`Flag`, and
+:class:`IntFlag`. It also defines one decorator, :func:`unique`, and one
+helper, :class:`auto`.
.. class:: Enum
- *Enum* is the base class for all *enum* enumerations.
-
- .. attribute:: Enum.name
-
- The name used to define the ``Enum`` member::
-
- >>> Color.BLUE.name
- 'BLUE'
-
- .. attribute:: Enum.value
-
- The value given to the ``Enum`` member::
-
- >>> Color.RED.value
- 1
-
- .. note:: Enum member values
-
- Member values can be anything: :class:`int`, :class:`str`, etc.. If
- the exact value is unimportant you may use :class:`auto` instances and an
- appropriate value will be chosen for you. Care must be taken if you mix
- :class:`auto` with other values.
-
- .. attribute:: Enum._ignore_
-
- ``_ignore_`` is only used during creation and is removed from the
- enumeration once that is complete.
-
- ``_ignore_`` is a list of names that will not become members, and whose
- names will also be removed from the completed enumeration. See
- :ref:`TimePeriod <enum-time-period>` for an example.
-
- .. method:: Enum.__call__(cls, value, names=None, \*, module=None, qualname=None, type=None, start=1, boundary=None)
-
- This method is called in two different ways:
-
- * to look up an existing member:
-
- :cls: The enum class being called.
- :value: The value to lookup.
-
- * to use the ``cls`` enum to create a new enum:
-
- :cls: The enum class being called.
- :value: The name of the new Enum to create.
- :names: The names/values of the members for the new Enum.
- :module: The name of the module the new Enum is created in.
- :qualname: The actual location in the module where this Enum can be found.
- :type: A mix-in type for the new Enum.
- :start: The first integer value for the Enum (used by :class:`auto`)
- :boundary: How to handle out-of-range values from bit operations (:class:`Flag` only)
-
- .. method:: Enum.__dir__(self)
-
- Returns ``['__class__', '__doc__', '__module__', 'name', 'value']`` and
- any public methods defined on *self.__class__*::
-
- >>> from datetime import date
- >>> class Weekday(Enum):
- ... MONDAY = 1
- ... TUESDAY = 2
- ... WEDNESDAY = 3
- ... THURSDAY = 4
- ... FRIDAY = 5
- ... SATURDAY = 6
- ... SUNDAY = 7
- ... @classmethod
- ... def today(cls):
- ... print('today is %s' % cls(date.today.isoweekday).naem)
- >>> dir(Weekday.SATURDAY)
- ['__class__', '__doc__', '__module__', 'name', 'today', 'value']
-
- .. method:: Enum._generate_next_value_(name, start, count, last_values)
-
- :name: The name of the member being defined (e.g. 'RED').
- :start: The start value for the Enum; the default is 1.
- :count: The number of members currently defined, not including this one.
- :last_values: A list of the previous values.
-
- A *staticmethod* that is used to determine the next value returned by
- :class:`auto`::
-
- >>> from enum import auto
- >>> class PowersOfThree(Enum):
- ... @staticmethod
- ... def _generate_next_value_(name, start, count, last_values):
- ... return (count + 1) * 3
- ... FIRST = auto()
- ... SECOND = auto()
- >>> PowersOfThree.SECOND.value
- 6
-
- .. method:: Enum._missing_(cls, value)
-
- A *classmethod* for looking up values not found in *cls*. By default it
- does nothing, but can be overridden to implement custom search behavior::
-
- >>> from enum import StrEnum
- >>> class Build(StrEnum):
- ... DEBUG = auto()
- ... OPTIMIZED = auto()
- ... @classmethod
- ... def _missing_(cls, value):
- ... value = value.lower()
- ... for member in cls:
- ... if member.value == value:
- ... return member
- ... return None
- >>> Build.DEBUG.value
- 'debug'
- >>> Build('deBUG')
- Build.DEBUG
-
- .. method:: Enum.__repr__(self)
-
- Returns the string used for *repr()* calls. By default, returns the
- *Enum* name and the member name, but can be overridden::
-
- >>> class OldStyle(Enum):
- ... RETRO = auto()
- ... OLD_SCHOOl = auto()
- ... YESTERYEAR = auto()
- ... def __repr__(self):
- ... cls_name = self.__class__.__name__
- ... return f'<{cls_name}.{self.name}: {self.value}>'
- >>> OldStyle.RETRO
- <OldStyle.RETRO: 1>
-
- .. method:: Enum.__str__(self)
-
- Returns the string used for *str()* calls. By default, returns the
- member name, but can be overridden::
-
- >>> class OldStyle(Enum):
- ... RETRO = auto()
- ... OLD_SCHOOl = auto()
- ... YESTERYEAR = auto()
- ... def __str__(self):
- ... cls_name = self.__class__.__name__
- ... return f'{cls_name}.{self.name}'
- >>> OldStyle.RETRO
- OldStyle.RETRO
-
-.. note::
-
- Using :class:`auto` with :class:`Enum` results in integers of increasing value,
- starting with ``1``.
-
+ Base class for creating enumerated constants. See section
+ `Functional API`_ for an alternate construction syntax.
.. class:: IntEnum
- *IntEnum* is the same as *Enum*, but its members are also integers and can be
- used anywhere that an integer can be used. If any integer operation is performed
- with an *IntEnum* member, the resulting value loses its enumeration status.
-
- >>> from enum import IntEnum
- >>> class Numbers(IntEnum):
- ... ONE = 1
- ... TWO = 2
- ... THREE = 3
- >>> Numbers.THREE
- Numbers.THREE
- >>> Numbers.ONE + Numbers.TWO
- 3
- >>> Numbers.THREE + 5
- 8
- >>> Numbers.THREE == 3
- True
-
-.. note::
-
- Using :class:`auto` with :class:`IntEnum` results in integers of increasing value,
- starting with ``1``.
-
-
-.. class:: StrEnum
-
- *StrEnum* is the same as *Enum*, but its members are also strings and can be used
- in most of the same places that a string can be used. The result of any string
- operation performed on or with a *StrEnum* member is not part of the enumeration.
-
- .. note:: There are places in the stdlib that check for an exact :class:`str`
- instead of a :class:`str` subclass (i.e. ``type(unknown) == str``
- instead of ``isinstance(str, unknown)``), and in those locations you
- will need to use ``str(StrEnum.member)``.
-
-
-.. note::
-
- Using :class:`auto` with :class:`StrEnum` results in values of the member name,
- lower-cased.
-
-
-.. class:: Flag
-
- *Flag* members support the bitwise operators ``&`` (*AND*), ``|`` (*OR*),
- ``^`` (*XOR*), and ``~`` (*INVERT*); the results of those operators are members
- of the enumeration.
-
- .. method:: __contains__(self, value)
-
- Returns *True* if value is in self::
-
- >>> from enum import Flag, auto
- >>> class Color(Flag):
- ... RED = auto()
- ... GREEN = auto()
- ... BLUE = auto()
- >>> purple = Color.RED | Color.BLUE
- >>> white = Color.RED | Color.GREEN | Color.BLUE
- >>> Color.GREEN in purple
- False
- >>> Color.GREEN in white
- True
- >>> purple in white
- True
- >>> white in purple
- False
-
- .. method:: __iter__(self):
-
- Returns all contained members::
-
- >>> list(Color.RED)
- [Color.RED]
- >>> list(purple)
- [Color.RED, Color.BLUE]
-
- .. method:: __len__(self):
-
- Returns number of members in flag::
-
- >>> len(Color.GREEN)
- 1
- >>> len(white)
- 3
-
- .. method:: __bool__(self):
-
- Returns *True* if any members in flag, *False* otherwise::
-
- >>> bool(Color.GREEN)
- True
- >>> bool(white)
- True
- >>> black = Color(0)
- >>> bool(black)
- False
-
- .. method:: __or__(self, other)
-
- Returns current flag binary or'ed with other::
-
- >>> Color.RED | Color.GREEN
- Color.RED|Color.GREEN
-
- .. method:: __and__(self, other)
-
- Returns current flag binary and'ed with other::
-
- >>> purple & white
- Color.RED|Color.BLUE
- >>> purple & Color.GREEN
- 0x0
-
- .. method:: __xor__(self, other)
-
- Returns current flag binary xor'ed with other::
-
- >>> purple ^ white
- Color.GREEN
- >>> purple ^ Color.GREEN
- Color.RED|Color.GREEN|Color.BLUE
-
- .. method:: __invert__(self):
-
- Returns all the flags in *type(self)* that are not in self::
-
- >>> ~white
- 0x0
- >>> ~purple
- Color.GREEN
- >>> ~Color.RED
- Color.GREEN|Color.BLUE
-
-.. note::
-
- Using :class:`auto` with :class:`Flag` results in integers that are powers
- of two, starting with ``1``.
-
+ Base class for creating enumerated constants that are also
+ subclasses of :class:`int`.
.. class:: IntFlag
- *IntFlag* is the same as *Flag*, but its members are also integers and can be
- used anywhere that an integer can be used.
+ Base class for creating enumerated constants that can be combined using
+ the bitwise operators without losing their :class:`IntFlag` membership.
+ :class:`IntFlag` members are also subclasses of :class:`int`.
- >>> from enum import IntFlag, auto
- >>> class Color(IntFlag):
- ... RED = auto()
- ... GREEN = auto()
- ... BLUE = auto()
- >>> Color.RED & 2
- 0x0
- >>> Color.RED | 2
- Color.RED|Color.GREEN
+.. class:: Flag
- If any integer operation is performed with an *IntFlag* member, the result is
- not an *IntFlag*::
+ Base class for creating enumerated constants that can be combined using
+ the bitwise operations without losing their :class:`Flag` membership.
- >>> Color.RED + 2
- 3
+.. function:: unique
+ :noindex:
- If a *Flag* operation is performed with an *IntFlag* member and:
-
- * the result is a valid *IntFlag*: an *IntFlag* is returned
- * the result is not a valid *IntFlag*: the result depends on the *FlagBoundary* setting
-
-.. note::
-
- Using :class:`auto` with :class:`IntFlag` results in integers that are powers
- of two, starting with ``1``.
-
-.. class:: EnumCheck
-
- *EnumCheck* contains the options used by the :func:`verify` decorator to ensure
- various constraints; failed constraints result in a :exc:`TypeError`.
-
- .. attribute:: UNIQUE
-
- Ensure that each value has only one name::
-
- >>> from enum import Enum, verify, UNIQUE
- >>> @verify(UNIQUE)
- ... class Color(Enum):
- ... RED = 1
- ... GREEN = 2
- ... BLUE = 3
- ... CRIMSON = 1
- Traceback (most recent call last):
- ...
- ValueError: aliases found in <enum 'Color'>: CRIMSON -> RED
-
-
- .. attribute:: CONTINUOUS
-
- Ensure that there are no missing values between the lowest-valued member
- and the highest-valued member::
-
- >>> from enum import Enum, verify, CONTINUOUS
- >>> @verify(CONTINUOUS)
- ... class Color(Enum):
- ... RED = 1
- ... GREEN = 2
- ... BLUE = 5
- Traceback (most recent call last):
- ...
- ValueError: invalid enum 'Color': missing values 3, 4
-
- .. attribute:: NAMED_FLAGS
-
- Ensure that any flag groups/masks contain only named flags -- useful when
- values are specified instead of being generated by :func:`auto`
-
- >>> from enum import Flag, verify, NAMED_FLAGS
- >>> @verify(NAMED_FLAGS)
- ... class Color(Flag):
- ... RED = 1
- ... GREEN = 2
- ... BLUE = 4
- ... WHITE = 15
- ... NEON = 31
- Traceback (most recent call last):
- ...
- ValueError: invalid Flag 'Color': aliases WHITE and NEON are missing combined values of 0x18 [use enum.show_flag_values(value) for details]
-
-.. note::
-
- CONTINUOUS and NAMED_FLAGS are designed to work with integer-valued members.
-
-.. versionadded:: 3.10
-
-.. class:: FlagBoundary
-
- *FlagBoundary* controls how out-of-range values are handled in *Flag* and its
- subclasses.
-
- .. attribute:: STRICT
-
- Out-of-range values cause a :exc:`ValueError` to be raised. This is the
- default for :class:`Flag`::
-
- >>> from enum import Flag, STRICT
- >>> class StrictFlag(Flag, boundary=STRICT):
- ... RED = auto()
- ... GREEN = auto()
- ... BLUE = auto()
- >>> StrictFlag(2**2 + 2**4)
- Traceback (most recent call last):
- ...
- ValueError: StrictFlag: invalid value: 20
- given 0b0 10100
- allowed 0b0 00111
-
- .. attribute:: CONFORM
-
- Out-of-range values have invalid values removed, leaving a valid *Flag*
- value::
-
- >>> from enum import Flag, CONFORM
- >>> class ConformFlag(Flag, boundary=CONFORM):
- ... RED = auto()
- ... GREEN = auto()
- ... BLUE = auto()
- >>> ConformFlag(2**2 + 2**4)
- ConformFlag.BLUE
-
- .. attribute:: EJECT
-
- Out-of-range values lose their *Flag* membership and revert to :class:`int`.
- This is the default for :class:`IntFlag`::
-
- >>> from enum import Flag, EJECT
- >>> class EjectFlag(Flag, boundary=EJECT):
- ... RED = auto()
- ... GREEN = auto()
- ... BLUE = auto()
- >>> EjectFlag(2**2 + 2**4)
- 20
-
- .. attribute:: KEEP
-
- Out-of-range values are kept, and the *Flag* membership is kept. This is
- used for some stdlib flags:
-
- >>> from enum import Flag, KEEP
- >>> class KeepFlag(Flag, boundary=KEEP):
- ... RED = auto()
- ... GREEN = auto()
- ... BLUE = auto()
- >>> KeepFlag(2**2 + 2**4)
- KeepFlag.BLUE|0x10
-
-.. versionadded:: 3.10
-
----------------
-
-Utilites and Decorators
------------------------
+ Enum class decorator that ensures only one name is bound to any one value.
.. class:: auto
- *auto* can be used in place of a value. If used, the *Enum* machinery will
- call an *Enum*'s :meth:`_generate_next_value_` to get an appropriate value.
- For *Enum* and *IntEnum* that appropriate value will be the last value plus
- one; for *Flag* and *IntFlag* it will be the first power-of-two greater
- than the last value; for *StrEnum* it will be the lower-cased version of the
- member's name.
+ Instances are replaced with an appropriate value for Enum members. By default, the initial value starts at 1.
- ``_generate_next_value_`` can be overridden to customize the values used by
- *auto*.
-
-.. decorator:: global_enum
-
- A :keyword:`class` decorator specifically for enumerations. It replaces the
- :meth:`__repr__` method with one that shows *module_name*.*member_name*. It
- also injects the members, and their aliases, into the global namespace they
- were defined in.
+.. versionadded:: 3.6 ``Flag``, ``IntFlag``, ``auto``
-.. decorator:: property
+Creating an Enum
+----------------
- A decorator similar to the built-in *property*, but specifically for
- enumerations. It allows member attributes to have the same names as members
- themselves.
+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::
- .. note:: the *property* and the member must be defined in separate classes;
- for example, the *value* and *name* attributes are defined in the
- *Enum* class, and *Enum* subclasses can define members with the
- names ``value`` and ``name``.
+ >>> from enum import Enum
+ >>> class Color(Enum):
+ ... RED = 1
+ ... GREEN = 2
+ ... BLUE = 3
+ ...
+
+.. note:: Enum member values
+
+ Member values can be anything: :class:`int`, :class:`str`, etc.. If
+ the exact value is unimportant you may use :class:`auto` instances and an
+ appropriate value will be chosen for you. Care must be taken if you mix
+ :class:`auto` with other values.
+
+.. 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*) and are functionally constants.
+ - 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.
+
+Enumeration members have human readable string representations::
+
+ >>> print(Color.RED)
+ Color.RED
+
+...while their ``repr`` has more information::
+
+ >>> print(repr(Color.RED))
+ <Color.RED: 1>
+
+The *type* of an enumeration member is the enumeration it belongs to::
+
+ >>> type(Color.RED)
+ <enum 'Color'>
+ >>> isinstance(Color.GREEN, Color)
+ True
+ >>>
+
+Enum members also have a property that contains just their item name::
+
+ >>> print(Color.RED.name)
+ RED
+
+Enumerations support iteration, in definition order::
+
+ >>> class Shake(Enum):
+ ... VANILLA = 7
+ ... CHOCOLATE = 4
+ ... COOKIES = 9
+ ... MINT = 3
+ ...
+ >>> for shake in Shake:
+ ... print(shake)
+ ...
+ Shake.VANILLA
+ Shake.CHOCOLATE
+ Shake.COOKIES
+ Shake.MINT
+
+Enumeration members are hashable, so they can be used in dictionaries and sets::
+
+ >>> apples = {}
+ >>> apples[Color.RED] = 'red delicious'
+ >>> apples[Color.GREEN] = 'granny smith'
+ >>> apples == {Color.RED: 'red delicious', Color.GREEN: 'granny smith'}
+ True
+
+
+Programmatic access to enumeration members and their attributes
+---------------------------------------------------------------
+
+Sometimes it's useful to access members in enumerations programmatically (i.e.
+situations where ``Color.RED`` won't do because the exact color is not known
+at program-writing time). ``Enum`` allows such access::
+
+ >>> Color(1)
+ <Color.RED: 1>
+ >>> Color(3)
+ <Color.BLUE: 3>
+
+If you want to access enum members by *name*, use item access::
+
+ >>> Color['RED']
+ <Color.RED: 1>
+ >>> Color['GREEN']
+ <Color.GREEN: 2>
+
+If you have an enum member and need its :attr:`name` or :attr:`value`::
+
+ >>> member = Color.RED
+ >>> member.name
+ 'RED'
+ >>> member.value
+ 1
+
+
+Duplicating enum members and values
+-----------------------------------
+
+Having two enum members with the same name is invalid::
+
+ >>> class Shape(Enum):
+ ... SQUARE = 2
+ ... SQUARE = 3
+ ...
+ Traceback (most recent call last):
+ ...
+ TypeError: Attempted to reuse key: 'SQUARE'
+
+However, two enum members are allowed to have the same value. Given two members
+A and B with the same value (and A defined first), B is an alias to A. By-value
+lookup of the value of A and B will return A. By-name lookup of B will also
+return A::
+
+ >>> class Shape(Enum):
+ ... SQUARE = 2
+ ... DIAMOND = 1
+ ... CIRCLE = 3
+ ... ALIAS_FOR_SQUARE = 2
+ ...
+ >>> Shape.SQUARE
+ <Shape.SQUARE: 2>
+ >>> Shape.ALIAS_FOR_SQUARE
+ <Shape.SQUARE: 2>
+ >>> Shape(2)
+ <Shape.SQUARE: 2>
+
+.. note::
+
+ Attempting to create a member with the same name as an already
+ defined attribute (another member, a method, etc.) or attempting to create
+ an attribute with the same name as a member is not allowed.
+
+
+Ensuring unique enumeration values
+----------------------------------
+
+By default, enumerations allow multiple names as aliases for the same value.
+When this behavior isn't desired, the following decorator can be used to
+ensure each value is used only once in the enumeration:
.. decorator:: unique
- A :keyword:`class` decorator specifically for enumerations. It searches an
- enumeration's :attr:`__members__`, gathering any aliases it finds; if any are
- found :exc:`ValueError` is raised with the details::
+A :keyword:`class` decorator specifically for enumerations. It searches an
+enumeration's :attr:`__members__` gathering any aliases it finds; if any are
+found :exc:`ValueError` is raised with the details::
- >>> from enum import Enum, unique
- >>> @unique
- ... class Mistake(Enum):
- ... ONE = 1
- ... TWO = 2
- ... THREE = 3
- ... FOUR = 3
- ...
- Traceback (most recent call last):
- ...
- ValueError: duplicate values found in <enum 'Mistake'>: FOUR -> THREE
+ >>> from enum import Enum, unique
+ >>> @unique
+ ... class Mistake(Enum):
+ ... ONE = 1
+ ... TWO = 2
+ ... THREE = 3
+ ... FOUR = 3
+ ...
+ Traceback (most recent call last):
+ ...
+ ValueError: duplicate values found in <enum 'Mistake'>: FOUR -> THREE
-.. decorator:: verify
- A :keyword:`class` decorator specifically for enumerations. Members from
- :class:`EnumCheck` are used to specify which constraints should be checked
- on the decorated enumeration.
+Using automatic values
+----------------------
-.. versionadded:: 3.10
+If the exact value is unimportant you can use :class:`auto`::
----------------
+ >>> from enum import Enum, auto
+ >>> class Color(Enum):
+ ... RED = auto()
+ ... BLUE = auto()
+ ... GREEN = auto()
+ ...
+ >>> list(Color)
+ [<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]
-Notes
------
+The values are chosen by :func:`_generate_next_value_`, which can be
+overridden::
-:class:`IntEnum`, :class:`StrEnum`, and :class:`IntFlag`
+ >>> class AutoName(Enum):
+ ... def _generate_next_value_(name, start, count, last_values):
+ ... return name
+ ...
+ >>> class Ordinal(AutoName):
+ ... NORTH = auto()
+ ... SOUTH = auto()
+ ... EAST = auto()
+ ... WEST = auto()
+ ...
+ >>> list(Ordinal)
+ [<Ordinal.NORTH: 'NORTH'>, <Ordinal.SOUTH: 'SOUTH'>, <Ordinal.EAST: 'EAST'>, <Ordinal.WEST: 'WEST'>]
- These three enum types are designed to be drop-in replacements for existing
- integer- and string-based values; as such, they have extra limitations:
+.. note::
- - ``format()`` will use the value of the enum member, unless ``__str__``
- has been overridden
+ The goal of the default :meth:`_generate_next_value_` method is to provide
+ the next :class:`int` in sequence with the last :class:`int` provided, but
+ the way it does this is an implementation detail and may change.
- - ``StrEnum.__str__`` uses the value and not the name of the enum member
+.. note::
- If you do not need/want those limitations, you can create your own base
- class by mixing in the ``int`` or ``str`` type yourself::
+ The :meth:`_generate_next_value_` method must be defined before any members.
- >>> from enum import Enum
- >>> class MyIntEnum(int, Enum):
- ... pass
+Iteration
+---------
+
+Iterating over the members of an enum does not provide the aliases::
+
+ >>> list(Shape)
+ [<Shape.SQUARE: 2>, <Shape.DIAMOND: 1>, <Shape.CIRCLE: 3>]
+
+The special attribute ``__members__`` is a read-only ordered mapping of names
+to members. It includes all names defined in the enumeration, including the
+aliases::
+
+ >>> for name, member in Shape.__members__.items():
+ ... name, member
+ ...
+ ('SQUARE', <Shape.SQUARE: 2>)
+ ('DIAMOND', <Shape.DIAMOND: 1>)
+ ('CIRCLE', <Shape.CIRCLE: 3>)
+ ('ALIAS_FOR_SQUARE', <Shape.SQUARE: 2>)
+
+The ``__members__`` attribute can be used for detailed programmatic access to
+the enumeration members. For example, finding all the aliases::
+
+ >>> [name for name, member in Shape.__members__.items() if member.name != name]
+ ['ALIAS_FOR_SQUARE']
+
+
+Comparisons
+-----------
+
+Enumeration members are compared by identity::
+
+ >>> Color.RED is Color.RED
+ True
+ >>> Color.RED is Color.BLUE
+ 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 "<stdin>", line 1, in <module>
+ 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
+
+Comparisons against non-enumeration values will always compare not equal
+(again, :class:`IntEnum` was explicitly designed to behave differently, see
+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.
+
+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
+ ... return self.name, self.value
+ ...
+ ... def __str__(self):
+ ... return 'my custom str! {0}'.format(self.value)
+ ...
+ ... @classmethod
+ ... def favorite_mood(cls):
+ ... # cls here is the enumeration
+ ... return cls.HAPPY
+ ...
+
+Then::
+
+ >>> Mood.favorite_mood()
+ <Mood.HAPPY: 3>
+ >>> Mood.HAPPY.describe()
+ ('HAPPY', 3)
+ >>> str(Mood.FUNKY)
+ 'my custom str! 1'
+
+The rules for what is allowed are as follows: names that start and end with
+a single underscore are reserved by enum and cannot be used; all other
+attributes defined within an enumeration will become members of this
+enumeration, with the exception of special methods (:meth:`__str__`,
+:meth:`__add__`, etc.), descriptors (methods are also descriptors), and
+variable names listed in :attr:`_ignore_`.
+
+Note: if your enumeration defines :meth:`__new__` and/or :meth:`__init__` then
+any value(s) given to the enum member will be passed into those methods.
+See `Planet`_ for an example.
+
+
+Restricted Enum subclassing
+---------------------------
+
+A new :class:`Enum` class must have one base Enum class, up to one concrete
+data type, and as many :class:`object`-based mixin classes as needed. The
+order of these base classes is::
+
+ class EnumName([mix-in, ...,] [data-type,] base-enum):
+ pass
+
+Also, subclassing an enumeration is allowed only if the enumeration does not define
+any members. So this is forbidden::
+
+ >>> class MoreColor(Color):
+ ... PINK = 17
+ ...
+ Traceback (most recent call last):
+ ...
+ TypeError: MoreColor: cannot extend enumeration 'Color'
+
+But this is allowed::
+
+ >>> class Foo(Enum):
+ ... def some_behavior(self):
+ ... pass
+ ...
+ >>> class Bar(Foo):
+ ... HAPPY = 1
+ ... SAD = 2
+ ...
+
+Allowing subclassing of enums that define members would lead to a violation of
+some important invariants of types and instances. On the other hand, it makes
+sense to allow sharing some common behavior between a group of enumerations.
+(See `OrderedEnum`_ for an example.)
+
+
+Pickling
+--------
+
+Enumerations can be pickled and unpickled::
+
+ >>> from test.test_enum import Fruit
+ >>> from pickle import dumps, loads
+ >>> Fruit.TOMATO is loads(dumps(Fruit.TOMATO))
+ True
+
+The usual restrictions for pickling apply: picklable enums must be defined in
+the top level of a module, since unpickling requires them to be importable
+from that module.
+
+.. note::
+
+ With pickle protocol version 4 it is possible to easily pickle enums
+ nested in other classes.
+
+It is possible to modify how Enum members are pickled/unpickled by defining
+:meth:`__reduce_ex__` in the enumeration class.
+
+
+Functional API
+--------------
+
+The :class:`Enum` class is callable, providing the following functional API::
+
+ >>> Animal = Enum('Animal', 'ANT BEE CAT DOG')
+ >>> Animal
+ <enum 'Animal'>
+ >>> Animal.ANT
+ <Animal.ANT: 1>
+ >>> Animal.ANT.value
+ 1
+ >>> list(Animal)
+ [<Animal.ANT: 1>, <Animal.BEE: 2>, <Animal.CAT: 3>, <Animal.DOG: 4>]
+
+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 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).
+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.
+
+The new pickle protocol 4 also, in some circumstances, relies on
+:attr:`~definition.__qualname__` being set to the location where pickle will be able
+to find the class. For example, if the class was made available in class
+SomeData in the global scope::
+
+ >>> Animal = Enum('Animal', 'ANT BEE CAT DOG', qualname='SomeData.Animal')
+
+The complete signature is::
+
+ Enum(value='NewEnumName', names=<...>, *, module='...', qualname='...', type=<mixed-in class>, start=1)
+
+:value: What the new Enum class will record as its name.
+
+:names: The Enum members. This can be a whitespace or comma separated string
+ (values will start at 1 unless otherwise specified)::
+
+ 'RED GREEN BLUE' | 'RED,GREEN,BLUE' | 'RED, GREEN, BLUE'
+
+ or an iterator of names::
+
+ ['RED', 'GREEN', 'BLUE']
+
+ or an iterator of (name, value) pairs::
+
+ [('CYAN', 4), ('MAGENTA', 5), ('YELLOW', 6)]
+
+ or a mapping::
+
+ {'CHARTREUSE': 7, 'SEA_GREEN': 11, 'ROSEMARY': 42}
+
+:module: name of module where new Enum class can be found.
+
+:qualname: where in module new Enum class can be found.
+
+:type: type to mix in to new Enum class.
+
+:start: number to start counting at if only names are passed in.
+
+.. versionchanged:: 3.5
+ The *start* parameter was added.
+
+
+Derived Enumerations
+--------------------
+
+IntEnum
+^^^^^^^
+
+The first variation of :class:`Enum` that is provided 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):
+ ... POST = 1
+ ... GET = 2
+ ...
+ >>> Shape == 1
+ False
+ >>> Shape.CIRCLE == 1
+ True
+ >>> Shape.CIRCLE == Request.POST
+ True
+
+However, they still can't be compared to standard :class:`Enum` enumerations::
+
+ >>> class Shape(IntEnum):
+ ... CIRCLE = 1
+ ... SQUARE = 2
+ ...
+ >>> class Color(Enum):
+ ... RED = 1
+ ... GREEN = 2
+ ...
+ >>> Shape.CIRCLE == Color.RED
+ False
+
+: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]
+
+
+IntFlag
+^^^^^^^
+
+The next variation of :class:`Enum` provided, :class:`IntFlag`, is also based
+on :class:`int`. The difference being :class:`IntFlag` members can be combined
+using the bitwise operators (&, \|, ^, ~) and the result is still an
+:class:`IntFlag` member. However, as the name implies, :class:`IntFlag`
+members also subclass :class:`int` and can be used wherever an :class:`int` is
+used. Any operation on an :class:`IntFlag` member besides the bit-wise
+operations will lose the :class:`IntFlag` membership.
+
+.. versionadded:: 3.6
+
+Sample :class:`IntFlag` class::
+
+ >>> from enum import IntFlag
+ >>> class Perm(IntFlag):
+ ... R = 4
+ ... W = 2
+ ... X = 1
+ ...
+ >>> Perm.R | Perm.W
+ <Perm.R|W: 6>
+ >>> Perm.R + Perm.W
+ 6
+ >>> RW = Perm.R | Perm.W
+ >>> Perm.R in RW
+ True
+
+It is also possible to name the combinations::
+
+ >>> class Perm(IntFlag):
+ ... R = 4
+ ... W = 2
+ ... X = 1
+ ... RWX = 7
+ >>> Perm.RWX
+ <Perm.RWX: 7>
+ >>> ~Perm.RWX
+ <Perm.-8: -8>
+
+Another important difference between :class:`IntFlag` and :class:`Enum` is that
+if no flags are set (the value is 0), its boolean evaluation is :data:`False`::
+
+ >>> Perm.R & Perm.X
+ <Perm.0: 0>
+ >>> bool(Perm.R & Perm.X)
+ False
+
+Because :class:`IntFlag` members are also subclasses of :class:`int` they can
+be combined with them::
+
+ >>> Perm.X | 8
+ <Perm.8|X: 9>
+
+
+Flag
+^^^^
+
+The last variation is :class:`Flag`. Like :class:`IntFlag`, :class:`Flag`
+members can be combined using the bitwise operators (&, \|, ^, ~). Unlike
+:class:`IntFlag`, they cannot be combined with, nor compared against, any
+other :class:`Flag` enumeration, nor :class:`int`. While it is possible to
+specify the values directly it is recommended to use :class:`auto` as the
+value and let :class:`Flag` select an appropriate value.
+
+.. versionadded:: 3.6
+
+Like :class:`IntFlag`, if a combination of :class:`Flag` members results in no
+flags being set, the boolean evaluation is :data:`False`::
+
+ >>> from enum import Flag, auto
+ >>> class Color(Flag):
+ ... RED = auto()
+ ... BLUE = auto()
+ ... GREEN = auto()
+ ...
+ >>> Color.RED & Color.GREEN
+ <Color.0: 0>
+ >>> bool(Color.RED & Color.GREEN)
+ False
+
+Individual flags should have values that are powers of two (1, 2, 4, 8, ...),
+while combinations of flags won't::
+
+ >>> class Color(Flag):
+ ... RED = auto()
+ ... BLUE = auto()
+ ... GREEN = auto()
+ ... WHITE = RED | BLUE | GREEN
+ ...
+ >>> Color.WHITE
+ <Color.WHITE: 7>
+
+Giving a name to the "no flags set" condition does not change its boolean
+value::
+
+ >>> class Color(Flag):
+ ... BLACK = 0
+ ... RED = auto()
+ ... BLUE = auto()
+ ... GREEN = auto()
+ ...
+ >>> Color.BLACK
+ <Color.BLACK: 0>
+ >>> bool(Color.BLACK)
+ False
+
+.. note::
+
+ For the majority of new code, :class:`Enum` and :class:`Flag` are strongly
+ recommended, since :class:`IntEnum` and :class:`IntFlag` break some
+ semantic promises of an enumeration (by being comparable to integers, and
+ thus by transitivity to other unrelated enumerations). :class:`IntEnum`
+ and :class:`IntFlag` should be used only in cases where :class:`Enum` and
+ :class:`Flag` will not do; for example, when integer constants are replaced
+ with enumerations, or for interoperability with other systems.
+
+
+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`.
+
+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 type.
+3. When another data type is mixed in, the :attr:`value` attribute is *not the
+ same* as the enum member itself, although it is equivalent and will compare
+ equal.
+4. %-style formatting: `%s` and `%r` call the :class:`Enum` class's
+ :meth:`__str__` and :meth:`__repr__` respectively; other codes (such as
+ `%i` or `%h` for IntEnum) treat the enum member as its mixed-in type.
+5. :ref:`Formatted string literals <f-strings>`, :meth:`str.format`,
+ and :func:`format` will use the mixed-in type's :meth:`__format__`
+ unless :meth:`__str__` or :meth:`__format__` is overridden in the subclass,
+ in which case the overridden methods or :class:`Enum` methods will be used.
+ Use the !s and !r format codes to force usage of the :class:`Enum` class's
+ :meth:`__str__` and :meth:`__repr__` methods.
+
+When to use :meth:`__new__` vs. :meth:`__init__`
+------------------------------------------------
+
+:meth:`__new__` must be used whenever you want to customize the actual value of
+the :class:`Enum` member. Any other modifications may go in either
+:meth:`__new__` or :meth:`__init__`, with :meth:`__init__` being preferred.
+
+For example, if you want to pass several items to the constructor, but only
+want one of them to be the value::
+
+ >>> class Coordinate(bytes, Enum):
+ ... """
+ ... Coordinate with binary codes that can be indexed by the int code.
+ ... """
+ ... def __new__(cls, value, label, unit):
+ ... obj = bytes.__new__(cls, [value])
+ ... obj._value_ = value
+ ... obj.label = label
+ ... obj.unit = unit
+ ... return obj
+ ... PX = (0, 'P.X', 'km')
+ ... PY = (1, 'P.Y', 'km')
+ ... VX = (2, 'V.X', 'km/s')
+ ... VY = (3, 'V.Y', 'km/s')
+ ...
+
+ >>> print(Coordinate['PY'])
+ Coordinate.PY
+
+ >>> print(Coordinate(3))
+ Coordinate.VY
+
+Interesting examples
+--------------------
+
+While :class:`Enum`, :class:`IntEnum`, :class:`IntFlag`, and :class:`Flag` 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.
+
+
+Omitting values
+^^^^^^^^^^^^^^^
+
+In many use-cases one doesn't care what the actual value of an enumeration
+is. There are several ways to define this type of simple enumeration:
+
+- use instances of :class:`auto` for the value
+- use instances of :class:`object` as the value
+- use a descriptive string as the value
+- use a tuple as the value and a custom :meth:`__new__` to replace the
+ tuple with an :class:`int` value
+
+Using any of these methods signifies to the user that these values are not
+important, and also enables one to add, remove, or reorder members without
+having to renumber the remaining members.
+
+Whichever method you choose, you should provide a :meth:`repr` that also hides
+the (unimportant) value::
+
+ >>> class NoValue(Enum):
+ ... def __repr__(self):
+ ... return '<%s.%s>' % (self.__class__.__name__, self.name)
+ ...
+
+
+Using :class:`auto`
+"""""""""""""""""""
+
+Using :class:`auto` would look like::
+
+ >>> class Color(NoValue):
+ ... RED = auto()
+ ... BLUE = auto()
+ ... GREEN = auto()
+ ...
+ >>> Color.GREEN
+ <Color.GREEN>
+
+
+Using :class:`object`
+"""""""""""""""""""""
+
+Using :class:`object` would look like::
+
+ >>> class Color(NoValue):
+ ... RED = object()
+ ... GREEN = object()
+ ... BLUE = object()
+ ...
+ >>> Color.GREEN
+ <Color.GREEN>
+
+
+Using a descriptive string
+""""""""""""""""""""""""""
+
+Using a string as the value would look like::
+
+ >>> class Color(NoValue):
+ ... RED = 'stop'
+ ... GREEN = 'go'
+ ... BLUE = 'too fast!'
+ ...
+ >>> Color.GREEN
+ <Color.GREEN>
+ >>> Color.GREEN.value
+ 'go'
+
+
+Using a custom :meth:`__new__`
+""""""""""""""""""""""""""""""
+
+Using an auto-numbering :meth:`__new__` would look like::
+
+ >>> class AutoNumber(NoValue):
+ ... def __new__(cls):
+ ... value = len(cls.__members__) + 1
+ ... obj = object.__new__(cls)
+ ... obj._value_ = value
+ ... return obj
+ ...
+ >>> class Color(AutoNumber):
+ ... RED = ()
+ ... GREEN = ()
+ ... BLUE = ()
+ ...
+ >>> Color.GREEN
+ <Color.GREEN>
+ >>> Color.GREEN.value
+ 2
+
+To make a more general purpose ``AutoNumber``, add ``*args`` to the signature::
+
+ >>> class AutoNumber(NoValue):
+ ... def __new__(cls, *args): # this is the only change from above
+ ... value = len(cls.__members__) + 1
+ ... obj = object.__new__(cls)
+ ... obj._value_ = value
+ ... return obj
+ ...
+
+Then when you inherit from ``AutoNumber`` you can write your own ``__init__``
+to handle any extra arguments::
+
+ >>> class Swatch(AutoNumber):
+ ... def __init__(self, pantone='unknown'):
+ ... self.pantone = pantone
+ ... AUBURN = '3497'
+ ... SEA_GREEN = '1246'
+ ... BLEACHED_CORAL = () # New color, no Pantone code yet!
+ ...
+ >>> Swatch.SEA_GREEN
+ <Swatch.SEA_GREEN>
+ >>> Swatch.SEA_GREEN.pantone
+ '1246'
+ >>> Swatch.BLEACHED_CORAL.pantone
+ 'unknown'
+
+.. 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.
+
+
+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):
+ ... 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
+ ...
+ >>> class Grade(OrderedEnum):
+ ... A = 5
+ ... B = 4
+ ... C = 3
+ ... D = 2
+ ... F = 1
+ ...
+ >>> Grade.C < Grade.A
+ True
+
+
+DuplicateFreeEnum
+^^^^^^^^^^^^^^^^^
+
+Raises an error if a duplicate member name is found instead of creating an
+alias::
+
+ >>> class DuplicateFreeEnum(Enum):
+ ... def __init__(self, *args):
+ ... cls = self.__class__
+ ... if any(self.value == e.value for e in cls):
+ ... a = self.name
+ ... e = cls(self.value).name
+ ... raise ValueError(
+ ... "aliases not allowed in DuplicateFreeEnum: %r --> %r"
+ ... % (a, e))
+ ...
+ >>> class Color(DuplicateFreeEnum):
+ ... RED = 1
+ ... GREEN = 2
+ ... BLUE = 3
+ ... GRENE = 2
+ ...
+ Traceback (most recent call last):
+ ...
+ ValueError: aliases not allowed in DuplicateFreeEnum: 'GRENE' --> 'GREEN'
+
+.. note::
+
+ This is a useful example for subclassing Enum to add or change other
+ behaviors as well as disallowing aliases. If the only desired change is
+ disallowing aliases, the :func:`unique` decorator can be used instead.
+
+
+Planet
+^^^^^^
+
+If :meth:`__new__` or :meth:`__init__` is defined the value of the enum member
+will be passed to those methods::
+
+ >>> class Planet(Enum):
+ ... MERCURY = (3.303e+23, 2.4397e6)
+ ... VENUS = (4.869e+24, 6.0518e6)
+ ... EARTH = (5.976e+24, 6.37814e6)
+ ... MARS = (6.421e+23, 3.3972e6)
+ ... JUPITER = (1.9e+27, 7.1492e7)
+ ... SATURN = (5.688e+26, 6.0268e7)
+ ... URANUS = (8.686e+25, 2.5559e7)
+ ... NEPTUNE = (1.024e+26, 2.4746e7)
+ ... def __init__(self, mass, radius):
+ ... self.mass = mass # in kilograms
+ ... self.radius = radius # in meters
+ ... @property
+ ... def surface_gravity(self):
+ ... # universal gravitational constant (m3 kg-1 s-2)
+ ... G = 6.67300E-11
+ ... return G * self.mass / (self.radius * self.radius)
+ ...
+ >>> Planet.EARTH.value
+ (5.976e+24, 6378140.0)
+ >>> Planet.EARTH.surface_gravity
+ 9.802652743337129
+
+
+TimePeriod
+^^^^^^^^^^
+
+An example to show the :attr:`_ignore_` attribute in use::
+
+ >>> from datetime import timedelta
+ >>> class Period(timedelta, Enum):
+ ... "different lengths of time"
+ ... _ignore_ = 'Period i'
+ ... Period = vars()
+ ... for i in range(367):
+ ... Period['day_%d' % i] = i
+ ...
+ >>> list(Period)[:2]
+ [<Period.day_0: datetime.timedelta(0)>, <Period.day_1: datetime.timedelta(days=1)>]
+ >>> list(Period)[-2:]
+ [<Period.day_365: datetime.timedelta(days=365)>, <Period.day_366: datetime.timedelta(days=366)>]
+
+
+How are Enums different?
+------------------------
+
+Enums have a custom metaclass that affects many aspects of both derived Enum
+classes and their instances (members).
+
+
+Enum Classes
+^^^^^^^^^^^^
+
+The :class:`EnumMeta` metaclass is responsible for providing the
+:meth:`__contains__`, :meth:`__dir__`, :meth:`__iter__` and other methods that
+allow one to do things with an :class:`Enum` class that fail on a typical
+class, such as `list(Color)` or `some_enum_var in Color`. :class:`EnumMeta` is
+responsible for ensuring that various other methods on the final :class:`Enum`
+class are correct (such as :meth:`__new__`, :meth:`__getnewargs__`,
+:meth:`__str__` and :meth:`__repr__`).
+
+
+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
+^^^^^^^^^^^^
+
+Supported ``__dunder__`` names
+""""""""""""""""""""""""""""""
+
+:attr:`__members__` is a read-only ordered mapping of ``member_name``:``member``
+items. It 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
+""""""""""""""""""""""""""""
+
+- ``_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; may be
+ overridden
+- ``_ignore_`` -- a list of names, either as a :class:`list` or a :class:`str`,
+ that will not be transformed into members, and will be removed from the final
+ class
+- ``_order_`` -- used in Python 2/3 code to ensure member order is consistent
+ (class attribute, removed during class creation)
+- ``_generate_next_value_`` -- used by the `Functional API`_ and by
+ :class:`auto` to get an appropriate value for an enum member; may be
+ overridden
+
+.. versionadded:: 3.6 ``_missing_``, ``_order_``, ``_generate_next_value_``
+.. versionadded:: 3.7 ``_ignore_``
+
+To help keep Python 2 / Python 3 code in sync an :attr:`_order_` attribute can
+be provided. It will be checked against the actual order of the enumeration
+and raise an error if the two do not match::
+
+ >>> class Color(Enum):
+ ... _order_ = 'RED GREEN BLUE'
+ ... RED = 1
+ ... BLUE = 3
+ ... GREEN = 2
+ ...
+ Traceback (most recent call last):
+ ...
+ TypeError: member order does not match _order_
+
+.. note::
+
+ In Python 2 code the :attr:`_order_` attribute is necessary as definition
+ order is lost before it can be recorded.
+
+
+_Private__names
+"""""""""""""""
+
+Private names will be normal attributes in Python 3.10 instead of either an error
+or a member (depending on if the name ends with an underscore). Using these names
+in 3.9 will issue a :exc:`DeprecationWarning`.
+
+
+``Enum`` member type
+""""""""""""""""""""
+
+:class:`Enum` members are instances of their :class:`Enum` class, and are
+normally accessed as ``EnumClass.member``. Under certain circumstances they
+can also be accessed as ``EnumClass.member.member``, but you should never do
+this as that lookup may fail or, worse, return something besides the
+:class:`Enum` member you are looking for (this is another good reason to use
+all-uppercase names for members)::
+
+ >>> class FieldTypes(Enum):
+ ... name = 0
+ ... value = 1
+ ... size = 2
+ ...
+ >>> FieldTypes.value.size
+ <FieldTypes.size: 2>
+ >>> FieldTypes.size.value
+ 2
+
+.. versionchanged:: 3.5
+
+
+Boolean value of ``Enum`` classes and members
+"""""""""""""""""""""""""""""""""""""""""""""
+
+:class:`Enum` members that are mixed with non-:class:`Enum` types (such as
+:class:`int`, :class:`str`, etc.) are evaluated according to the mixed-in
+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)
+
+:class:`Enum` classes always evaluate as :data:`True`.
+
+
+``Enum`` classes with methods
+"""""""""""""""""""""""""""""
+
+If you give your :class:`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__', 'mass', 'name', 'radius', 'surface_gravity', 'value']
+
+
+Combining members of ``Flag``
+"""""""""""""""""""""""""""""
+
+If a combination of Flag members is not named, the :func:`repr` will include
+all named flags and all named combinations of flags that are in the value::
+
+ >>> class Color(Flag):
+ ... RED = auto()
+ ... GREEN = auto()
+ ... BLUE = auto()
+ ... MAGENTA = RED | BLUE
+ ... YELLOW = RED | GREEN
+ ... CYAN = GREEN | BLUE
+ ...
+ >>> Color(3) # named combination
+ <Color.YELLOW: 3>
+ >>> Color(7) # not named combination
+ <Color.CYAN|MAGENTA|BLUE|YELLOW|GREEN|RED: 7>
+