enum.rst 32 KB
Newer Older
1 2 3 4
:mod:`enum` --- Support for enumerations
========================================

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

7 8 9 10 11
.. :moduleauthor:: Ethan Furman <ethan@stoneleaf.us>
.. :sectionauthor:: Barry Warsaw <barry@python.org>,
.. :sectionauthor:: Eli Bendersky <eliben@gmail.com>,
.. :sectionauthor:: Ethan Furman <ethan@stoneleaf.us>

12 13
.. versionadded:: 3.4

14 15 16 17
**Source code:** :source:`Lib/enum.py`

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

18 19 20 21 22 23 24
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
---------------
25

26
This module defines four enumeration classes that can be used to define unique
27 28
sets of names and values: :class:`Enum`, :class:`IntEnum`, :class:`Flag`, and
:class:`IntFlag`.  It also defines one decorator, :func:`unique`, and one
29
helper, :class:`auto`.
30 31 32 33

.. class:: Enum

    Base class for creating enumerated constants.  See section
34
    `Functional API`_ for an alternate construction syntax.
35 36 37 38 39 40

.. class:: IntEnum

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

41 42 43 44 45 46 47 48 49 50 51
.. 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:: Flag

    Base class for creating enumerated constants that can be combined using
    the bitwise operations without losing their :class:`Flag` membership.

52 53 54
.. function:: unique

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

56 57 58 59 60
.. class:: auto

    Instances are replaced with an appropriate value for Enum members.

.. versionadded:: 3.6  ``Flag``, ``IntFlag``, ``auto``
61

62 63 64 65 66 67

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
68 69 70 71 72
`Functional API`_.  To define an enumeration, subclass :class:`Enum` as
follows::

    >>> from enum import Enum
    >>> class Color(Enum):
73 74 75
    ...     RED = 1
    ...     GREEN = 2
    ...     BLUE = 3
76
    ...
77

78 79 80 81 82 83 84
.. 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.

85 86
.. note:: Nomenclature

87
  - The class :class:`Color` is an *enumeration* (or *enum*)
88 89
  - The attributes :attr:`Color.RED`, :attr:`Color.GREEN`, etc., are
    *enumeration members* (or *enum members*) and are functionally constants.
90
  - The enum members have *names* and *values* (the name of
91
    :attr:`Color.RED` is ``RED``, the value of :attr:`Color.BLUE` is
92
    ``3``, etc.)
93

94 95 96 97 98 99
.. 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.

100 101
Enumeration members have human readable string representations::

102 103
    >>> print(Color.RED)
    Color.RED
104 105 106

...while their ``repr`` has more information::

107 108
    >>> print(repr(Color.RED))
    <Color.RED: 1>
109 110 111

The *type* of an enumeration member is the enumeration it belongs to::

112
    >>> type(Color.RED)
113
    <enum 'Color'>
114
    >>> isinstance(Color.GREEN, Color)
115 116 117 118 119
    True
    >>>

Enum members also have a property that contains just their item name::

120 121
    >>> print(Color.RED.name)
    RED
122 123 124 125

Enumerations support iteration, in definition order::

    >>> class Shake(Enum):
126 127 128 129
    ...     VANILLA = 7
    ...     CHOCOLATE = 4
    ...     COOKIES = 9
    ...     MINT = 3
130 131
    ...
    >>> for shake in Shake:
132
    ...     print(shake)
133
    ...
134 135 136 137
    Shake.VANILLA
    Shake.CHOCOLATE
    Shake.COOKIES
    Shake.MINT
138 139 140 141

Enumeration members are hashable, so they can be used in dictionaries and sets::

    >>> apples = {}
142 143 144
    >>> apples[Color.RED] = 'red delicious'
    >>> apples[Color.GREEN] = 'granny smith'
    >>> apples == {Color.RED: 'red delicious', Color.GREEN: 'granny smith'}
145 146 147
    True


148 149
Programmatic access to enumeration members and their attributes
---------------------------------------------------------------
150 151

Sometimes it's useful to access members in enumerations programmatically (i.e.
152
situations where ``Color.RED`` won't do because the exact color is not known
153 154 155
at program-writing time).  ``Enum`` allows such access::

    >>> Color(1)
156
    <Color.RED: 1>
157
    >>> Color(3)
158
    <Color.BLUE: 3>
159 160 161

If you want to access enum members by *name*, use item access::

162 163 164 165
    >>> Color['RED']
    <Color.RED: 1>
    >>> Color['GREEN']
    <Color.GREEN: 2>
166

167
If you have an enum member and need its :attr:`name` or :attr:`value`::
168

169
    >>> member = Color.RED
170
    >>> member.name
171
    'RED'
172 173 174
    >>> member.value
    1

175 176 177 178 179 180 181

Duplicating enum members and values
-----------------------------------

Having two enum members with the same name is invalid::

    >>> class Shape(Enum):
182 183
    ...     SQUARE = 2
    ...     SQUARE = 3
184 185 186
    ...
    Traceback (most recent call last):
    ...
187
    TypeError: Attempted to reuse key: 'SQUARE'
188 189 190 191 192 193 194

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):
195 196 197 198
    ...     SQUARE = 2
    ...     DIAMOND = 1
    ...     CIRCLE = 3
    ...     ALIAS_FOR_SQUARE = 2
199
    ...
200 201 202 203
    >>> Shape.SQUARE
    <Shape.SQUARE: 2>
    >>> Shape.ALIAS_FOR_SQUARE
    <Shape.SQUARE: 2>
204
    >>> Shape(2)
205
    <Shape.SQUARE: 2>
206

207 208 209 210 211 212
.. 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.

213 214

Ensuring unique enumeration values
215
----------------------------------
216 217 218 219 220 221 222 223 224 225 226 227 228 229

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

    >>> from enum import Enum, unique
    >>> @unique
    ... class Mistake(Enum):
230 231 232 233
    ...     ONE = 1
    ...     TWO = 2
    ...     THREE = 3
    ...     FOUR = 3
234
    ...
235 236
    Traceback (most recent call last):
    ...
237
    ValueError: duplicate values found in <enum 'Mistake'>: FOUR -> THREE
238 239


240 241 242 243 244 245 246
Using automatic values
----------------------

If the exact value is unimportant you can use :class:`auto`::

    >>> from enum import Enum, auto
    >>> class Color(Enum):
247 248 249
    ...     RED = auto()
    ...     BLUE = auto()
    ...     GREEN = auto()
250 251
    ...
    >>> list(Color)
252
    [<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]
253 254 255 256 257 258 259 260 261

The values are chosen by :func:`_generate_next_value_`, which can be
overridden::

    >>> class AutoName(Enum):
    ...     def _generate_next_value_(name, start, count, last_values):
    ...         return name
    ...
    >>> class Ordinal(AutoName):
262 263 264 265
    ...     NORTH = auto()
    ...     SOUTH = auto()
    ...     EAST = auto()
    ...     WEST = auto()
266 267
    ...
    >>> list(Ordinal)
268
    [<Ordinal.NORTH: 'NORTH'>, <Ordinal.SOUTH: 'SOUTH'>, <Ordinal.EAST: 'EAST'>, <Ordinal.WEST: 'WEST'>]
269 270 271 272 273 274 275

.. note::

    The goal of the default :meth:`_generate_next_value_` methods 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.

276
Iteration
277
---------
278

279 280 281
Iterating over the members of an enum does not provide the aliases::

    >>> list(Shape)
282
    [<Shape.SQUARE: 2>, <Shape.DIAMOND: 1>, <Shape.CIRCLE: 3>]
283 284 285 286 287 288

The special attribute ``__members__`` is an ordered dictionary mapping names
to members.  It includes all names defined in the enumeration, including the
aliases::

    >>> for name, member in Shape.__members__.items():
289
    ...     name, member
290
    ...
291 292 293 294
    ('SQUARE', <Shape.SQUARE: 2>)
    ('DIAMOND', <Shape.DIAMOND: 1>)
    ('CIRCLE', <Shape.CIRCLE: 3>)
    ('ALIAS_FOR_SQUARE', <Shape.SQUARE: 2>)
295 296 297 298

The ``__members__`` attribute can be used for detailed programmatic access to
the enumeration members.  For example, finding all the aliases::

299
    >>> [name for name, member in Shape.__members__.items() if member.name != name]
300
    ['ALIAS_FOR_SQUARE']
301

302

303 304 305 306 307
Comparisons
-----------

Enumeration members are compared by identity::

308
    >>> Color.RED is Color.RED
309
    True
310
    >>> Color.RED is Color.BLUE
311
    False
312
    >>> Color.RED is not Color.BLUE
313 314 315 316 317
    True

Ordered comparisons between enumeration values are *not* supported.  Enum
members are not integers (but see `IntEnum`_ below)::

318
    >>> Color.RED < Color.BLUE
319 320
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
321
    TypeError: '<' not supported between instances of 'Color' and 'Color'
322 323 324

Equality comparisons are defined though::

325
    >>> Color.BLUE == Color.RED
326
    False
327
    >>> Color.BLUE != Color.RED
328
    True
329
    >>> Color.BLUE == Color.BLUE
330 331 332
    True

Comparisons against non-enumeration values will always compare not equal
333
(again, :class:`IntEnum` was explicitly designed to behave differently, see
334 335
below)::

336
    >>> Color.BLUE == 2
337 338 339 340 341 342 343
    False


Allowed members and attributes of enumerations
----------------------------------------------

The examples above use integers for enumeration values.  Using integers is
344 345 346 347
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.
348 349 350 351 352

Enumerations are Python classes, and can have methods and special methods as
usual.  If we have this enumeration::

    >>> class Mood(Enum):
353 354
    ...     FUNKY = 1
    ...     HAPPY = 3
355 356 357 358
    ...
    ...     def describe(self):
    ...         # self is the member here
    ...         return self.name, self.value
359
    ...
360 361
    ...     def __str__(self):
    ...         return 'my custom str! {0}'.format(self.value)
362
    ...
363 364 365
    ...     @classmethod
    ...     def favorite_mood(cls):
    ...         # cls here is the enumeration
366
    ...         return cls.HAPPY
367 368 369 370 371
    ...

Then::

    >>> Mood.favorite_mood()
372 373 374 375
    <Mood.HAPPY: 3>
    >>> Mood.HAPPY.describe()
    ('HAPPY', 3)
    >>> str(Mood.FUNKY)
376 377
    'my custom str! 1'

378 379
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
380 381 382
attributes defined within an enumeration will become members of this
enumeration, with the exception of special methods (:meth:`__str__`,
:meth:`__add__`, etc.) and descriptors (methods are also descriptors).
383 384 385 386 387 388 389 390 391 392 393 394 395

Note:  if your enumeration defines :meth:`__new__` and/or :meth:`__init__` then
whatever value(s) were given to the enum member will be passed into those
methods.  See `Planet`_ for an example.


Restricted subclassing of enumerations
--------------------------------------

Subclassing an enumeration is allowed only if the enumeration does not define
any members.  So this is forbidden::

    >>> class MoreColor(Color):
396
    ...     PINK = 17
397
    ...
398 399 400 401 402 403 404
    Traceback (most recent call last):
    ...
    TypeError: Cannot extend enumerations

But this is allowed::

    >>> class Foo(Enum):
405 406
    ...     def some_behavior(self):
    ...         pass
407 408
    ...
    >>> class Bar(Foo):
409 410
    ...     HAPPY = 1
    ...     SAD = 2
411 412 413 414 415 416 417 418 419 420 421 422 423 424 425
    ...

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
426
    >>> Fruit.TOMATO is loads(dumps(Fruit.TOMATO))
427 428 429 430 431 432
    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.

433
.. note::
434

435 436
    With pickle protocol version 4 it is possible to easily pickle enums
    nested in other classes.
437

438 439 440
It is possible to modify how Enum members are pickled/unpickled by defining
:meth:`__reduce_ex__` in the enumeration class.

441 442 443 444 445 446

Functional API
--------------

The :class:`Enum` class is callable, providing the following functional API::

447
    >>> Animal = Enum('Animal', 'ANT BEE CAT DOG')
448 449
    >>> Animal
    <enum 'Animal'>
450 451 452
    >>> Animal.ANT
    <Animal.ANT: 1>
    >>> Animal.ANT.value
453 454
    1
    >>> list(Animal)
455
    [<Animal.ANT: 1>, <Animal.BEE: 2>, <Animal.CAT: 3>, <Animal.DOG: 4>]
456

457 458
The semantics of this API resemble :class:`~collections.namedtuple`. The first
argument of the call to :class:`Enum` is the name of the enumeration.
459

460 461 462 463 464 465 466 467
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::
468

469
    >>> class Animal(Enum):
470 471 472 473
    ...     ANT = 1
    ...     BEE = 2
    ...     CAT = 3
    ...     DOG = 4
474
    ...
475

476 477 478 479
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``.

480 481 482
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
483
function in separate module, and also may not work on IronPython or Jython).
484 485
The solution is to specify the module name explicitly as follows::

486
    >>> Animal = Enum('Animal', 'ANT BEE CAT DOG', module=__name__)
487

488 489
.. warning::

490
    If ``module`` is not supplied, and Enum cannot determine what it is,
491 492 493
    the new Enum members will not be unpicklable; to keep errors closer to
    the source, pickling will be disabled.

494
The new pickle protocol 4 also, in some circumstances, relies on
495
:attr:`~definition.__qualname__` being set to the location where pickle will be able
496 497 498
to find the class.  For example, if the class was made available in class
SomeData in the global scope::

499
    >>> Animal = Enum('Animal', 'ANT BEE CAT DOG', qualname='SomeData.Animal')
500

501 502
The complete signature is::

503
    Enum(value='NewEnumName', names=<...>, *, module='...', qualname='...', type=<mixed-in class>, start=1)
504

505
:value: What the new Enum class will record as its name.
506

507
:names: The Enum members.  This can be a whitespace or comma separated string
508
  (values will start at 1 unless otherwise specified)::
509

510
    'RED GREEN BLUE' | 'RED,GREEN,BLUE' | 'RED, GREEN, BLUE'
511

512 513
  or an iterator of names::

514
    ['RED', 'GREEN', 'BLUE']
515

516
  or an iterator of (name, value) pairs::
517

518
    [('CYAN', 4), ('MAGENTA', 5), ('YELLOW', 6)]
519

520
  or a mapping::
521

522
    {'CHARTREUSE': 7, 'SEA_GREEN': 11, 'ROSEMARY': 42}
523

524
:module: name of module where new Enum class can be found.
525

526
:qualname: where in module new Enum class can be found.
527

528
:type: type to mix in to new Enum class.
529

530
:start: number to start counting at if only names are passed in.
531

532 533 534
.. versionchanged:: 3.5
   The *start* parameter was added.

535

536
Derived Enumerations
537
--------------------
538 539

IntEnum
540
^^^^^^^
541

542
The first variation of :class:`Enum` that is provided is also a subclass of
543 544 545 546 547 548
: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):
549 550
    ...     CIRCLE = 1
    ...     SQUARE = 2
551 552
    ...
    >>> class Request(IntEnum):
553 554
    ...     POST = 1
    ...     GET = 2
555 556 557
    ...
    >>> Shape == 1
    False
558
    >>> Shape.CIRCLE == 1
559
    True
560
    >>> Shape.CIRCLE == Request.POST
561 562 563 564 565
    True

However, they still can't be compared to standard :class:`Enum` enumerations::

    >>> class Shape(IntEnum):
566 567
    ...     CIRCLE = 1
    ...     SQUARE = 2
568 569
    ...
    >>> class Color(Enum):
570 571
    ...     RED = 1
    ...     GREEN = 2
572
    ...
573
    >>> Shape.CIRCLE == Color.RED
574 575 576 577
    False

:class:`IntEnum` values behave like integers in other ways you'd expect::

578
    >>> int(Shape.CIRCLE)
579
    1
580
    >>> ['a', 'b', 'c'][Shape.CIRCLE]
581
    'b'
582
    >>> [i for i in range(Shape.SQUARE)]
583 584
    [0, 1]

585 586 587 588 589 590 591 592

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`
Ethan Furman's avatar
Ethan Furman committed
593 594 595
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.
596

597 598 599 600
.. versionadded:: 3.6

Sample :class:`IntFlag` class::

601 602 603 604 605 606 607 608 609 610 611 612 613 614
    >>> 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

615 616 617 618 619 620 621 622 623 624
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
625
    <Perm.-8: -8>
626 627 628 629 630 631 632 633 634 635 636 637 638 639

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>
640 641 642 643 644 645


Flag
^^^^

The last variation is :class:`Flag`.  Like :class:`IntFlag`, :class:`Flag`
646
members can be combined using the bitwise operators (&, \|, ^, ~).  Unlike
647
:class:`IntFlag`, they cannot be combined with, nor compared against, any
648 649 650
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.
651 652 653

.. versionadded:: 3.6

654 655 656 657 658
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
    >>> class Color(Flag):
659 660 661
    ...     RED = auto()
    ...     BLUE = auto()
    ...     GREEN = auto()
662
    ...
663
    >>> Color.RED & Color.GREEN
664
    <Color.0: 0>
665
    >>> bool(Color.RED & Color.GREEN)
666 667
    False

668 669 670 671
Individual flags should have values that are powers of two (1, 2, 4, 8, ...),
while combinations of flags won't::

    >>> class Color(Flag):
672 673 674 675
    ...     RED = auto()
    ...     BLUE = auto()
    ...     GREEN = auto()
    ...     WHITE = RED | BLUE | GREEN
676
    ...
677 678
    >>> Color.WHITE
    <Color.WHITE: 7>
679

680 681 682 683
Giving a name to the "no flags set" condition does not change its boolean
value::

    >>> class Color(Flag):
684 685 686 687
    ...     BLACK = 0
    ...     RED = auto()
    ...     BLUE = auto()
    ...     GREEN = auto()
688
    ...
689 690 691
    >>> Color.BLACK
    <Color.BLACK: 0>
    >>> bool(Color.BLACK)
692 693
    False

694 695 696 697 698 699 700 701 702
.. 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.
703

704 705

Others
706
^^^^^^
707 708 709 710 711 712 713 714

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
715
a :class:`StrEnum` that mixes in :class:`str` instead of :class:`int`.
716 717 718 719 720 721 722 723 724 725 726 727

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
   :class:`str`.
3. When another data type is mixed in, the :attr:`value` attribute is *not the
728
   same* as the enum member itself, although it is equivalent and will compare
729
   equal.
730 731 732
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.
733 734
5. :ref:`Formatted string literals <f-strings>`, :meth:`str.format`,
   and :func:`format` will use the mixed-in
735 736
   type's :meth:`__format__`.  If the :class:`Enum` class's :func:`str` or
   :func:`repr` is desired, use the `!s` or `!r` format codes.
737 738 739


Interesting examples
740
--------------------
741

742 743 744 745
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.
746 747


748 749
Omitting values
^^^^^^^^^^^^^^^
750

751 752
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:
753

754
- use instances of :class:`auto` for the value
755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772
- 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)
    ...


773 774 775
Using :class:`auto`
"""""""""""""""""""

776
Using :class:`auto` would look like::
777 778

    >>> class Color(NoValue):
779 780 781
    ...     RED = auto()
    ...     BLUE = auto()
    ...     GREEN = auto()
782
    ...
783 784
    >>> Color.GREEN
    <Color.GREEN>
785 786


787 788 789 790 791 792
Using :class:`object`
"""""""""""""""""""""

Using :class:`object` would look like::

    >>> class Color(NoValue):
793 794 795
    ...     RED = object()
    ...     GREEN = object()
    ...     BLUE = object()
796
    ...
797 798
    >>> Color.GREEN
    <Color.GREEN>
799 800 801 802 803 804 805 806


Using a descriptive string
""""""""""""""""""""""""""

Using a string as the value would look like::

    >>> class Color(NoValue):
807 808 809
    ...     RED = 'stop'
    ...     GREEN = 'go'
    ...     BLUE = 'too fast!'
810
    ...
811 812 813
    >>> Color.GREEN
    <Color.GREEN>
    >>> Color.GREEN.value
814 815 816 817 818 819 820 821 822
    'go'


Using a custom :meth:`__new__`
""""""""""""""""""""""""""""""

Using an auto-numbering :meth:`__new__` would look like::

    >>> class AutoNumber(NoValue):
823
    ...     def __new__(cls):
824 825
    ...         value = len(cls.__members__) + 1
    ...         obj = object.__new__(cls)
826
    ...         obj._value_ = value
827 828
    ...         return obj
    ...
829
    >>> class Color(AutoNumber):
830 831 832
    ...     RED = ()
    ...     GREEN = ()
    ...     BLUE = ()
833
    ...
834 835 836
    >>> Color.GREEN
    <Color.GREEN>
    >>> Color.GREEN.value
837 838
    2

839

840 841 842 843
.. 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
844
    class creation for lookup of existing members.
845

846 847

OrderedEnum
848
^^^^^^^^^^^
849 850 851 852 853 854 855 856

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__:
857
    ...             return self.value >= other.value
858 859 860
    ...         return NotImplemented
    ...     def __gt__(self, other):
    ...         if self.__class__ is other.__class__:
861
    ...             return self.value > other.value
862 863 864
    ...         return NotImplemented
    ...     def __le__(self, other):
    ...         if self.__class__ is other.__class__:
865
    ...             return self.value <= other.value
866 867 868
    ...         return NotImplemented
    ...     def __lt__(self, other):
    ...         if self.__class__ is other.__class__:
869
    ...             return self.value < other.value
870 871 872 873 874 875 876 877 878 879 880 881 882
    ...         return NotImplemented
    ...
    >>> class Grade(OrderedEnum):
    ...     A = 5
    ...     B = 4
    ...     C = 3
    ...     D = 2
    ...     F = 1
    ...
    >>> Grade.C < Grade.A
    True


883
DuplicateFreeEnum
884
^^^^^^^^^^^^^^^^^
885 886 887 888 889 890 891 892 893 894 895 896 897 898 899

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):
900 901 902 903
    ...     RED = 1
    ...     GREEN = 2
    ...     BLUE = 3
    ...     GRENE = 2
904
    ...
905 906
    Traceback (most recent call last):
    ...
907
    ValueError: aliases not allowed in DuplicateFreeEnum:  'GRENE' --> 'GREEN'
908 909 910 911

.. note::

    This is a useful example for subclassing Enum to add or change other
912
    behaviors as well as disallowing aliases.  If the only desired change is
Ezio Melotti's avatar
Ezio Melotti committed
913
    disallowing aliases, the :func:`unique` decorator can be used instead.
914 915


916
Planet
917
^^^^^^
918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943

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
944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961


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_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__`,
962
:meth:`__str__` and :meth:`__repr__`).
963 964 965 966 967 968 969 970 971 972 973 974 975 976 977


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

978
Supported ``__dunder__`` names
979
""""""""""""""""""""""""""""""
980 981 982 983 984 985 986 987 988 989

:attr:`__members__` is an :class:`OrderedDict` 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
990
""""""""""""""""""""""""""""
991 992 993 994 995 996 997 998

- ``_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
- ``_order_`` -- used in Python 2/3 code to ensure member order is consistent
  (class attribute, removed during class creation)
999 1000 1001
- ``_generate_next_value_`` -- used by the `Functional API`_ and by
  :class:`auto` to get an appropriate value for an enum member; may be
  overridden
1002

1003
.. versionadded:: 3.6 ``_missing_``, ``_order_``, ``_generate_next_value_``
1004 1005 1006 1007 1008 1009

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):
1010 1011 1012 1013
    ...     _order_ = 'RED GREEN BLUE'
    ...     RED = 1
    ...     BLUE = 3
    ...     GREEN = 2
1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024
    ...
    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.

``Enum`` member type
1025
""""""""""""""""""""
1026

Ethan Furman's avatar
Ethan Furman committed
1027 1028 1029 1030
: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
1031 1032
:class:`Enum` member you are looking for (this is another good reason to use
all-uppercase names for members)::
1033 1034 1035 1036 1037

    >>> class FieldTypes(Enum):
    ...     name = 0
    ...     value = 1
    ...     size = 2
1038
    ...
1039 1040 1041 1042 1043 1044
    >>> FieldTypes.value.size
    <FieldTypes.size: 2>
    >>> FieldTypes.size.value
    2

.. versionchanged:: 3.5
1045

1046 1047

Boolean value of ``Enum`` classes and members
1048
"""""""""""""""""""""""""""""""""""""""""""""
1049

Ethan Furman's avatar
Ethan Furman committed
1050
:class:`Enum` members that are mixed with non-:class:`Enum` types (such as
1051
:class:`int`, :class:`str`, etc.) are evaluated according to the mixed-in
Ethan Furman's avatar
Ethan Furman committed
1052 1053
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
1054 1055 1056
your class::

    def __bool__(self):
Ethan Furman's avatar
Ethan Furman committed
1057
        return bool(self.value)
1058

Ethan Furman's avatar
Ethan Furman committed
1059
:class:`Enum` classes always evaluate as :data:`True`.
1060 1061 1062


``Enum`` classes with methods
1063
"""""""""""""""""""""""""""""
1064

1065
If you give your :class:`Enum` subclass extra methods, like the `Planet`_
1066 1067
class above, those methods will show up in a :func:`dir` of the member,
but not of the class::
1068 1069 1070 1071 1072

    >>> dir(Planet)
    ['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', 'VENUS', '__class__', '__doc__', '__members__', '__module__']
    >>> dir(Planet.EARTH)
    ['__class__', '__doc__', '__module__', 'name', 'surface_gravity', 'value']
1073

1074 1075 1076 1077 1078 1079 1080 1081

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):
1082 1083 1084 1085 1086 1087
    ...     RED = auto()
    ...     GREEN = auto()
    ...     BLUE = auto()
    ...     MAGENTA = RED | BLUE
    ...     YELLOW = RED | GREEN
    ...     CYAN = GREEN | BLUE
1088 1089
    ...
    >>> Color(3)  # named combination
1090
    <Color.YELLOW: 3>
1091
    >>> Color(7)      # not named combination
1092
    <Color.CYAN|MAGENTA|BLUE|YELLOW|GREEN|RED: 7>
1093