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 01:49:23 2013 +0300 @@ -68,13 +68,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 +124,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 +137,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 +151,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 @@ -166,17 +166,18 @@ >>> from enum import Enum, unique >>> @unique ... class Mistake(Enum): - ... one = 1 - ... two = 2 - ... three = 3 - ... four = 3 + ... 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 +189,7 @@ aliases:: >>> for name, member in Shape.__members__.items(): - ... name, member + ... name, member ... ('square', ) ('diamond', ) @@ -252,20 +253,20 @@ usual. If we have this enumeration:: >>> class Mood(Enum): - ... funky = 1 - ... happy = 3 + ... funky = 1 + ... happy = 3 ... - ... def describe(self): - ... # self is the member here - ... return self.name, self.value + ... def describe(self): + ... # self is the member here + ... return self.name, self.value ... - ... def __str__(self): - ... return 'my custom str! {0}'.format(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 + ... @classmethod + ... def favorite_mood(cls): + ... # cls here is the enumeration + ... return cls.happy Then:: @@ -294,7 +295,7 @@ any members. So this is forbidden:: >>> class MoreColor(Color): - ... pink = 17 + ... pink = 17 Traceback (most recent call last): ... TypeError: Cannot extend enumerations @@ -302,12 +303,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 +364,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 +382,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 +394,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 +411,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 +440,7 @@ Others ------- +^^^^^^ While :class:`IntEnum` is part of the :mod:`enum` module, it would be very simple to implement independently:: @@ -472,7 +473,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 +482,7 @@ AutoNumber ----------- +^^^^^^^^^^ Avoids having to specify the value for each enumeration member:: @@ -502,7 +503,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 +539,7 @@ DuplicateFreeEnum ------------------ +^^^^^^^^^^^^^^^^^ Raises an error if a duplicate member name is found instead of creating an alias:: @@ -570,7 +571,7 @@ Planet ------- +^^^^^^ If :meth:`__new__` or :meth:`__init__` is defined the value of the enum member will be passed to those methods::