Doc/library/enum.rst

:mod:`enum` --- Support for enumerations
========================================

.. module:: enum
   :synopsis: Implementation of an enumeration class.

.. moduleauthor:: Ethan Furman <ethan@stoneleaf.us>
.. sectionauthor:: Barry Warsaw <barry@python.org>
.. sectionauthor:: Eli Bendersky <eliben@gmail.com>
.. sectionauthor:: Ethan Furman <ethan@stoneleaf.us>

.. versionadded:: 3.4

**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

   * :ref:`Basic Tutorial <enum-basic-tutorial>`
   * :ref:`Advanced Tutorial <enum-advanced-tutorial>`
   * :ref:`Enum Cookbook <enum-cookbook>`

----------------

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 :meth:`call` syntax to return members by value
* uses :meth:`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`.

   :class:`StrEnum`

      Base class for creating enumerated constants that are also
      subclasses of :class:`str`.

   :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`.

   :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.


.. versionadded:: 3.6  ``Flag``, ``IntFlag``, ``auto``
.. versionadded:: 3.10  ``StrEnum``


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

   .. 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]


.. 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``.


.. 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``.


.. 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.

      >>> 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

   If any integer operation is performed with an *IntFlag* member, the result is
   not an *IntFlag*::

        >>> Color.RED + 2
        3

   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:: 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 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 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 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 KEEP
         >>> class KeepFlag(Flag, boundary=KEEP):
         ...     RED = auto()
         ...     GREEN = auto()
         ...     BLUE = auto()
         >>> KeepFlag(2**2 + 2**4)
         KeepFlag.BLUE|0x10


Utilites and Decorators
-----------------------

.. 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.

   ``_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 the global namespace
   they were defined in.


.. decorator:: property

   A decorator similar to the built-in *property*, but specifically for
   enumerations.  It allows member attributes to have the same names as members
   themselves.

   .. 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``.

.. 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::

      >>> 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