diff -r 5c7697f28ee4 Doc/library/enum.rst --- a/Doc/library/enum.rst Mon Sep 02 08:57:21 2013 -0700 +++ b/Doc/library/enum.rst Tue Sep 03 02:44:58 2013 +0300 @@ -37,10 +37,13 @@ ... green = 2 ... blue = 3 -**A note on nomenclature**: we call :class:`Color` an *enumeration* (or *enum*) -and :attr:`Color.red`, :attr:`Color.green` are *enumeration members* (or -*enum members*). Enumeration members also have *values* (the value of -:attr:`Color.red` is ``1``, etc.) +.. note:: **Nomenclature** + + - We call :class:`Color` an *enumeration* (or *enum*) + - :attr:`Color.red`, :attr:`Color.green` are *enumeration members* (or + *enum members*) + - Enumeration members also have *values* (the value of + :attr:`Color.red` is ``1``, etc.) Enumeration members have human readable string representations:: @@ -68,13 +71,13 @@ Enumerations support iteration, in definition order:: >>> class Shake(Enum): - ... vanilla = 7 - ... chocolate = 4 - ... cookies = 9 - ... mint = 3 + ... vanilla = 7 + ... chocolate = 4 + ... cookies = 9 + ... mint = 3 ... >>> for shake in Shake: - ... print(shake) + ... print(shake) ... Shake.vanilla Shake.chocolate @@ -124,8 +127,8 @@ Having two enum members with the same name is invalid:: >>> class Shape(Enum): - ... square = 2 - ... square = 3 + ... square = 2 + ... square = 3 ... Traceback (most recent call last): ... @@ -137,10 +140,10 @@ return A:: >>> class Shape(Enum): - ... square = 2 - ... diamond = 1 - ... circle = 3 - ... alias_for_square = 2 + ... square = 2 + ... diamond = 1 + ... circle = 3 + ... alias_for_square = 2 ... >>> Shape.square @@ -151,7 +154,7 @@ 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 @@ -159,24 +162,25 @@ .. 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 : 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 : four -> three Iteration -========= +--------- Iterating over the members of an enum does not provide the aliases:: @@ -188,7 +192,7 @@ aliases:: >>> for name, member in Shape.__members__.items(): - ... name, member + ... name, member ... ('square', ) ('diamond', ) @@ -251,21 +255,21 @@ 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 + 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:: @@ -294,7 +298,8 @@ any members. So this is forbidden:: >>> class MoreColor(Color): - ... pink = 17 + ... pink = 17 + ... Traceback (most recent call last): ... TypeError: Cannot extend enumerations @@ -302,12 +307,12 @@ But this is allowed:: >>> class Foo(Enum): - ... def some_behavior(self): - ... pass + ... def some_behavior(self): + ... pass ... >>> class Bar(Foo): - ... happy = 1 - ... sad = 2 + ... happy = 1 + ... sad = 2 ... Allowing subclassing of enums that define members would lead to a violation of @@ -363,10 +368,10 @@ assignment to :class:`Animal` is equivalent to:: >>> class Animals(Enum): - ... ant = 1 - ... bee = 2 - ... cat = 3 - ... dog = 4 + ... 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 @@ -381,10 +386,10 @@ >>> Animals = Enum('Animals', 'ant bee cat dog', module=__name__) Derived Enumerations -==================== +-------------------- IntEnum -------- +^^^^^^^ A variation of :class:`Enum` is provided which is also a subclass of :class:`int`. Members of an :class:`IntEnum` can be compared to integers; @@ -393,12 +398,12 @@ >>> from enum import IntEnum >>> class Shape(IntEnum): - ... circle = 1 - ... square = 2 + ... circle = 1 + ... square = 2 ... >>> class Request(IntEnum): - ... post = 1 - ... get = 2 + ... post = 1 + ... get = 2 ... >>> Shape == 1 False @@ -410,12 +415,12 @@ However, they still can't be compared to standard :class:`Enum` enumerations:: >>> class Shape(IntEnum): - ... circle = 1 - ... square = 2 + ... circle = 1 + ... square = 2 ... >>> class Color(Enum): - ... red = 1 - ... green = 2 + ... red = 1 + ... green = 2 ... >>> Shape.circle == Color.red False @@ -439,7 +444,7 @@ Others ------- +^^^^^^ While :class:`IntEnum` is part of the :mod:`enum` module, it would be very simple to implement independently:: @@ -472,7 +477,7 @@ Interesting examples -==================== +-------------------- While :class:`Enum` and :class:`IntEnum` are expected to cover the majority of use-cases, they cannot cover them all. Here are recipes for some different @@ -481,7 +486,7 @@ AutoNumber ----------- +^^^^^^^^^^ Avoids having to specify the value for each enumeration member:: @@ -502,7 +507,7 @@ 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 @@ -538,7 +543,7 @@ DuplicateFreeEnum ------------------ +^^^^^^^^^^^^^^^^^ Raises an error if a duplicate member name is found instead of creating an alias:: @@ -570,7 +575,7 @@ Planet ------- +^^^^^^ If :meth:`__new__` or :meth:`__init__` is defined the value of the enum member will be passed to those methods::