Close #18908: Keep Enum docs in their own section. Patch by Elazar Gershuni.
diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst
index 14dcfa7..3661469 100644
--- a/Doc/library/enum.rst
+++ b/Doc/library/enum.rst
@@ -36,11 +36,15 @@
... red = 1
... 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
+ - The class :class:`Color` is an *enumeration* (or *enum*)
+ - The attributes :attr:`Color.red`, :attr:`Color.green`, etc., are
+ *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::
@@ -68,13 +72,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 +128,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 +141,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
<Shape.square: 2>
@@ -151,7 +155,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 +170,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 <enum 'Mistake'>: four -> three
Iteration
-=========
+---------
Iterating over the members of an enum does not provide the aliases::
@@ -188,7 +193,7 @@
aliases::
>>> for name, member in Shape.__members__.items():
- ... name, member
+ ... name, member
...
('square', <Shape.square: 2>)
('diamond', <Shape.diamond: 1>)
@@ -252,20 +257,21 @@
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 +300,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 +309,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 +370,11 @@
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 +389,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 +401,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 +418,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 +447,7 @@
Others
-------
+^^^^^^
While :class:`IntEnum` is part of the :mod:`enum` module, it would be very
simple to implement independently::
@@ -472,7 +480,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 +489,7 @@
AutoNumber
-----------
+^^^^^^^^^^
Avoids having to specify the value for each enumeration member::
@@ -502,7 +510,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 +546,7 @@
DuplicateFreeEnum
------------------
+^^^^^^^^^^^^^^^^^
Raises an error if a duplicate member name is found instead of creating an
alias::
@@ -558,6 +566,7 @@
... green = 2
... blue = 3
... grene = 2
+ ...
Traceback (most recent call last):
...
ValueError: aliases not allowed in DuplicateFreeEnum: 'grene' --> 'green'
@@ -570,7 +579,7 @@
Planet
-------
+^^^^^^
If :meth:`__new__` or :meth:`__init__` is defined the value of the enum member
will be passed to those methods::