abstract_settings

The base class every settings section is built from.

Settings gives a dataclass of configuration fields three things Algan relies on: set(), which mutates in place so a section keeps its identity; override(), a context manager that restores the previous values on exit – including when the body raises; and validation at construction, so a bad value is rejected where it is written rather than deep inside a render.

Assignment is ``set()``. SETTINGS.video.frames_per_second = 60 and SETTINGS.video.set(frames_per_second=60) are the same operation, down to validation and normalization, so the shorter spelling cannot be the one that skips the checks. RayTracingSettings – which is not a subclass, and has by far the most fields – has always routed assignment this way; the dataclass sections do too.

A write only touches what changed. set() compares each field against the validated replacement by identity and leaves the untouched ones exactly as they were. Without that, setting any one field replaced every other with an equal-but-different deepcopy, so anything holding a Color from SETTINGS.style by reference silently stopped tracking the setting.

It also supports immutable presets. A frozen section (HD, PREVIEW) answers set() with a modified copy instead of mutating, which is what lets HD.set(frames_per_second=60) be a safe expression.

Sections declare initialization-only fields so that assigning one raises a message naming the environment variable to set instead of a generic unknown-key error.

A section may also declare aliases with settings_aliases() – a second spelling for a field, honoured everywhere the declared name is (construction, set(), override(), attribute read and attribute write). An alias is not a second setting: to_dict and snapshots always answer with the declared name, so a save/restore round-trips through one spelling no matter which one was written.

Classes

Settings

Base class for validated settings sections and immutable presets.

Functions

settings_aliases(**aliases)

Give a settings section a second spelling for some of its fields.

Apply it outside @dataclass, so that it wraps the __init__ that decorator generates:

@settings_aliases(fps="frames_per_second")
@dataclass
class VideoSettings(Settings):
    frames_per_second: int = 30

fps then works wherever frames_per_second does – as a constructor keyword, in set() and override(), as set_fps(...), and for reading and assigning the attribute. It stays a spelling rather than becoming a field: it is absent from to_dict(), from snapshots and from dataclasses.fields, so state that round-trips through those cannot end up carrying the same value twice under two names.

Parameters:

aliases (str)