0
  #   ˆl–ßi~”JhŠi@=p ¸ )‹FÿÀ„‚ËŸ¿È ?÷     ``enum`` --- support for enumerations
========================================

.. :synopsis: enumerations are sets of symbolic names bound to unique, constant
  values.
.. :moduleauthor:: Ethan Furman <ethan@stoneleaf.us>
.. :sectionauthor:: Barry Warsaw <barry@python.org>,
.. :sectionauthor:: Eli Bendersky <eliben@gmail.com>,
.. :sectionauthor:: Ethan Furman <ethan@stoneleaf.us>

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

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.


Module Contents
---------------

This module defines two enumeration classes that can be used to define unique
sets of names and values: ``Enum`` and ``IntEnum``.  It also defines
one decorator, ``unique``.

``Enum``

Base class for creating enumerated constants.  See section `Functional API`_
for an alternate construction syntax.

``IntEnum``

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

``unique``

Enum class decorator that ensures only one name is bound to any one value.


Creating an Enum
----------------

Enumerations are created using the ``class`` syntax, which makes them
easy to read and write.  An alternative creation method is described in
`Functional API`_.  To define an enumeration, subclass ``Enum`` as
follows::

    >>> from enum import Enum
    >>> class Color(Enum):
    ...     red = 1
    ...     green = 2
    ...     blue = 3

Note: Nomenclature

  - The class ``Color`` is an *enumeration* (or *enum*)
  - The attributes ``Color.red``, ``Color.green``, etc., are
    *enumeration members* (or *enum members*).
  - The enum members have *names* and *values* (the name of
    ``Color.red`` is ``red``, the value of ``Color.blue`` is
    ``3``, etc.)
    
Note:

    Even though we use the ``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 Python 3.x definition order is used; in
Python 2.x the definition order is not available, but class attribute
``__order__`` is supported;  otherwise, value order is used::

    >>> class Shake(Enum):
    ...   __order__ = 'vanilla chocolate cookies mint'  # only needed in 2.x
    ...   vanilla = 7
    ...   chocolate = 4
    ...   cookies = 9
    ...   mint = 3
    ...
    >>> for shake in Shake:
    ...   print(shake)
    ...
    Shake.vanilla
    Shake.chocolate
    Shake.cookies
    Shake.mint

The ``__order__`` attribute is always removed, and in 3.x it is also ignored
(order is definition order); however, in the stdlib version it will be ignored
but not removed.

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