settings—settings handling

Provides DummySettingsManager and SettingsManager (syncs to disk).

class DummySettingsManager(settings, filter_caps=False)[source]

Bases: object

An object for handling settings.

Parameters:settings,filter_caps – as taken by add().

To access and change settings, use attributes of this object. To restore a setting to its default (initial) value, delete it. To add a new setting, just set it to a value (or use add()). Note that a setting may not begin with ‘_’.

add(settings, filter_caps=False)[source]

Add more settings.

  • settings – a dict used to store the settings, or a (new-style) class with settings as attributes.
  • filter_caps – if True, ignore all settings whose names are not entirely upper-case.

Mark some settings as having changed.

Parameters:settings – any number of names of settings that have been changed.

This is for settings that can be changed internally without setting them to new values, such as appending to a list. If you do this, you should call this function to make sure that events are propagated and new values are handled properly.

on_change(setting[, after_cb][, before_cb][, source])[source]

Register callbacks for when the given setting is changed.

  • setting – the setting name, as used to change the setting (case-sensitive).
  • after_cb – function to call after the setting has changed.
  • before_cb – function to call before the setting is changed; its return value indicates whether to allow the setting to be changed. Note, however, that mutable settings may not always be prevented from changing, in which case before_cb will not be called and after_cb will.
  • source – non-None hashable object by which to group these callbacks for removal at a later time. It is important to remove all callbacks added by a world when it is removed, since they may have references to the world, keeping all its objects in memory.

Both callbacks, when called, are passed the new value of the setting (or, if it is determined that a callback takes no arguments, it is passed no arguments).


Remove callbacks registered for change events in the given group.

Parameters:source – the source argument passed to on_change() previously.

Missing sources are ignored.


Force saving all settings.

This class’s implementation does nothing.

class SettingsManager(settings, fn, save=(), filter_caps=False)[source]

Bases: engine.settings.DummySettingsManager

An object for handling settings.

  • fn – filename to save settings in.
  • save – a list containing the names of the settings to save to fn (others are stored in memory only).

Other arguments are as taken by DummySettingsManager.

All settings registered through save() will be saved to the given file whenever they are set. If you change settings internally without setting them (append to a list, for example), use dump().


Register more settings for saving to disk.

Takes any number of strings corresponding to setting names.


Force syncing to disk.

Previous topic

text—multi-line text rendering

Next topic

util—general utility functions

This Page