mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-02 11:08:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 15

Close #18908: Keep Enum docs in their own section. Patch by Elazar Gershuni.

Browse source
This commit is contained in:
Ethan Furman 2013-09-06 19:53:30 -07:00
parent f70f4a63b6
commit ed0bf8a729
1 changed files with 67 additions and 58 deletions
Download patch file Download diff file Expand all files Collapse all files

125
Doc/library/enum.rst
View file

@ -36,11 +36,15 @@ follows::
... red = 1 ... red = 1
... green = 2 ... green = 2
... blue = 3 ... blue = 3
...
**A note on nomenclature**: we call :class:`Color` an *enumeration* (or *enum*) ..note: Nomenclature
and :attr:`Color.red`, :attr:`Color.green` are *enumeration members* (or - The class :class:`Color` is an *enumeration* (or *enum*)
*enum members*). Enumeration members also have *values* (the value of - The attributes :attr:`Color.red`, :attr:`Color.green`, etc., are
:attr:`Color.red` is ``1``, etc.) *enumeration members* (or *enum members*).
- The enum members have *names* and *values* (the name of
:attr:`Color.red` is ``red``, the value of :attr:`Color.blue` is
``3``, etc.)
Enumeration members have human readable string representations:: Enumeration members have human readable string representations::
@ -68,13 +72,13 @@ Enum members also have a property that contains just their item name::
Enumerations support iteration, in definition order:: Enumerations support iteration, in definition order::
>>> class Shake(Enum): >>> class Shake(Enum):
... vanilla = 7 ... vanilla = 7
... chocolate = 4 ... chocolate = 4
... cookies = 9 ... cookies = 9
... mint = 3 ... mint = 3
... ...
>>> for shake in Shake: >>> for shake in Shake:
... print(shake) ... print(shake)
... ...
Shake.vanilla Shake.vanilla
Shake.chocolate Shake.chocolate
@ -124,8 +128,8 @@ Duplicating enum members and values
Having two enum members with the same name is invalid:: Having two enum members with the same name is invalid::
>>> class Shape(Enum): >>> class Shape(Enum):
... square = 2 ... square = 2
... square = 3 ... square = 3
... ...
Traceback (most recent call last): Traceback (most recent call last):
... ...
@ -137,10 +141,10 @@ lookup of the value of A and B will return A. By-name lookup of B will also
return A:: return A::
>>> class Shape(Enum): >>> class Shape(Enum):
... square = 2 ... square = 2
... diamond = 1 ... diamond = 1
... circle = 3 ... circle = 3
... alias_for_square = 2 ... alias_for_square = 2
... ...
>>> Shape.square >>> Shape.square
<Shape.square: 2> <Shape.square: 2>
@ -151,7 +155,7 @@ return A::
Ensuring unique enumeration values Ensuring unique enumeration values
================================== ----------------------------------
By default, enumerations allow multiple names as aliases for the same value. 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 When this behavior isn't desired, the following decorator can be used to
@ -166,17 +170,18 @@ found :exc:`ValueError` is raised with the details::
>>> from enum import Enum, unique >>> from enum import Enum, unique
>>> @unique >>> @unique
... class Mistake(Enum): ... class Mistake(Enum):
... one = 1 ... one = 1
... two = 2 ... two = 2
... three = 3 ... three = 3
... four = 3 ... four = 3
...
Traceback (most recent call last): Traceback (most recent call last):
... ...
ValueError: duplicate values found in <enum 'Mistake'>: four -> three ValueError: duplicate values found in <enum 'Mistake'>: four -> three
Iteration Iteration
========= ---------
Iterating over the members of an enum does not provide the aliases:: Iterating over the members of an enum does not provide the aliases::
@ -188,7 +193,7 @@ to members. It includes all names defined in the enumeration, including the
aliases:: aliases::
>>> for name, member in Shape.__members__.items(): >>> for name, member in Shape.__members__.items():
... name, member ... name, member
... ...
('square', <Shape.square: 2>) ('square', <Shape.square: 2>)
('diamond', <Shape.diamond: 1>) ('diamond', <Shape.diamond: 1>)
@ -252,20 +257,21 @@ Enumerations are Python classes, and can have methods and special methods as
usual. If we have this enumeration:: usual. If we have this enumeration::
>>> class Mood(Enum): >>> class Mood(Enum):
... funky = 1 ... funky = 1
... happy = 3 ... happy = 3
... ...
... def describe(self): ... def describe(self):
... # self is the member here ... # self is the member here
... return self.name, self.value ... return self.name, self.value
... ...
... def __str__(self): ... def __str__(self):
... return 'my custom str! {0}'.format(self.value) ... 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:: Then::
@ -294,7 +300,8 @@ Subclassing an enumeration is allowed only if the enumeration does not define
any members. So this is forbidden:: any members. So this is forbidden::
>>> class MoreColor(Color): >>> class MoreColor(Color):
... pink = 17 ... pink = 17
...
Traceback (most recent call last): Traceback (most recent call last):
... ...
TypeError: Cannot extend enumerations TypeError: Cannot extend enumerations
@ -302,12 +309,12 @@ any members. So this is forbidden::
But this is allowed:: But this is allowed::
>>> class Foo(Enum): >>> class Foo(Enum):
... def some_behavior(self): ... def some_behavior(self):
... pass ... pass
... ...
>>> class Bar(Foo): >>> class Bar(Foo):
... happy = 1 ... happy = 1
... sad = 2 ... sad = 2
... ...
Allowing subclassing of enums that define members would lead to a violation of Allowing subclassing of enums that define members would lead to a violation of
@ -363,10 +370,11 @@ new class derived from :class:`Enum` is returned. In other words, the above
assignment to :class:`Animal` is equivalent to:: assignment to :class:`Animal` is equivalent to::
>>> class Animals(Enum): >>> class Animals(Enum):
... ant = 1 ... ant = 1
... bee = 2 ... bee = 2
... cat = 3 ... cat = 3
... dog = 4 ... dog = 4
...
The reason for defaulting to ``1`` as the starting number and not ``0`` is 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 that ``0`` is ``False`` in a boolean sense, but enum members all evaluate
@ -381,10 +389,10 @@ The solution is to specify the module name explicitly as follows::
>>> Animals = Enum('Animals', 'ant bee cat dog', module=__name__) >>> Animals = Enum('Animals', 'ant bee cat dog', module=__name__)
Derived Enumerations Derived Enumerations
==================== --------------------
IntEnum IntEnum
------- ^^^^^^^
A variation of :class:`Enum` is provided which is also a subclass of 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; :class:`int`. Members of an :class:`IntEnum` can be compared to integers;
@ -393,12 +401,12 @@ to each other::
>>> from enum import IntEnum >>> from enum import IntEnum
>>> class Shape(IntEnum): >>> class Shape(IntEnum):
... circle = 1 ... circle = 1
... square = 2 ... square = 2
... ...
>>> class Request(IntEnum): >>> class Request(IntEnum):
... post = 1 ... post = 1
... get = 2 ... get = 2
... ...
>>> Shape == 1 >>> Shape == 1
False False
@ -410,12 +418,12 @@ to each other::
However, they still can't be compared to standard :class:`Enum` enumerations:: However, they still can't be compared to standard :class:`Enum` enumerations::
>>> class Shape(IntEnum): >>> class Shape(IntEnum):
... circle = 1 ... circle = 1
... square = 2 ... square = 2
... ...
>>> class Color(Enum): >>> class Color(Enum):
... red = 1 ... red = 1
... green = 2 ... green = 2
... ...
>>> Shape.circle == Color.red >>> Shape.circle == Color.red
False False
@ -439,7 +447,7 @@ that still expects integers.
Others Others
------ ^^^^^^
While :class:`IntEnum` is part of the :mod:`enum` module, it would be very While :class:`IntEnum` is part of the :mod:`enum` module, it would be very
simple to implement independently:: simple to implement independently::
@ -472,7 +480,7 @@ Some rules:
Interesting examples Interesting examples
==================== --------------------
While :class:`Enum` and :class:`IntEnum` are expected to cover the majority of 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 use-cases, they cannot cover them all. Here are recipes for some different
@ -481,7 +489,7 @@ one's own.
AutoNumber AutoNumber
---------- ^^^^^^^^^^
Avoids having to specify the value for each enumeration member:: Avoids having to specify the value for each enumeration member::
@ -502,7 +510,7 @@ Avoids having to specify the value for each enumeration member::
OrderedEnum OrderedEnum
----------- ^^^^^^^^^^^
An ordered enumeration that is not based on :class:`IntEnum` and so maintains 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 the normal :class:`Enum` invariants (such as not being comparable to other
@ -538,7 +546,7 @@ enumerations)::
DuplicateFreeEnum DuplicateFreeEnum
----------------- ^^^^^^^^^^^^^^^^^
Raises an error if a duplicate member name is found instead of creating an Raises an error if a duplicate member name is found instead of creating an
alias:: alias::
@ -558,6 +566,7 @@ alias::
... green = 2 ... green = 2
... blue = 3 ... blue = 3
... grene = 2 ... grene = 2
...
Traceback (most recent call last): Traceback (most recent call last):
... ...
ValueError: aliases not allowed in DuplicateFreeEnum: 'grene' --> 'green' ValueError: aliases not allowed in DuplicateFreeEnum: 'grene' --> 'green'
@ -570,7 +579,7 @@ alias::
Planet Planet
------ ^^^^^^
If :meth:`__new__` or :meth:`__init__` is defined the value of the enum member If :meth:`__new__` or :meth:`__init__` is defined the value of the enum member
will be passed to those methods:: will be passed to those methods::