Principle:Volcengine Verl Frozen Dataclass Config
| Knowledge Sources | |
|---|---|
| Domains | Configuration, Data_Structures, Software_Design |
| Last Updated | 2026-02-07 18:00 GMT |
Overview
A configuration design pattern that uses frozen Python dataclasses with dict-like access to provide type-safe, immutable configuration objects.
Description
Frozen Dataclass Config is a software design pattern used throughout verl for configuration management. It combines three ideas:
- Dataclass structure — Configuration fields are declared with types and defaults using Python's @dataclass decorator, enabling IDE autocompletion and static type checking
- Immutability — Fields are frozen after construction via a custom __setattr__ that raises FrozenInstanceError. Only fields explicitly listed in _mutable_fields can be changed post-init.
- Mapping interface — The class implements collections.abc.Mapping, so config objects work wherever dicts are expected (iteration, bracket access, .get() with defaults)
This pattern provides the safety of immutable config with the convenience of dict-like access, and is compatible with Hydra structured configs via the _target_ field.
Usage
Use this principle when creating new configuration classes in verl. Subclass BaseConfig, declare fields with types and defaults, and optionally specify _mutable_fields for any fields that need post-construction modification.
Theoretical Basis
Pseudo-code Logic:
# Abstract pattern (NOT real implementation)
@dataclass
class Config(Mapping):
_mutable_fields = set() # Allow-list for mutable fields
def __setattr__(self, name, value):
if name in self.__dict__ and name not in self._mutable_fields:
raise FrozenInstanceError(f"'{name}' is frozen")
super().__setattr__(name, value)
def __getitem__(self, key):
return getattr(self, key)
def __iter__(self):
return (f.name for f in fields(self))
def __len__(self):
return len(fields(self))
The key trade-off is between full immutability (Python frozen dataclass) and selective mutability (_mutable_fields). verl chooses selective mutability because some fields (e.g., runtime state) need to be set after construction.