util.prefs module

Prefs: an application’s preferences – an AttributedObject (see util.attribute) saved to a file of its own, with callbacks for when a preference changes.

Created on Sep. 5, 2023

Code author: Rob Kremer <robkremer@me.com>

class util.prefs.Prefs

Bases: AttributedObject

An application’s preferences: an AttributedObject with no supertypes, saved to a file of its own (read(), save()). Setting a preference calls the callbacks registered for its key (addCallback()).

__init__()

Constructor

getSupers() → list[Prefs]
Returns:

Always an empty list – a Prefs object is a flat attribute store with no ISA/inheritance lattice of its own.

Return type:

list[Prefs]

isIndividual() → bool
Returns:

Always True – a Prefs object isn’t a TYPE in AttributedObject’s type/individual sense, it’s just a single flat attribute store, so it’s treated as an individual throughout.

Return type:

bool

classmethod read(file: str) → Prefs
Parameters:

file (str)

Returns:

Return type:

Prefs

addCallback(key: str, callback: Callable[[str, Any], None]) → int

Registers a function to be called whenever the value of the Attribute named key has changed.

Parameters:

  • key – The name of attribute to install the callback under.

  • callback – A function taking a string (the key) and a value (the updated value) to be called when the value of the key attributed has changed.

Returns:

An id int that can be used by removeCallback() to refer to this callback.

removeCallback(key: str, ID: int)

Removes a callback function from the registered callbacks.

Parameters:

  • key – The name of attribute under which the callback was originally installed by addCallback().

  • ID – The value returned from the original call to addCallback().

save(saveas: str | None = None, overwrite=True, format: str | None = None) → None
Parameters:

  • format – The serialization strategy to save with (see SerializationStrategy); by default, DEFAULT_STRATEGY.

  • saveas (str | None)

  • overwrite (bool)

__setitem__(key: str, value: Serializable | int | float | bool | str | list | dict | strdict | tuple | set | None)

Overrides AttributedObject [] assignment to accept a value, by creating and Attribute with the type of value. (AttributedObject’s assignment only accepts Attribute arguments if there is no pre-existing Attribute.)

Also calls any registered callbacks with the key and value. If a callback raises and exception, it is removed from the callback list.

Parameters:

  • key (str)

  • value (SerializableType)