~dkuhlman/python-training-materials/Materials

<h1>8.13. <a class="reference internal" href="#module-enum" title="enum: Implementation of an enumeration class."><code class="xref py py-mod docutils literal">enum</code></a> — Support for enumerations<a class="headerlink" href="#module-enum" title="Permalink to this headline">¶</a></h1>

New in version 3.4.

</div>

Source code: <a class="reference external" href="https://hg.python.org/cpython/file/3.5/Lib/enum.py">Lib/enum.py</a>

100

101

An enumeration is a set of symbolic names (members) bound to unique,

102

constant values. Within an enumeration, the members can be compared

103

by identity, and the enumeration itself can be iterated over.

104

105

<h2>8.13.1. Module Contents<a class="headerlink" href="#module-contents" title="Permalink to this headline">¶</a></h2>

106

This module defines two enumeration classes that can be used to define unique

107

sets of names and values: <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a> and <a class="reference internal" href="#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal">IntEnum</code></a>. It also defines

108

one decorator, <a class="reference internal" href="#enum.unique" title="enum.unique"><code class="xref py py-func docutils literal">unique()</code></a>.

109

110

111

class <code class="descclassname">enum.</code><code class="descname">Enum</code><a class="headerlink" href="#enum.Enum" title="Permalink to this definition">¶</a></dt>

112

<dd>Base class for creating enumerated constants. See section

113

<a class="reference internal" href="#functional-api">Functional API</a> for an alternate construction syntax.

114

</dd></dl>

115

116

117

118

class <code class="descclassname">enum.</code><code class="descname">IntEnum</code><a class="headerlink" href="#enum.IntEnum" title="Permalink to this definition">¶</a></dt>

119

<dd>Base class for creating enumerated constants that are also

120

subclasses of <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal">int</code></a>.

121

</dd></dl>

122

123

124

125

<code class="descclassname">enum.</code><code class="descname">unique</code>()<a class="headerlink" href="#enum.unique" title="Permalink to this definition">¶</a></dt>

126

<dd>Enum class decorator that ensures only one name is bound to any one value.

127

</dd></dl>

128

129

</div>

130

131

<h2>8.13.2. Creating an Enum<a class="headerlink" href="#creating-an-enum" title="Permalink to this headline">¶</a></h2>

132

Enumerations are created using the <a class="reference internal" href="../reference/compound_stmts.html#class"><code class="xref std std-keyword docutils literal">class</code></a> syntax, which makes them

133

easy to read and write. An alternative creation method is described in

134

<a class="reference internal" href="#functional-api">Functional API</a>. To define an enumeration, subclass <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a> as

135

follows:

136

<div class="highlight-python3"><div class="highlight"><pre>>>> from enum import Enum

137

>>> class Color(Enum):

138

... red = 1

139

... green = 2

140

... blue = 3

141

...

142

</pre></div>

143

</div>

144

145

Note

146

Nomenclature

147

148

<li>The class <code class="xref py py-class docutils literal">Color</code> is an enumeration (or enum)</li>

149

<li>The attributes <code class="xref py py-attr docutils literal">Color.red</code>, <code class="xref py py-attr docutils literal">Color.green</code>, etc., are

150

enumeration members (or enum members).</li>

151

<li>The enum members have names and values (the name of

152

<code class="xref py py-attr docutils literal">Color.red</code> is <code class="docutils literal">red</code>, the value of <code class="xref py py-attr docutils literal">Color.blue</code> is

153

154

</ul>

155

</div>

156

157

Note

158

Even though we use the <a class="reference internal" href="../reference/compound_stmts.html#class"><code class="xref std std-keyword docutils literal">class</code></a> syntax to create Enums, Enums

159

are not normal Python classes. See <a class="reference internal" href="#how-are-enums-different">How are Enums different?</a> for

160

more details.

161

</div>

162

Enumeration members have human readable string representations:

163

<div class="highlight-python3"><div class="highlight"><pre>>>> print(Color.red)

164

Color.red

165

</pre></div>

166

</div>

167

...while their <code class="docutils literal">repr</code> has more information:

168

<div class="highlight-python3"><div class="highlight"><pre>>>> print(repr(Color.red))

169

<Color.red: 1>

170

</pre></div>

171

</div>

172

The type of an enumeration member is the enumeration it belongs to:

173

<div class="highlight-python3"><div class="highlight"><pre>>>> type(Color.red)

174

175

>>> isinstance(Color.green, Color)

176

True

177

>>>

178

</pre></div>

179

</div>

180

Enum members also have a property that contains just their item name:

181

182

red

183

</pre></div>

184

</div>

185

Enumerations support iteration, in definition order:

186

<div class="highlight-python3"><div class="highlight"><pre>>>> class Shake(Enum):

187

... vanilla = 7

188

... chocolate = 4

189

... cookies = 9

190

... mint = 3

191

...

192

>>> for shake in Shake:

193

... print(shake)

194

...

195

Shake.vanilla

196

Shake.chocolate

197

Shake.cookies

198

Shake.mint

199

</pre></div>

200

</div>

201

Enumeration members are hashable, so they can be used in dictionaries and sets:

202

<div class="highlight-python3"><div class="highlight"><pre>>>> apples = {}

203

>>> apples[Color.red] = 'red delicious'

204

>>> apples[Color.green] = 'granny smith'

205

>>> apples == {Color.red: 'red delicious', Color.green: 'granny smith'}

206

True

207

</pre></div>

208

</div>

209

</div>

210

211

<h2>8.13.3. Programmatic access to enumeration members and their attributes<a class="headerlink" href="#programmatic-access-to-enumeration-members-and-their-attributes" title="Permalink to this headline">¶</a></h2>

212

Sometimes it’s useful to access members in enumerations programmatically (i.e.

213

situations where <code class="docutils literal">Color.red</code> won’t do because the exact color is not known

214

at program-writing time). <code class="docutils literal">Enum</code> allows such access:

215

<div class="highlight-python3"><div class="highlight"><pre>>>> Color(1)

216

<Color.red: 1>

217

>>> Color(3)

218

<Color.blue: 3>

219

</pre></div>

220

</div>

221

If you want to access enum members by name, use item access:

222

<div class="highlight-python3"><div class="highlight"><pre>>>> Color['red']

223

<Color.red: 1>

224

>>> Color['green']

225

<Color.green: 2>

226

</pre></div>

227

</div>

228

If you have an enum member and need its <code class="xref py py-attr docutils literal">name</code> or <code class="xref py py-attr docutils literal">value</code>:

229

<div class="highlight-python3"><div class="highlight"><pre>>>> member = Color.red

230

>>> member.name

231

'red'

232

>>> member.value

233

1

234

</pre></div>

235

</div>

236

</div>

237

238

<h2>8.13.4. Duplicating enum members and values<a class="headerlink" href="#duplicating-enum-members-and-values" title="Permalink to this headline">¶</a></h2>

239

Having two enum members with the same name is invalid:

240

<div class="highlight-python3"><div class="highlight"><pre>>>> class Shape(Enum):

241

... square = 2

242

... square = 3

243

...

244

Traceback (most recent call last):

245

...

246

TypeError: Attempted to reuse key: 'square'

247

</pre></div>

248

</div>

249

However, two enum members are allowed to have the same value. Given two members

250

A and B with the same value (and A defined first), B is an alias to A. By-value

251

lookup of the value of A and B will return A. By-name lookup of B will also

252

return A:

253

254

... square = 2

255

... diamond = 1

256

... circle = 3

257

... alias_for_square = 2

258

...

259

>>> Shape.square

260

<Shape.square: 2>

261

>>> Shape.alias_for_square

262

<Shape.square: 2>

263

>>> Shape(2)

264

<Shape.square: 2>

265

</pre></div>

266

</div>

267

268

Note

269

Attempting to create a member with the same name as an already

270

defined attribute (another member, a method, etc.) or attempting to create

271

an attribute with the same name as a member is not allowed.

272

</div>

273

</div>

274

275

<h2>8.13.5. Ensuring unique enumeration values<a class="headerlink" href="#ensuring-unique-enumeration-values" title="Permalink to this headline">¶</a></h2>

276

By default, enumerations allow multiple names as aliases for the same value.

277

When this behavior isn’t desired, the following decorator can be used to

278

ensure each value is used only once in the enumeration:

279

280

<dt>

281

<code class="descclassname">@</code><code class="descclassname">enum.</code><code class="descname">unique</code></dt>

282

283

284

A <a class="reference internal" href="../reference/compound_stmts.html#class"><code class="xref std std-keyword docutils literal">class</code></a> decorator specifically for enumerations. It searches an

285

enumeration’s <code class="xref py py-attr docutils literal">__members__</code> gathering any aliases it finds; if any are

286

found <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a> is raised with the details:

287

288

>>> @unique

289

... class Mistake(Enum):

290

... one = 1

291

... two = 2

292

... three = 3

293

... four = 3

294

...

295

Traceback (most recent call last):

296

...

297

ValueError: duplicate values found in <enum 'Mistake'>: four -> three

298

</pre></div>

299

</div>

300

</div>

301

302

<h2>8.13.6. Iteration<a class="headerlink" href="#iteration" title="Permalink to this headline">¶</a></h2>

303

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

304

<div class="highlight-python3"><div class="highlight"><pre>>>> list(Shape)

305

[<Shape.square: 2>, <Shape.diamond: 1>, <Shape.circle: 3>]

306

</pre></div>

307

</div>

308

The special attribute <code class="docutils literal">__members__</code> is an ordered dictionary mapping names

309

to members. It includes all names defined in the enumeration, including the

310

aliases:

311

<div class="highlight-python3"><div class="highlight"><pre>>>> for name, member in Shape.__members__.items():

312

... name, member

313

...

314

('square', <Shape.square: 2>)

315

('diamond', <Shape.diamond: 1>)

316

('circle', <Shape.circle: 3>)

317

('alias_for_square', <Shape.square: 2>)

318

</pre></div>

319

</div>

320

The <code class="docutils literal">__members__</code> attribute can be used for detailed programmatic access to

321

the enumeration members. For example, finding all the aliases:

322

<div class="highlight-python3"><div class="highlight"><pre>>>> [name for name, member in Shape.__members__.items() if member.name != name]

323

['alias_for_square']

324

</pre></div>

325

</div>

326

</div>

327

328

<h2>8.13.7. Comparisons<a class="headerlink" href="#comparisons" title="Permalink to this headline">¶</a></h2>

329

Enumeration members are compared by identity:

330

<div class="highlight-python3"><div class="highlight"><pre>>>> Color.red is Color.red

331

True

332

>>> Color.red is Color.blue

333

False

334

>>> Color.red is not Color.blue

335

True

336

</pre></div>

337

</div>

338

Ordered comparisons between enumeration values are not supported. Enum

339

members are not integers (but see <a class="reference internal" href="#intenum">IntEnum</a> below):

340

<div class="highlight-python3"><div class="highlight"><pre>>>> Color.red < Color.blue

341

Traceback (most recent call last):

342

File "<stdin>", line 1, in <module>

343

TypeError: unorderable types: Color() < Color()

344

</pre></div>

345

</div>

346

Equality comparisons are defined though:

347

<div class="highlight-python3"><div class="highlight"><pre>>>> Color.blue == Color.red

348

False

349

>>> Color.blue != Color.red

350

True

351

>>> Color.blue == Color.blue

352

True

353

</pre></div>

354

</div>

355

Comparisons against non-enumeration values will always compare not equal

356

(again, <a class="reference internal" href="#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal">IntEnum</code></a> was explicitly designed to behave differently, see

357

below):

358

<div class="highlight-python3"><div class="highlight"><pre>>>> Color.blue == 2

359

False

360

</pre></div>

361

</div>

362

</div>

363

364

<h2>8.13.8. Allowed members and attributes of enumerations<a class="headerlink" href="#allowed-members-and-attributes-of-enumerations" title="Permalink to this headline">¶</a></h2>

365

The examples above use integers for enumeration values. Using integers is

366

short and handy (and provided by default by the <a class="reference internal" href="#functional-api">Functional API</a>), but not

367

strictly enforced. In the vast majority of use-cases, one doesn’t care what

368

the actual value of an enumeration is. But if the value is important,

369

enumerations can have arbitrary values.

370

Enumerations are Python classes, and can have methods and special methods as

371

usual. If we have this enumeration:

372

<div class="highlight-python3"><div class="highlight"><pre>>>> class Mood(Enum):

373

... funky = 1

374

... happy = 3

375

...

376

... def describe(self):

377

... # self is the member here

378

... return self.name, self.value

379

...

380

... def __str__(self):

381

... return 'my custom str! {0}'.format(self.value)

382

...

383

... @classmethod

384

... def favorite_mood(cls):

385

... # cls here is the enumeration

386

... return cls.happy

387

...

388

</pre></div>

389

</div>

390

Then:

391

<div class="highlight-python3"><div class="highlight"><pre>>>> Mood.favorite_mood()

392

<Mood.happy: 3>

393

>>> Mood.happy.describe()

394

('happy', 3)

395

>>> str(Mood.funky)

396

'my custom str! 1'

397

</pre></div>

398

</div>

399

The rules for what is allowed are as follows: names that start and end with

400

a single underscore are reserved by enum and cannot be used; all other

401

attributes defined within an enumeration will become members of this

402

enumeration, with the exception of special methods (<a class="reference internal" href="../reference/datamodel.html#object.__str__" title="object.__str__"><code class="xref py py-meth docutils literal">__str__()</code></a>,

403

<a class="reference internal" href="../reference/datamodel.html#object.__add__" title="object.__add__"><code class="xref py py-meth docutils literal">__add__()</code></a>, etc.) and descriptors (methods are also descriptors).

404

Note: if your enumeration defines <a class="reference internal" href="../reference/datamodel.html#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal">__new__()</code></a> and/or <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal">__init__()</code></a> then

405

whatever value(s) were given to the enum member will be passed into those

406

methods. See <a class="reference internal" href="#planet">Planet</a> for an example.

407

</div>

408

409

<h2>8.13.9. Restricted subclassing of enumerations<a class="headerlink" href="#restricted-subclassing-of-enumerations" title="Permalink to this headline">¶</a></h2>

410

Subclassing an enumeration is allowed only if the enumeration does not define

411

any members. So this is forbidden:

412

<div class="highlight-python3"><div class="highlight"><pre>>>> class MoreColor(Color):

413

... pink = 17

414

...

415

Traceback (most recent call last):

416

...

417

TypeError: Cannot extend enumerations

418

</pre></div>

419

</div>

420

But this is allowed:

421

<div class="highlight-python3"><div class="highlight"><pre>>>> class Foo(Enum):

422

... def some_behavior(self):

423

... pass

424

...

425

>>> class Bar(Foo):

426

... happy = 1

427

... sad = 2

428

...

429

</pre></div>

430

</div>

431

Allowing subclassing of enums that define members would lead to a violation of

432

some important invariants of types and instances. On the other hand, it makes

433

sense to allow sharing some common behavior between a group of enumerations.

434

(See <a class="reference internal" href="#orderedenum">OrderedEnum</a> for an example.)

435

</div>

436

437

<h2>8.13.10. Pickling<a class="headerlink" href="#pickling" title="Permalink to this headline">¶</a></h2>

438

Enumerations can be pickled and unpickled:

439

<div class="highlight-python3"><div class="highlight"><pre>>>> from test.test_enum import Fruit

440

>>> from pickle import dumps, loads

441

>>> Fruit.tomato is loads(dumps(Fruit.tomato))

442

True

443

</pre></div>

444

</div>

445

The usual restrictions for pickling apply: picklable enums must be defined in

446

the top level of a module, since unpickling requires them to be importable

447

from that module.

448

449

Note

450

With pickle protocol version 4 it is possible to easily pickle enums

451

nested in other classes.

452

</div>

453

It is possible to modify how Enum members are pickled/unpickled by defining

454

<a class="reference internal" href="pickle.html#object.__reduce_ex__" title="object.__reduce_ex__"><code class="xref py py-meth docutils literal">__reduce_ex__()</code></a> in the enumeration class.

455

</div>

456

457

<h2>8.13.11. Functional API<a class="headerlink" href="#functional-api" title="Permalink to this headline">¶</a></h2>

458

The <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a> class is callable, providing the following functional API:

459

<div class="highlight-python3"><div class="highlight"><pre>>>> Animal = Enum('Animal', 'ant bee cat dog')

460

>>> Animal

461

462

>>> Animal.ant

463

<Animal.ant: 1>

464

>>> Animal.ant.value

465

1

466

>>> list(Animal)

467

[<Animal.ant: 1>, <Animal.bee: 2>, <Animal.cat: 3>, <Animal.dog: 4>]

468

</pre></div>

469

</div>

470

The semantics of this API resemble <a class="reference internal" href="collections.html#collections.namedtuple" title="collections.namedtuple"><code class="xref py py-class docutils literal">namedtuple</code></a>. The first

471

argument of the call to <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a> is the name of the enumeration.

472

The second argument is the source of enumeration member names. It can be a

473

whitespace-separated string of names, a sequence of names, a sequence of

474

2-tuples with key/value pairs, or a mapping (e.g. dictionary) of names to

475

values. The last two options enable assigning arbitrary values to

476

enumerations; the others auto-assign increasing integers starting with 1 (use

477

the <code class="docutils literal">start</code> parameter to specify a different starting value). A

478

new class derived from <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a> is returned. In other words, the above

479

assignment to <code class="xref py py-class docutils literal">Animal</code> is equivalent to:

480

<div class="highlight-python3"><div class="highlight"><pre>>>> class Animal(Enum):

481

... ant = 1

482

... bee = 2

483

... cat = 3

484

... dog = 4

485

...

486

</pre></div>

487

</div>

488

The reason for defaulting to <code class="docutils literal">1</code> as the starting number and not <code class="docutils literal">0</code> is

489

that <code class="docutils literal">0</code> is <code class="docutils literal">False</code> in a boolean sense, but enum members all evaluate

490

to <code class="docutils literal">True</code>.

491

Pickling enums created with the functional API can be tricky as frame stack

492

implementation details are used to try and figure out which module the

493

enumeration is being created in (e.g. it will fail if you use a utility

494

function in separate module, and also may not work on IronPython or Jython).

495

The solution is to specify the module name explicitly as follows:

496

497

</pre></div>

498

</div>

499

500

Warning

501

If <code class="docutils literal">module</code> is not supplied, and Enum cannot determine what it is,

502

the new Enum members will not be unpicklable; to keep errors closer to

503

the source, pickling will be disabled.

504

</div>

505

The new pickle protocol 4 also, in some circumstances, relies on

506

<a class="reference internal" href="stdtypes.html#definition.__qualname__" title="definition.__qualname__"><code class="xref py py-attr docutils literal">__qualname__</code></a> being set to the location where pickle will be able

507

to find the class. For example, if the class was made available in class

508

SomeData in the global scope:

509

510

</pre></div>

511

</div>

512

The complete signature is:

513

<div class="highlight-python3"><div class="highlight"><pre>Enum(value='NewEnumName', names=<...>, *, module='...', qualname='...', type=<mixed-in class>, start=1)

514

</pre></div>

515

</div>

516

517

518

519

520

<tr class="field-odd field"><th class="field-name">value:</th><td class="field-body">What the new Enum class will record as its name.

521

</td>

522

</tr>

523

<tr class="field-even field"><th class="field-name">names:</th><td class="field-body">The Enum members. This can be a whitespace or comma separated string

524

(values will start at 1 unless otherwise specified):

525

<div class="highlight-python3"><div class="highlight"><pre>'red green blue' | 'red,green,blue' | 'red, green, blue'

526

</pre></div>

527

</div>

528

or an iterator of names:

529

<div class="highlight-python3"><div class="highlight"><pre>['red', 'green', 'blue']

530

</pre></div>

531

</div>

532

or an iterator of (name, value) pairs:

533

<div class="highlight-python3"><div class="highlight"><pre>[('cyan', 4), ('magenta', 5), ('yellow', 6)]

534

</pre></div>

535

</div>

536

or a mapping:

537

<div class="highlight-python3"><div class="highlight"><pre>{'chartreuse': 7, 'sea_green': 11, 'rosemary': 42}

538

</pre></div>

539

</div>

540

</td>

541

</tr>

542

<tr class="field-odd field"><th class="field-name">module:</th><td class="field-body">name of module where new Enum class can be found.

543

</td>

544

</tr>

545

<tr class="field-even field"><th class="field-name">qualname:</th><td class="field-body">where in module new Enum class can be found.

546

</td>

547

</tr>

548

<tr class="field-odd field"><th class="field-name">type:</th><td class="field-body">type to mix in to new Enum class.

549

</td>

550

</tr>

551

<tr class="field-even field"><th class="field-name">start:</th><td class="field-body">number to start counting at if only names are passed in.

552

</td>

553

</tr>

554

</tbody>

555

</table>

556

557

Changed in version 3.5: The start parameter was added.

558

</div>

559

</div>

560

561

<h2>8.13.12. Derived Enumerations<a class="headerlink" href="#derived-enumerations" title="Permalink to this headline">¶</a></h2>

562

563

<h3>8.13.12.1. IntEnum<a class="headerlink" href="#intenum" title="Permalink to this headline">¶</a></h3>

564

A variation of <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a> is provided which is also a subclass of

565

<a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal">int</code></a>. Members of an <a class="reference internal" href="#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal">IntEnum</code></a> can be compared to integers;

566

by extension, integer enumerations of different types can also be compared

567

to each other:

568

569

>>> class Shape(IntEnum):

570

... circle = 1

571

... square = 2

572

...

573

>>> class Request(IntEnum):

574

... post = 1

575

... get = 2

576

...

577

>>> Shape == 1

578

False

579

>>> Shape.circle == 1

580

True

581

>>> Shape.circle == Request.post

582

True

583

</pre></div>

584

</div>

585

However, they still can’t be compared to standard <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a> enumerations:

586

587

... circle = 1

588

... square = 2

589

...

590

>>> class Color(Enum):

591

... red = 1

592

... green = 2

593

...

594

>>> Shape.circle == Color.red

595

False

596

</pre></div>

597

</div>

598

<a class="reference internal" href="#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal">IntEnum</code></a> values behave like integers in other ways you’d expect:

599

<div class="highlight-python3"><div class="highlight"><pre>>>> int(Shape.circle)

600

1

601

>>> ['a', 'b', 'c'][Shape.circle]

602

'b'

603

>>> [i for i in range(Shape.square)]

604

[0, 1]

605

</pre></div>

606

</div>

607

For the vast majority of code, <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a> is strongly recommended,

608

since <a class="reference internal" href="#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal">IntEnum</code></a> breaks some semantic promises of an enumeration (by

609

being comparable to integers, and thus by transitivity to other

610

unrelated enumerations). It should be used only in special cases where

611

there’s no other choice; for example, when integer constants are

612

replaced with enumerations and backwards compatibility is required with code

613

that still expects integers.

614

</div>

615

616

<h3>8.13.12.2. Others<a class="headerlink" href="#others" title="Permalink to this headline">¶</a></h3>

617

While <a class="reference internal" href="#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal">IntEnum</code></a> is part of the <a class="reference internal" href="#module-enum" title="enum: Implementation of an enumeration class."><code class="xref py py-mod docutils literal">enum</code></a> module, it would be very

618

simple to implement independently:

619

<div class="highlight-python3"><div class="highlight"><pre>class IntEnum(int, Enum):

620

pass

621

</pre></div>

622

</div>

623

This demonstrates how similar derived enumerations can be defined; for example

624

a <code class="xref py py-class docutils literal">StrEnum</code> that mixes in <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal">str</code></a> instead of <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal">int</code></a>.

625

Some rules:

626

627

<li>When subclassing <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a>, mix-in types must appear before

628

<a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a> itself in the sequence of bases, as in the <a class="reference internal" href="#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal">IntEnum</code></a>

629

example above.</li>

630

<li>While <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a> can have members of any type, once you mix in an

631

additional type, all the members must have values of that type, e.g.

632

<a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal">int</code></a> above. This restriction does not apply to mix-ins which only

633

add methods and don’t specify another data type such as <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal">int</code></a> or

634

635

<li>When another data type is mixed in, the <code class="xref py py-attr docutils literal">value</code> attribute is not the

636

same as the enum member itself, although it is equivalent and will compare

637

equal.</li>

638

<li>%-style formatting: <cite>%s</cite> and <cite>%r</cite> call the <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a> class’s

639

<a class="reference internal" href="../reference/datamodel.html#object.__str__" title="object.__str__"><code class="xref py py-meth docutils literal">__str__()</code></a> and <a class="reference internal" href="../reference/datamodel.html#object.__repr__" title="object.__repr__"><code class="xref py py-meth docutils literal">__repr__()</code></a> respectively; other codes (such as

640

<cite>%i</cite> or <cite>%h</cite> for IntEnum) treat the enum member as its mixed-in type.</li>

641

<li><a class="reference internal" href="stdtypes.html#str.format" title="str.format"><code class="xref py py-meth docutils literal">str.format()</code></a> (or <a class="reference internal" href="functions.html#format" title="format"><code class="xref py py-func docutils literal">format()</code></a>) will use the mixed-in

642

type’s <a class="reference internal" href="../reference/datamodel.html#object.__format__" title="object.__format__"><code class="xref py py-meth docutils literal">__format__()</code></a>. If the <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a> class’s <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-func docutils literal">str()</code></a> or

643

<a class="reference internal" href="functions.html#repr" title="repr"><code class="xref py py-func docutils literal">repr()</code></a> is desired, use the <cite>!s</cite> or <cite>!r</cite> format codes.</li>

644

</ol>

645

</div>

646

</div>

647

648

<h2>8.13.13. Interesting examples<a class="headerlink" href="#interesting-examples" title="Permalink to this headline">¶</a></h2>

649

While <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a> and <a class="reference internal" href="#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal">IntEnum</code></a> are expected to cover the majority of

650

use-cases, they cannot cover them all. Here are recipes for some different

651

types of enumerations that can be used directly, or as examples for creating

652

one’s own.

653

654

<h3>8.13.13.1. AutoNumber<a class="headerlink" href="#autonumber" title="Permalink to this headline">¶</a></h3>

655

Avoids having to specify the value for each enumeration member:

656

<div class="highlight-python3"><div class="highlight"><pre>>>> class AutoNumber(Enum):

657

... def __new__(cls):

658

... value = len(cls.__members__) + 1

659

... obj = object.__new__(cls)

660

... obj._value_ = value

661

... return obj

662

...

663

>>> class Color(AutoNumber):

664

... red = ()

665

... green = ()

666

... blue = ()

667

...

668

>>> Color.green.value == 2

669

True

670

</pre></div>

671

</div>

672

673

Note

674

The <a class="reference internal" href="../reference/datamodel.html#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal">__new__()</code></a> method, if defined, is used during creation of the Enum

675

members; it is then replaced by Enum’s <a class="reference internal" href="../reference/datamodel.html#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal">__new__()</code></a> which is used after

676

class creation for lookup of existing members.

677

</div>

678

</div>

679

680

<h3>8.13.13.2. OrderedEnum<a class="headerlink" href="#orderedenum" title="Permalink to this headline">¶</a></h3>

681

An ordered enumeration that is not based on <a class="reference internal" href="#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal">IntEnum</code></a> and so maintains

682

the normal <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a> invariants (such as not being comparable to other

683

enumerations):

684

<div class="highlight-python3"><div class="highlight"><pre>>>> class OrderedEnum(Enum):

685

... def __ge__(self, other):

686

... if self.__class__ is other.__class__:

687

... return self.value >= other.value

688

... return NotImplemented

689

... def __gt__(self, other):

690

691

... return self.value > other.value

692

... return NotImplemented

693

... def __le__(self, other):

694

695

... return self.value <= other.value

696

... return NotImplemented

697

... def __lt__(self, other):

698

699

... return self.value < other.value

700

... return NotImplemented

701

...

702

>>> class Grade(OrderedEnum):

703

... A = 5

704

... B = 4

705

... C = 3

706

... D = 2

707

... F = 1

708

...

709

>>> Grade.C < Grade.A

710

True

711

</pre></div>

712

</div>

713

</div>

714

715

<h3>8.13.13.3. DuplicateFreeEnum<a class="headerlink" href="#duplicatefreeenum" title="Permalink to this headline">¶</a></h3>

716

Raises an error if a duplicate member name is found instead of creating an

717

alias:

718

<div class="highlight-python3"><div class="highlight"><pre>>>> class DuplicateFreeEnum(Enum):

719

... def __init__(self, *args):

720

... cls = self.__class__

721

... if any(self.value == e.value for e in cls):

722

... a = self.name

723

... e = cls(self.value).name

724

... raise ValueError(

725

... "aliases not allowed in DuplicateFreeEnum: %r --> %r"

726

... % (a, e))

727

...

728

>>> class Color(DuplicateFreeEnum):

729

... red = 1

730

... green = 2

731

... blue = 3

732

... grene = 2

733

...

734

Traceback (most recent call last):

735

...

736

ValueError: aliases not allowed in DuplicateFreeEnum: 'grene' --> 'green'

737

</pre></div>

738

</div>

739

740

Note

741

This is a useful example for subclassing Enum to add or change other

742

behaviors as well as disallowing aliases. If the only desired change is

743

disallowing aliases, the <a class="reference internal" href="#enum.unique" title="enum.unique"><code class="xref py py-func docutils literal">unique()</code></a> decorator can be used instead.

744

</div>

745

</div>

746

747

<h3>8.13.13.4. Planet<a class="headerlink" href="#planet" title="Permalink to this headline">¶</a></h3>

748

If <a class="reference internal" href="../reference/datamodel.html#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal">__new__()</code></a> or <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal">__init__()</code></a> is defined the value of the enum member

749

will be passed to those methods:

750

<div class="highlight-python3"><div class="highlight"><pre>>>> class Planet(Enum):

751

... MERCURY = (3.303e+23, 2.4397e6)

752

... VENUS = (4.869e+24, 6.0518e6)

753

... EARTH = (5.976e+24, 6.37814e6)

754

... MARS = (6.421e+23, 3.3972e6)

755

... JUPITER = (1.9e+27, 7.1492e7)

756

... SATURN = (5.688e+26, 6.0268e7)

757

... URANUS = (8.686e+25, 2.5559e7)

758

... NEPTUNE = (1.024e+26, 2.4746e7)

759

... def __init__(self, mass, radius):

760

... self.mass = mass # in kilograms

761

... self.radius = radius # in meters

762

... @property

763

... def surface_gravity(self):

764

... # universal gravitational constant (m3 kg-1 s-2)

765

... G = 6.67300E-11

766

... return G * self.mass / (self.radius * self.radius)

767

...

768

>>> Planet.EARTH.value

769

(5.976e+24, 6378140.0)

770

>>> Planet.EARTH.surface_gravity

771

9.802652743337129

772

</pre></div>

773

</div>

774

</div>

775

</div>

776

777

<h2>8.13.14. How are Enums different?<a class="headerlink" href="#how-are-enums-different" title="Permalink to this headline">¶</a></h2>

778

Enums have a custom metaclass that affects many aspects of both derived Enum

779

classes and their instances (members).

780

781

<h3>8.13.14.1. Enum Classes<a class="headerlink" href="#enum-classes" title="Permalink to this headline">¶</a></h3>

782

The <code class="xref py py-class docutils literal">EnumMeta</code> metaclass is responsible for providing the

783

<a class="reference internal" href="../reference/datamodel.html#object.__contains__" title="object.__contains__"><code class="xref py py-meth docutils literal">__contains__()</code></a>, <a class="reference internal" href="../reference/datamodel.html#object.__dir__" title="object.__dir__"><code class="xref py py-meth docutils literal">__dir__()</code></a>, <a class="reference internal" href="../reference/datamodel.html#object.__iter__" title="object.__iter__"><code class="xref py py-meth docutils literal">__iter__()</code></a> and other methods that

784

allow one to do things with an <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a> class that fail on a typical

785

class, such as <cite>list(Color)</cite> or <cite>some_var in Color</cite>. <code class="xref py py-class docutils literal">EnumMeta</code> is

786

responsible for ensuring that various other methods on the final <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a>

787

class are correct (such as <a class="reference internal" href="../reference/datamodel.html#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal">__new__()</code></a>, <a class="reference internal" href="pickle.html#object.__getnewargs__" title="object.__getnewargs__"><code class="xref py py-meth docutils literal">__getnewargs__()</code></a>,

788

789

</div>

790

791

<h3>8.13.14.2. Enum Members (aka instances)<a class="headerlink" href="#enum-members-aka-instances" title="Permalink to this headline">¶</a></h3>

792

The most interesting thing about Enum members is that they are singletons.

793

<code class="xref py py-class docutils literal">EnumMeta</code> creates them all while it is creating the <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a>

794

class itself, and then puts a custom <a class="reference internal" href="../reference/datamodel.html#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal">__new__()</code></a> in place to ensure

795

that no new ones are ever instantiated by returning only the existing

796

member instances.

797

</div>

798

799

<h3>8.13.14.3. Finer Points<a class="headerlink" href="#finer-points" title="Permalink to this headline">¶</a></h3>

800

<a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a> members are instances of an <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a> class, and even

801

though they are accessible as <cite>EnumClass.member</cite>, they should not be accessed

802

directly from the member as that lookup may fail or, worse, return something

803

besides the <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a> member you looking for:

804

<div class="highlight-python3"><div class="highlight"><pre>>>> class FieldTypes(Enum):

805

... name = 0

806

... value = 1

807

... size = 2

808

...

809

>>> FieldTypes.value.size

810

<FieldTypes.size: 2>

811

>>> FieldTypes.size.value

812

2

813

</pre></div>

814

</div>

815

816

Changed in version 3.5.

817

</div>

818

The <code class="xref py py-attr docutils literal">__members__</code> attribute is only available on the class.

819

If you give your <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a> subclass extra methods, like the <a class="reference internal" href="#planet">Planet</a>

820

class above, those methods will show up in a <a class="reference internal" href="functions.html#dir" title="dir"><code class="xref py py-func docutils literal">dir()</code></a> of the member,

821

but not of the class:

822

<div class="highlight-python3"><div class="highlight"><pre>>>> dir(Planet)

823

['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', 'VENUS', '__class__', '__doc__', '__members__', '__module__']

824

>>> dir(Planet.EARTH)

825

['__class__', '__doc__', '__module__', 'name', 'surface_gravity', 'value']

826

</pre></div>

827

</div>

828

The <a class="reference internal" href="../reference/datamodel.html#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal">__new__()</code></a> method will only be used for the creation of the

829

<a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a> members – after that it is replaced. Any custom <a class="reference internal" href="../reference/datamodel.html#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal">__new__()</code></a>

830

method must create the object and set the <code class="xref py py-attr docutils literal">_value_</code> attribute

831

appropriately.

832

If you wish to change how <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a> members are looked up you should either

833

write a helper function or a <a class="reference internal" href="functions.html#classmethod" title="classmethod"><code class="xref py py-func docutils literal">classmethod()</code></a> for the <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal">Enum</code></a>

834

subclass.

835

</div>

836

</div>

837

</div>

838

839

840

</div>

841

</div>

842

</div>

843

844

845

<h3><a href="../contents.html">Table Of Contents</a></h3>

846

<ul>

847

<li><a class="reference internal" href="#">8.13. <code class="docutils literal">enum</code> — Support for enumerations</a><ul>

848

<li><a class="reference internal" href="#module-contents">8.13.1. Module Contents</a></li>

849

<li><a class="reference internal" href="#creating-an-enum">8.13.2. Creating an Enum</a></li>

850

<li><a class="reference internal" href="#programmatic-access-to-enumeration-members-and-their-attributes">8.13.3. Programmatic access to enumeration members and their attributes</a></li>

851

<li><a class="reference internal" href="#duplicating-enum-members-and-values">8.13.4. Duplicating enum members and values</a></li>

852

<li><a class="reference internal" href="#ensuring-unique-enumeration-values">8.13.5. Ensuring unique enumeration values</a></li>

853

<li><a class="reference internal" href="#iteration">8.13.6. Iteration</a></li>

854

<li><a class="reference internal" href="#comparisons">8.13.7. Comparisons</a></li>

855

<li><a class="reference internal" href="#allowed-members-and-attributes-of-enumerations">8.13.8. Allowed members and attributes of enumerations</a></li>

856

<li><a class="reference internal" href="#restricted-subclassing-of-enumerations">8.13.9. Restricted subclassing of enumerations</a></li>

857

<li><a class="reference internal" href="#pickling">8.13.10. Pickling</a></li>

858

<li><a class="reference internal" href="#functional-api">8.13.11. Functional API</a></li>

859

<li><a class="reference internal" href="#derived-enumerations">8.13.12. Derived Enumerations</a><ul>

860

<li><a class="reference internal" href="#intenum">8.13.12.1. IntEnum</a></li>

861

<li><a class="reference internal" href="#others">8.13.12.2. Others</a></li>

862

</ul>

863

</li>

864

<li><a class="reference internal" href="#interesting-examples">8.13.13. Interesting examples</a><ul>

865

<li><a class="reference internal" href="#autonumber">8.13.13.1. AutoNumber</a></li>

866

<li><a class="reference internal" href="#orderedenum">8.13.13.2. OrderedEnum</a></li>

867

<li><a class="reference internal" href="#duplicatefreeenum">8.13.13.3. DuplicateFreeEnum</a></li>

868

<li><a class="reference internal" href="#planet">8.13.13.4. Planet</a></li>

869

</ul>

870

</li>

871

<li><a class="reference internal" href="#how-are-enums-different">8.13.14. How are Enums different?</a><ul>

872

<li><a class="reference internal" href="#enum-classes">8.13.14.1. Enum Classes</a></li>

873

<li><a class="reference internal" href="#enum-members-aka-instances">8.13.14.2. Enum Members (aka instances)</a></li>

874

<li><a class="reference internal" href="#finer-points">8.13.14.3. Finer Points</a></li>

875

</ul>

876

</li>

877

</ul>

878

</li>

879

</ul>

880

881

<h4>Previous topic</h4>

882

<a href="reprlib.html"

883

title="previous chapter">8.12. <code class="docutils literal">reprlib</code> — Alternate <code class="docutils literal">repr()</code> implementation</a>

884

<h4>Next topic</h4>

885

<a href="numeric.html"

886

title="next chapter">9. Numeric and Mathematical Modules</a>

887

888

889

890

<li><a href="../bugs.html">Report a Bug</a></li>

891

<li><a href="../_sources/library/enum.txt"

892

rel="nofollow">Show Source</a></li>

893

</ul>

894

</div>

895

</div>

896

</div>

897

898

</div>

899

900

<h3>Navigation</h3>

901

<ul>

902

903

<a href="../genindex.html" title="General Index"

904

>index</a></li>

905

906

<a href="../py-modindex.html" title="Python Module Index"

907

>modules</a> |</li>

908

909

<a href="numeric.html" title="9. Numeric and Mathematical Modules"

910

>next</a> |</li>

911

912

<a href="reprlib.html" title="8.12. reprlib — Alternate repr() implementation"

913

>previous</a> |</li>

914

<li><img src="../_static/py.png" alt=""

915

style="vertical-align: middle; margin-top: -1px"/></li>

916

<li><a href="https://www.python.org/">Python</a> »</li>

917

<li>

918

3.5.2

919

<a href="../index.html">Documentation </a> »

920

</li>

921

922

<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>

923

<li class="nav-item nav-item-2"><a href="datatypes.html" >8. Data Types</a> »</li>

924

925

926

927

928

929

930

931

932

933

</form>

934

</div>

935

936

937

</li>

938

939

</ul>

940

</div>

941

942

943

944

The Python Software Foundation is a non-profit corporation.

945

<a href="https://www.python.org/psf/donations/">Please donate.</a>

946

947

Last updated on Sep 23, 2016.

948

<a href="../bugs.html">Found a bug</a>?

949

950

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.3.

951

</div>

952

953

</body>

954

</html>

b'\\ No newline at end of file'

Older »