Enum – dbzero

@dbzero.enum

The @dbzero.enum decorator and function create a persistent, type-safe enumerated type. Enums are useful for defining a set of named constants, such as states, categories, or colors.

Using dbzero enums instead of raw strings for tags or object members prevents accidental clashes and makes your data model more robust and explicit.

Signatures

You can define an enum in two ways: as a class decorator or as a direct function call.

# As a decorator
@db0.enum(values=["PENDING", "ACTIVE", "INACTIVE"])
class Status:
    pass
 
# As a function call
Color = db0.enum("Color", ["RED", "GREEN", "BLUE"])

Parameters

Name	Type	Description
name	`str`	The name for the enum type. Required for the function call; inferred from the class name when used as a decorator.
values	`list[str]`	A list of unique string names for the enum members. The order of values is preserved.
prefix	`str`	Optional. Scopes the enum definition to a specific data prefix. If `None` (default), the enum is defined in the prefix that is active at the time of creation. This allows for creating data-model-specific enums.

Return Value

Returns a new `EnumType` object. When used as a decorator, it replaces the decorated class with this `EnumType`.

Enum members are objects of type EnumValue. They are persistent, hashable, and comparable.

str(Color.RED) returns "RED".
repr(Color.RED) returns "<EnumValue Color.RED>".

Description

dbzero enums are collections of named constants that are integrated into the dbzero persistence layer. Each enum type is unique, ensuring that values from different enums are distinct, even if they share the same string name.

Accessing Members

You can access enum members by attribute, string key, or integer index.

# Access by attribute
active_status = Status.ACTIVE
 
# Access by string key
red_color = Color['RED']
 
# Access by integer index
green_color = Color[1] # Corresponds to "GREEN"

Type Safety

Enums provide type safety for tagging and querying. An object tagged with Color.RED will not be found when searching for the string "RED" or a value from a different enum like TrafficLight.RED.

Color = db0.enum("Color", ["RED", "GREEN", "BLUE"])
Palette = db0.enum("Palette", ["RED", "ORANGE", "YELLOW"])
 
# Tag two different objects
db0.tags(MemoTestClass(1)).add(Color.RED)
db0.tags(MemoTestClass(2)).add(Palette.RED)
db0.tags(MemoTestClass(3)).add("RED")
 
# Each find query returns a distinct set of objects
list(db0.find(Color.RED))    # [MemoTestClass(1)]
list(db0.find(Palette.RED))  # [MemoTestClass(2)]
list(db0.find("RED"))        # [MemoTestClass(3)]

Usage in Collections and Functions

Enum values are hashable and can be used as keys in both standard Python dictionaries and dbzero.dict collections. They can also be stored as attributes of @dbzero.memo objects and used as default arguments in functions.

# Using as a default function argument
@db0.memo
class Document:
    def __init__(self, content, status=Status.PENDING):
        self.content = content
        self.status = status
 
doc = Document("My first doc.")
assert doc.status == Status.PENDING
 
# Using as a dictionary key
color_map = db0.dict({
    Color.RED: "#FF0000",
    Color.GREEN: "#00FF00"
})
assert color_map[Color.RED] == "#FF0000"

Prefix Scoping

By providing a prefix argument, you can tie an enum's definition to a specific data prefix. This is useful for creating enums that are part of a distinct data model.

Even if enum values are created or accessed from different prefixes, they compare as equal if they originate from the same definition.

@db0.enum(values=["ADMIN", "USER", "GUEST"], prefix="auth_data")
class Role:
    pass
 
# The Role enum is now tied to the "auth_data" prefix
obj = ScopedDataClass(42) # A class scoped to a different prefix
 
# You can still tag objects from other scopes
db0.tags(obj).add(Role.ADMIN)

⚠️

An enum type with a given name can only be defined once per prefix. Attempting to redefine it with different values will raise an exception.

dict exists