Introduction
Magic strings (status = "active") and magic numbers (if code == 200) are bugs waiting to happen. Enums give you named, type-safe constants that are easy to compare, iterate, and serialize.
The problem
# Magic strings — typos are silent bugs
status = "actve" # typo, no error
if status == "active":
...
# Magic numbers
if response.status_code == 200:
...
elif response.status_code == 404:
...
Basic Enum
from enum import Enum
class Status(Enum):
PENDING = "pending"
ACTIVE = "active"
INACTIVE = "inactive"
DELETED = "deleted"
# Usage
status = Status.ACTIVE
print(status) # Status.ACTIVE
print(status.value) # "active"
print(status.name) # "ACTIVE"
# Comparison
if status == Status.ACTIVE:
print("User is active")
# Iteration
for s in Status:
print(s.value)
StrEnum (Python 3.11+) — the modern way
from enum import StrEnum
class Status(StrEnum):
PENDING = "pending"
ACTIVE = "active"
INACTIVE = "inactive"
# StrEnum members ARE strings
status = Status.ACTIVE
print(status == "active") # True (no .value needed)
print(f"Status: {status}") # "Status: active"
StrEnum is the best choice for string-based enums — members behave like strings.
IntEnum
from enum import IntEnum
class HttpStatusCode(IntEnum):
OK = 200
NOT_FOUND = 404
SERVER_ERROR = 500
# IntEnum members ARE ints
if response.status_code == HttpStatusCode.OK:
print("Success")
print(HttpStatusCode.OK + 1) # 201 (int arithmetic works)
auto() — auto-generate values
from enum import Enum, auto
class Color(Enum):
RED = auto() # 1
GREEN = auto() # 2
BLUE = auto() # 3
Use when the values don’t matter (internal identifiers).
Unique and non-comparable
from enum import Enum, unique
@unique # raises ValueError if duplicate values
class Status(Enum):
ACTIVE = "active"
INACTIVE = "inactive"
# ACTIVE2 = "active" # ValueError: duplicate value
Methods on enums
Enums can have methods and properties:
from enum import Enum
class OrderStatus(Enum):
PENDING = "pending"
PAID = "paid"
SHIPPED = "shipped"
DELIVERED = "delivered"
@property
def is_terminal(self):
return self in (OrderStatus.DELIVERED,)
def next_status(self):
order = [OrderStatus.PENDING, OrderStatus.PAID, OrderStatus.SHIPPED, OrderStatus.DELIVERED]
idx = order.index(self)
return order[idx + 1] if idx + 1 < len(order) else None
status = OrderStatus.PAID
print(status.is_terminal) # False
print(status.next_status()) # OrderStatus.SHIPPED
Enum in dataclasses and Pydantic
from dataclasses import dataclass
from enum import StrEnum
class Role(StrEnum):
ADMIN = "admin"
USER = "user"
@dataclass
class User:
name: str
role: Role
u = User("Galvan", Role.ADMIN)
print(u.role.value) # "admin"
With Pydantic, enums are validated automatically:
from pydantic import BaseModel
from enum import StrEnum
class Role(StrEnum):
ADMIN = "admin"
USER = "user"
class User(BaseModel):
name: str
role: Role
user = User(name="Galvan", role="admin") # validates and converts
print(user.role) # Role.ADMIN
Serialization
import json
class Status(StrEnum):
ACTIVE = "active"
# StrEnum serializes naturally
json.dumps({"status": Status.ACTIVE}) # '{"status": "active"}'
# Regular Enum needs .value
json.dumps({"status": Status.ACTIVE.value}) # '{"status": "active"}'
StrEnum is JSON-friendly out of the box.
Enums in FastAPI
from fastapi import FastAPI
from enum import StrEnum
class SortOrder(StrEnum):
ASC = "asc"
DESC = "desc"
app = FastAPI()
@app.get("/items")
def list_items(sort: SortOrder = SortOrder.ASC):
# sort is validated by FastAPI; invalid values → 422
return {"sort": sort.value}
FastAPI validates enum query params automatically and shows them in Swagger docs.
Common mistakes
- Using strings instead of enums — typos are silent bugs. Enums catch them at runtime.
- Comparing with
.valueeverywhere — use==directly:if status == Status.ACTIVE. - Forgetting
@unique— duplicate values are allowed by default; use@uniqueto catch them. - Using
Enumwhen you want string behavior — useStrEnum(3.11+) for string enums. - Not iterating —
for s in Status:is great for dropdowns and validation.
Key Concepts
Enum= named constants with.valueand.nameStrEnum= enum members that are strings (3.11+)IntEnum= enum members that are intsauto()= auto-generate values@unique= prevent duplicate values- Methods/properties = enums can have behavior
What to Try Next
- Replace magic strings in your FastAPI backend with enums.
- Use enums in your Pydantic models for validation.
- Add enums to your Streamlit selectboxes for clean options.
- Combine with dataclasses for typed data structures.
FAQ
Enum vs constants (module-level variables)?
Constants (ACTIVE = "active") are just strings — no type safety, no iteration, no validation. Enums are first-class objects with methods, iteration, and type checking. Use enums for related sets of constants.
StrEnum vs Enum with string values?
StrEnum (3.11+) makes members behave like strings (status == "active" is True). Regular Enum requires .value comparison. For string-based enums, always use StrEnum.
Can I use enums as dict keys?
Yes — enums are hashable by default. my_dict[Status.ACTIVE] = "value" works. Great for mapping statuses to handlers.