📦 woodruffw / ordered_enum

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79ordered_enum
============

[![CI](https://github.com/woodruffw/ordered_enum/actions/workflows/ci.yml/badge.svg)](https://github.com/woodruffw/ordered_enum/actions/workflows/ci.yml)
[![Downloads](https://pepy.tech/badge/ordered-enum)](https://pepy.tech/project/ordered-enum)

**ordered_enum** is a small library for adding (total) orderings to `enum.Enum`s.

It provides two ordering behaviors:

* `ordered_enum.OrderedEnum`: total ordering by definition
* `ordered_enum.ValueOrderedEnum`: "total" ordering by member values

## Installation

**ordered_enum** requires Python 3.9 or newer.

```bash
pip3 install ordered_enum
```

## Usage

To use **ordered_enum**, just use `OrderedEnum` or `ValueOrderedEnum` as your parent class:

```python
from ordered_enum import OrderedEnum


class State(OrderedEnum):
    Disabled = 4
    Loaded = 3
    Waiting = 2
    Running = 1
    Dead = 0


assert(State.Disabled < State.Loaded)
assert(sorted([State.Dead, State.Waiting]) == [State.Waiting, State.Dead])
```

`OrderedEnum` doesn't require `@enum.unique` (or unique values at all); it uses the order of
definition to impose an ordering between members.

If you'd like to impose an ordering based on member values, you can use `ValueOrderedEnum` instead:

```python
import enum
from ordered_enum import ValueOrderedEnum


@enum.unique
class State(ValueOrderedEnum):
    Disabled = 4
    Loaded = 3
    Waiting = 2
    Running = 1
    Dead = 0


assert(State.Disabled > State.Loaded)
assert(sorted([State.Waiting, State.Dead]) == [State.Dead, State.Waiting])
```

`ValueOrderedEnum` **does** require unique values, which can be enforced via `@enum.unique`.
Failing to make a `ValueOrderedEnum`'s values unique will result in a silently broken ordering.

## Caveats

As mentioned above, `ordered_enum.OrderedEnum` provides an ordering of enum values based on their order
of definition in the class. This means that:

1. Enum values doesn't have to be unique for **ordered_enum** to work
2. Enum values can be heterogeneously typed
2. Moving enum values around changes their ordering

Therefore, you should either not depend on a specific ordering **or** ensure that your
order of definition is the order you'd like.