0
# Core Enumerations
1
2
Basic enumeration classes that provide the foundation for creating typed constants with optional integer or string behavior. These classes are fully compatible with Python's stdlib Enum while providing enhanced functionality.
3
4
## Capabilities
5
6
### Enum
7
8
The base enumeration class for creating enumerated constants. Provides a clean way to create sets of named values with automatic iteration, membership testing, and comparison support.
9
10
```python { .api }
11
class Enum:
12
def __init__(self, value):
13
"""
14
Create an enum member.
15
16
Args:
17
value: The value to associate with this enum member
18
"""
19
20
def __new__(cls, value):
21
"""Create and return a new enum member."""
22
23
def __str__(self):
24
"""Return the name of the enum member."""
25
26
def __repr__(self):
27
"""Return the representation of the enum member."""
28
29
@property
30
def name(self):
31
"""The name of the enum member."""
32
33
@property
34
def value(self):
35
"""The value of the enum member."""
36
37
@classmethod
38
def __members__(cls):
39
"""Return a mapping of member names to members."""
40
41
def __call__(self, value):
42
"""Return the enum member matching the given value."""
43
```
44
45
#### Usage Example
46
47
```python
48
from aenum import Enum
49
50
class Color(Enum):
51
RED = 1
52
GREEN = 2
53
BLUE = 3
54
55
# Access members
56
print(Color.RED) # Color.RED
57
print(Color.RED.name) # 'RED'
58
print(Color.RED.value) # 1
59
60
# Iteration
61
for color in Color:
62
print(color)
63
64
# Membership testing
65
print(Color.RED in Color) # True
66
67
# Functional API
68
Animal = Enum('Animal', 'ANT BEE CAT DOG')
69
print(Animal.CAT) # Animal.CAT
70
```
71
72
### IntEnum
73
74
Enumeration that subclasses int, allowing enum members to be used anywhere integers are expected while maintaining enum identity and behavior.
75
76
```python { .api }
77
class IntEnum(int, Enum):
78
def __init__(self, value):
79
"""
80
Create an integer enum member.
81
82
Args:
83
value (int): Integer value for the enum member
84
"""
85
86
def __new__(cls, value):
87
"""Create and return a new integer enum member."""
88
```
89
90
#### Usage Example
91
92
```python
93
from aenum import IntEnum
94
95
class Priority(IntEnum):
96
LOW = 1
97
MEDIUM = 2
98
HIGH = 3
99
100
# Integer operations
101
print(Priority.HIGH + 1) # 4
102
print(Priority.HIGH > Priority.LOW) # True
103
print(Priority.MEDIUM * 2) # 4
104
105
# Still maintains enum identity
106
print(Priority.HIGH) # Priority.HIGH
107
print(isinstance(Priority.HIGH, int)) # True
108
```
109
110
### StrEnum
111
112
Enumeration that subclasses str, allowing enum members to be used anywhere strings are expected while maintaining enum identity and behavior. Particularly useful for API constants and serialization.
113
114
```python { .api }
115
class StrEnum(str, Enum):
116
def __init__(self, value):
117
"""
118
Create a string enum member.
119
120
Args:
121
value (str): String value for the enum member
122
"""
123
124
def __new__(cls, value):
125
"""Create and return a new string enum member."""
126
```
127
128
#### Usage Example
129
130
```python
131
from aenum import StrEnum
132
133
class Status(StrEnum):
134
PENDING = 'pending'
135
PROCESSING = 'processing'
136
COMPLETE = 'complete'
137
138
# String operations
139
print(Status.PENDING.upper()) # 'PENDING'
140
print('Status: ' + Status.PENDING) # 'Status: pending'
141
print(Status.PENDING == 'pending') # True
142
143
# JSON serialization friendly
144
import json
145
data = {'status': Status.PENDING}
146
print(json.dumps(data)) # {"status": "pending"}
147
```
148
149
### ReprEnum
150
151
Enumeration that only changes the repr() method while leaving str() and format() to the mixed-in type. Useful when you want enum identity but string behavior in most contexts.
152
153
```python { .api }
154
class ReprEnum(Enum):
155
def __repr__(self):
156
"""Return enum-style representation."""
157
158
def __str__(self):
159
"""Return the value as string."""
160
161
def __format__(self, format_spec):
162
"""Format using the value's format method."""
163
```
164
165
#### Usage Example
166
167
```python
168
from aenum import ReprEnum
169
170
class Color(ReprEnum):
171
RED = 'red'
172
GREEN = 'green'
173
BLUE = 'blue'
174
175
# Different repr vs str behavior
176
print(repr(Color.RED)) # Color.RED
177
print(str(Color.RED)) # 'red'
178
print(f"Color: {Color.RED}") # 'Color: red'
179
```
180
181
### Advanced Creation Patterns
182
183
#### Class-based Definition with Methods
184
185
```python
186
from aenum import Enum
187
188
class Planet(Enum):
189
MERCURY = (3.303e+23, 2.4397e6)
190
VENUS = (4.869e+24, 6.0518e6)
191
EARTH = (5.976e+24, 6.37814e6)
192
193
def __init__(self, mass, radius):
194
self.mass = mass # in kilograms
195
self.radius = radius # in meters
196
197
@property
198
def surface_gravity(self):
199
# universal gravitational constant (m3 kg-1 s-2)
200
G = 6.67300E-11
201
return G * self.mass / (self.radius * self.radius)
202
```
203
204
#### Functional API with Custom Values
205
206
```python
207
from aenum import Enum
208
209
# Simple functional creation
210
Color = Enum('Color', 'RED GREEN BLUE')
211
212
# With custom values
213
Color = Enum('Color', [('RED', 1), ('GREEN', 2), ('BLUE', 3)])
214
215
# From dictionary
216
color_dict = {'RED': 1, 'GREEN': 2, 'BLUE': 3}
217
Color = Enum('Color', color_dict)
218
```
219
220
## Common Patterns
221
222
### Configuration Enums
223
224
```python
225
from aenum import StrEnum, IntEnum
226
227
class LogLevel(IntEnum):
228
DEBUG = 10
229
INFO = 20
230
WARNING = 30
231
ERROR = 40
232
CRITICAL = 50
233
234
class Environment(StrEnum):
235
DEVELOPMENT = 'dev'
236
STAGING = 'staging'
237
PRODUCTION = 'prod'
238
```
239
240
### State Machines
241
242
```python
243
from aenum import Enum
244
245
class OrderStatus(Enum):
246
PENDING = 'pending'
247
CONFIRMED = 'confirmed'
248
SHIPPED = 'shipped'
249
DELIVERED = 'delivered'
250
CANCELLED = 'cancelled'
251
252
def can_transition_to(self, new_status):
253
transitions = {
254
self.PENDING: [self.CONFIRMED, self.CANCELLED],
255
self.CONFIRMED: [self.SHIPPED, self.CANCELLED],
256
self.SHIPPED: [self.DELIVERED],
257
self.DELIVERED: [],
258
self.CANCELLED: []
259
}
260
return new_status in transitions.get(self, [])
261
```