Options Manager#

class ignis.options_manager.OptionsManager(file: str | None = None, hot_reload: bool = True)#

Bases: OptionsGroup.

This is the top-level class in the option structure. It provides support for loading and saving options to a file. Has support for hot-reloading when the file is modified externally.

Parameters:

file (str | None, default: None) -- The path to the file used for saving and loading options. Cannot be changed after initialization.
hot_reload (bool, default: True) -- Whether to enable hot-reloading.

The standard option structure must follow this format:

from ignis.options_manager import OptionsManager, OptionsGroup, TrackedList

class SomeOptions(OptionsManager):
    def __init__(self):
        super().__init__(file="PATH/TO/FILE")

    class Subgroup1(OptionsGroup):
        option1: bool = False
        option2: int = 5000

    class SomeSubgroup(OptionsGroup):
        example_option: str | None = get_something...()
        test: str = "%Y-%m-%d_%H-%M-%S.mp4"
        # using TrackedList instead of usual python list is encouraged
        some_list: TrackedList[int] = TrackedList()


    subgroup1 = Subgroup1()
    some_subgroup = SomeSubgroup()

some_options = SomeOptions()

save_to_file(file: str) → None#

Manually save options to the specified file.

Parameters:: file (str) -- The path to the file where options will be saved.
Return type:: None

load_from_file(file: str, emit: bool = True) → None#

Manually load options from the specified file.

Parameters:

file (str) -- The path to the file from which options will be loaded.
emit (bool, default: True) -- Whether to emit the changed `and :attr:`subgroup_changed signals for options in file that differ from those on self.

Return type:

None

class ignis.options_manager.OptionsGroup(*args, **kwargs)#

An options group. Implements the Singleton pattern.

signal changed#

Emitted when an option of this group has changed

Parameters:: option_name (str) -- The name of the option.

signal subgroup_changed#

Emitted when an option of a subgroup has changed

Parameters:

subgroup_name (str) -- The name of the subgroup.
option_name (str) -- The name of the option.

signal autosave#: Emitted when changes to this group or its child subgroups are going to be saved to the file.

connect_option(option_name: str, callback: Callable, *args) → None#

Connect an option change event to the specified callback.

This method serves as a replacement for the notify signal, as options are simple Python properties, not GObject properties.

Parameters:

option_name (str) -- The name of the option to connect.
callback (Callable) -- The function to invoke when the value of the option changes.

Return type:

None

Any *args will be passed to the callback.

to_dict() → dict[str, Any]#

Returns a dictionary representation of all options and subgroups.

Return type:: dict[str, Any]

apply_from_dict(data: dict[str, Any], emit: bool = True, autosave: bool = True) → None#

Apply values to options from a dictionary.

Parameters:

data (dict[str, Any]) -- A dictionary containing the values to apply.
emit (bool, default: True) -- Whether to emit the changed `and :attr:`subgroup_changed signals for options in data that differ from those on self.
autosave (bool, default: True) -- Whether to automatically save changes to the file.

Return type:

None

class ignis.options_manager.TrackedList(owner: OptionsGroup | None = None, name: str | None = None, *args)#

Bases: list.

The same as a usual Python list, but it can emit changed signal for the OptionsGroup attribute in which it is stored when the list's elements change.

from ignis.options_manager import OptionsGroup, TrackedList

class SomeGroup(OptionsGroup):
    some_list: TrackedList = TrackedList()

group = SomeGroup()
group.connect_option("some_list", lambda: print(f"changed!: {group.some_list}"))
group.some_list.append(123)

Options Manager#

This Page