0
# aenum
1

2
Advanced Enumerations (compatible with Python's stdlib Enum), NamedTuples, and NamedConstants. This library provides enhanced enumeration capabilities that extend Python's standard library functionality with features like multiple values, auto-numbering, bitwise operations, and unique constraints.
3

4
## Package Information
5

6
- **Package Name**: aenum
7
- **Language**: Python
8
- **Installation**: `pip install aenum`
9
- **Python Support**: 2.7, 3.3-3.13
10

11
## Core Imports
12

13
```python
14
from aenum import Enum, IntEnum, StrEnum, Flag, IntFlag
15
```
16

17
Basic imports for most use cases:
18

19
```python
20
from aenum import Enum, auto, unique
21
```
22

23
## Basic Usage
24

25
```python
26
from aenum import Enum, IntEnum, StrEnum, auto
27

28
# Basic enumeration
29
class Color(Enum):
30
    RED = 1
31
    GREEN = 2
32
    BLUE = 3
33

34
# String enumeration (useful for APIs)
35
class Status(StrEnum):
36
    PENDING = 'pending'
37
    PROCESSING = 'processing'
38
    COMPLETE = 'complete'
39

40
# Integer enumeration (sortable, comparable)
41
class Priority(IntEnum):
42
    LOW = 1
43
    MEDIUM = 2
44
    HIGH = 3
45

46
# Using auto for automatic value assignment
47
class Direction(Enum):
48
    NORTH = auto()
49
    SOUTH = auto()
50
    EAST = auto()
51
    WEST = auto()
52

53
# Usage examples
54
print(Color.RED)  # Color.RED
55
print(Status.PENDING)  # 'pending'
56
print(Priority.HIGH > Priority.LOW)  # True
57
print(Direction.NORTH.value)  # 1
58

59
# Functional API for simple cases
60
Animal = Enum('Animal', 'ANT BEE CAT DOG')
61
print(Animal.CAT)  # Animal.CAT
62
```
63

64
## Architecture
65

66
The aenum library is organized around these key components:
67

68
- **Core Enum Classes**: `Enum`, `IntEnum`, `StrEnum` provide the foundation with stdlib compatibility
69
- **Flag Classes**: `Flag`, `IntFlag` enable bitwise combinable enumerations
70
- **Specialized Enums**: Auto-numbering, ordering, uniqueness, and multi-value enums
71
- **NamedTuple**: Enhanced tuple implementation with named fields and default values
72
- **NamedConstant**: Immutable constant containers for configuration and settings
73
- **Utilities**: Functions for extending, converting, and manipulating enumerations
74

75
## Capabilities
76

77
### Core Enumerations
78

79
Basic enumeration classes that provide the foundation for creating typed constants with optional integer or string behavior.
80

81
```python { .api }
82
class Enum:
83
    def __init__(self, value): ...
84

85
class IntEnum(int, Enum):
86
    def __init__(self, value): ...
87

88
class StrEnum(str, Enum):
89
    def __init__(self, value): ...
90

91
class ReprEnum(Enum):
92
    def __repr__(self): ...
93
```
94

95
[Core Enumerations](./core-enums.md)
96

97
### Flags and Bitwise Operations
98

99
Flag enumerations that support bitwise operations for combining multiple values, commonly used for permissions, feature toggles, and configuration options.
100

101
```python { .api }
102
class Flag(Enum):
103
    def __or__(self, other): ...
104
    def __and__(self, other): ...
105
    def __xor__(self, other): ...
106
    def __invert__(self): ...
107

108
class IntFlag(int, Flag):
109
    def __init__(self, value): ...
110

111
class FlagBoundary(Enum):
112
    STRICT: ...
113
    CONFORM: ...
114
    EJECT: ...
115
    KEEP: ...
116
```
117

118
[Flags and Bitwise Operations](./flags.md)
119

120
### Advanced Enum Features
121

122
Specialized enumeration classes that provide automatic numbering, ordering, uniqueness constraints, and multi-value support for complex enumeration needs.
123

124
```python { .api }
125
class AutoNumberEnum(Enum):
126
    def _generate_next_value_(name, start, count, last_values): ...
127

128
class AutoEnum(Enum):
129
    """Auto-enum that uses _generate_next_value_ for missing values (Python 3 only)."""
130

131
class OrderedEnum(Enum):
132
    def __lt__(self, other): ...
133
    def __le__(self, other): ...
134
    def __gt__(self, other): ...
135
    def __ge__(self, other): ...
136

137
class UniqueEnum(Enum): ...
138

139
class MultiValueEnum(Enum): ...
140

141
class AddValueEnum(Enum):
142
    def _generate_next_value_(name, start, count, last_values): ...
143
```
144

145
[Advanced Enum Features](./advanced-enums.md)
146

147
### NamedTuple
148

149
Enhanced tuple implementation with named fields, default values, docstrings, and methods for creating structured data containers.
150

151
```python { .api }
152
def NamedTuple(typename, fields, **kwargs):
153
    """
154
    Create a new NamedTuple class.
155
    
156
    Args:
157
        typename (str): Name of the new class
158
        fields (str | list): Field names as string or list
159
        **kwargs: Additional options
160
    
161
    Returns:
162
        type: New NamedTuple class
163
    """
164

165
class TupleSize(Enum):
166
    fixed: ...
167
    minimum: ...
168
    variable: ...
169
```
170

171
[NamedTuple](./namedtuple.md)
172

173
### Utilities and Advanced Features
174

175
Helper functions, decorators, and classes for working with enumerations including uniqueness validation, runtime extension, conversion utilities, and named constants.
176

177
```python { .api }
178
def unique(enumeration):
179
    """Decorator to ensure enum members have unique values."""
180

181
def extend_enum(enumeration, name, *args, **kwds):
182
    """Add new members to an existing enumeration."""
183

184
def export(enum_class, namespace=None):
185
    """Export enum members to a namespace."""
186

187
class auto:
188
    """Placeholder class for automatic value assignment."""
189

190
class NamedConstant:
191
    """Base class for named constants."""
192

193
class constant:
194
    """Descriptor for constant values."""
195
```
196

197
[Utilities and Advanced Features](./utilities.md)
198

199
## Types
200

201
```python { .api }
202
# Core type definitions used across the API
203
EnumMeta = EnumType  # Metaclass for Enum classes
204

205
class _EnumArgSpec:
206
    args: list
207
    varargs: str
208
    varkw: str
209
    defaults: tuple
210

211
# Sentinel values
212
class _auto_null: ...
213
class no_arg: ...
214
undefined: object
215

216
# Helper types for advanced features
217
class Member: ...
218
class NonMember: ...
219
class skip: ...
220
nonmember = skip
221

222
# Property types
223
class enum_property(property): ...
224
```