Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit ed0bf8a

Browse files
ethanfurmanethanfurman
committed
Close #18908: Keep Enum docs in their own section. Patch by Elazar Gershuni.
1 parent f70f4a6 commit ed0bf8a

1 file changed

Lines changed: 67 additions & 58 deletions

File tree

‎Doc/library/enum.rst‎

Lines changed: 67 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -36,11 +36,15 @@ follows::
3636
... red = 1
3737
... green = 2
3838
... blue = 3
39+
...
3940

40-
**A note on nomenclature**: we call :class:`Color` an *enumeration* (or *enum*)
41-
and :attr:`Color.red`, :attr:`Color.green` are *enumeration members* (or
42-
*enum members*). Enumeration members also have *values* (the value of
43-
:attr:`Color.red` is ``1``, etc.)
41+
..note: Nomenclature
42+
- The class :class:`Color` is an *enumeration* (or *enum*)
43+
- The attributes :attr:`Color.red`, :attr:`Color.green`, etc., are
44+
*enumeration members* (or *enum members*).
45+
- The enum members have *names* and *values* (the name of
46+
:attr:`Color.red` is ``red``, the value of :attr:`Color.blue` is
47+
``3``, etc.)
4448

4549
Enumeration members have human readable string representations::
4650

@@ -68,13 +72,13 @@ Enum members also have a property that contains just their item name::
6872
Enumerations support iteration, in definition order::
6973

7074
>>> class Shake(Enum):
71-
... vanilla = 7
72-
... chocolate = 4
73-
... cookies = 9
74-
... mint = 3
75+
... vanilla = 7
76+
... chocolate = 4
77+
... cookies = 9
78+
... mint = 3
7579
...
7680
>>> for shake in Shake:
77-
... print(shake)
81+
... print(shake)
7882
...
7983
Shake.vanilla
8084
Shake.chocolate
@@ -124,8 +128,8 @@ Duplicating enum members and values
124128
Having two enum members with the same name is invalid::
125129

126130
>>> class Shape(Enum):
127-
... square = 2
128-
... square = 3
131+
... square = 2
132+
... square = 3
129133
...
130134
Traceback (most recent call last):
131135
...
@@ -137,10 +141,10 @@ lookup of the value of A and B will return A. By-name lookup of B will also
137141
return A::
138142

139143
>>> class Shape(Enum):
140-
... square = 2
141-
... diamond = 1
142-
... circle = 3
143-
... alias_for_square = 2
144+
... square = 2
145+
... diamond = 1
146+
... circle = 3
147+
... alias_for_square = 2
144148
...
145149
>>> Shape.square
146150
<Shape.square: 2>
@@ -151,7 +155,7 @@ return A::
151155

152156

153157
Ensuring unique enumeration values
154-
==================================
158+
----------------------------------
155159

156160
By default, enumerations allow multiple names as aliases for the same value.
157161
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::
166170
>>> from enum import Enum, unique
167171
>>> @unique
168172
... class Mistake(Enum):
169-
... one = 1
170-
... two = 2
171-
... three = 3
172-
... four = 3
173+
... one = 1
174+
... two = 2
175+
... three = 3
176+
... four = 3
177+
...
173178
Traceback (most recent call last):
174179
...
175180
ValueError: duplicate values found in <enum 'Mistake'>: four -> three
176181

177182

178183
Iteration
179-
=========
184+
---------
180185

181186
Iterating over the members of an enum does not provide the aliases::
182187

@@ -188,7 +193,7 @@ to members. It includes all names defined in the enumeration, including the
188193
aliases::
189194

190195
>>> for name, member in Shape.__members__.items():
191-
... name, member
196+
... name, member
192197
...
193198
('square', <Shape.square: 2>)
194199
('diamond', <Shape.diamond: 1>)
@@ -252,20 +257,21 @@ Enumerations are Python classes, and can have methods and special methods as
252257
usual. If we have this enumeration::
253258

254259
>>> class Mood(Enum):
255-
... funky = 1
256-
... happy = 3
260+
... funky = 1
261+
... happy = 3
262+
...
263+
... def describe(self):
264+
... # self is the member here
265+
... return self.name, self.value
257266
...
258-
... def describe(self):
259-
... # self is the member here
260-
... return self.name, self.value
267+
... def __str__(self):
268+
... return 'my custom str! {0}'.format(self.value)
261269
...
262-
... def __str__(self):
263-
... return 'my custom str! {0}'.format(self.value)
270+
... @classmethod
271+
... def favorite_mood(cls):
272+
... # cls here is the enumeration
273+
... return cls.happy
264274
...
265-
... @classmethod
266-
... def favorite_mood(cls):
267-
... # cls here is the enumeration
268-
... return cls.happy
269275

270276
Then::
271277

@@ -294,20 +300,21 @@ Subclassing an enumeration is allowed only if the enumeration does not define
294300
any members. So this is forbidden::
295301

296302
>>> class MoreColor(Color):
297-
... pink = 17
303+
... pink = 17
304+
...
298305
Traceback (most recent call last):
299306
...
300307
TypeError: Cannot extend enumerations
301308

302309
But this is allowed::
303310

304311
>>> class Foo(Enum):
305-
... def some_behavior(self):
306-
... pass
312+
... def some_behavior(self):
313+
... pass
307314
...
308315
>>> class Bar(Foo):
309-
... happy = 1
310-
... sad = 2
316+
... happy = 1
317+
... sad = 2
311318
...
312319

313320
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
363370
assignment to :class:`Animal` is equivalent to::
364371

365372
>>> class Animals(Enum):
366-
... ant = 1
367-
... bee = 2
368-
... cat = 3
369-
... dog = 4
373+
... ant = 1
374+
... bee = 2
375+
... cat = 3
376+
... dog = 4
377+
...
370378

371379
The reason for defaulting to ``1`` as the starting number and not ``0`` is
372380
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::
381389
>>> Animals = Enum('Animals', 'ant bee cat dog', module=__name__)
382390

383391
Derived Enumerations
384-
====================
392+
--------------------
385393

386394
IntEnum
387-
-------
395+
^^^^^^^
388396

389397
A variation of :class:`Enum` is provided which is also a subclass of
390398
:class:`int`. Members of an :class:`IntEnum` can be compared to integers;
@@ -393,12 +401,12 @@ to each other::
393401

394402
>>> from enum import IntEnum
395403
>>> class Shape(IntEnum):
396-
... circle = 1
397-
... square = 2
404+
... circle = 1
405+
... square = 2
398406
...
399407
>>> class Request(IntEnum):
400-
... post = 1
401-
... get = 2
408+
... post = 1
409+
... get = 2
402410
...
403411
>>> Shape == 1
404412
False
@@ -410,12 +418,12 @@ to each other::
410418
However, they still can't be compared to standard :class:`Enum` enumerations::
411419

412420
>>> class Shape(IntEnum):
413-
... circle = 1
414-
... square = 2
421+
... circle = 1
422+
... square = 2
415423
...
416424
>>> class Color(Enum):
417-
... red = 1
418-
... green = 2
425+
... red = 1
426+
... green = 2
419427
...
420428
>>> Shape.circle == Color.red
421429
False
@@ -439,7 +447,7 @@ that still expects integers.
439447

440448

441449
Others
442-
------
450+
^^^^^^
443451

444452
While :class:`IntEnum` is part of the :mod:`enum` module, it would be very
445453
simple to implement independently::
@@ -472,7 +480,7 @@ Some rules:
472480

473481

474482
Interesting examples
475-
====================
483+
--------------------
476484

477485
While :class:`Enum` and :class:`IntEnum` are expected to cover the majority of
478486
use-cases, they cannot cover them all. Here are recipes for some different
@@ -481,7 +489,7 @@ one's own.
481489

482490

483491
AutoNumber
484-
----------
492+
^^^^^^^^^^
485493

486494
Avoids having to specify the value for each enumeration member::
487495

@@ -502,7 +510,7 @@ Avoids having to specify the value for each enumeration member::
502510

503511

504512
OrderedEnum
505-
-----------
513+
^^^^^^^^^^^
506514

507515
An ordered enumeration that is not based on :class:`IntEnum` and so maintains
508516
the normal :class:`Enum` invariants (such as not being comparable to other
@@ -538,7 +546,7 @@ enumerations)::
538546

539547

540548
DuplicateFreeEnum
541-
-----------------
549+
^^^^^^^^^^^^^^^^^
542550

543551
Raises an error if a duplicate member name is found instead of creating an
544552
alias::
@@ -558,6 +566,7 @@ alias::
558566
... green = 2
559567
... blue = 3
560568
... grene = 2
569+
...
561570
Traceback (most recent call last):
562571
...
563572
ValueError: aliases not allowed in DuplicateFreeEnum: 'grene' --> 'green'
@@ -570,7 +579,7 @@ alias::
570579

571580

572581
Planet
573-
------
582+
^^^^^^
574583

575584
If :meth:`__new__` or :meth:`__init__` is defined the value of the enum member
576585
will be passed to those methods::

0 commit comments

Comments
 (0)