Property List Manager#

class PropertyListManager[source]#

Handles reading, writing, and managing configuration stored in Patcher’s property list file (self.plist_path).

A PatcherError will be raised in the event of directory creation failure or if an error occurs trying to write information to the property list.

needs_migration() → bool[source]#

Determines whether the plist file needs to be migrated.

migrate_plist() → None[source]#

Modifies existing property list files in v1 format to v2 format.

A backup file is created in the event migration fails so user settings are perserved.

get(section: str, key: str | None = None) → Dict[str, Any] | Any | None[source]#

Retrieves a value from the property list file.

If a key is provided, its value will be returned. Otherwise, the section will be returned.

Parameters:

section (str) – The section in the property list file to retrieve from.
key (str) – The key whose value should be retrieved. If None, returns the entire section.

Returns:

The value of the specified key, the full section, or None if not found.

Return type:

Optional [Any]

set(key: str, value: Any, migration: bool = False) → None[source]#

Sets a key-value pair or replaces a section in the property list file.

If value is a dictionary and the existing key is also a dictionary, it merges them.
If value is a dictionary and the existing key is a primitive, it raises an error (unless migration=True).
If value is a primitive and the existing key is a dictionary, it raises an error (unless migration=True).
Otherwise, it stores the value as a top-level key.

Parameters:

key (str) – The section or top-level key in the property list.
value (Any) – The value to assign. Can be a dictionary or a single value.
migration (bool) – If True, allows type changes (dict → primitive or primitive → dict).

Return type:

None

remove(key: str, value: str | None = None) → bool[source]#

Removes a key or a specific value from a key in the property list.

If value is None, the entire key (section) is removed.
If value is provided, only that specific value is removed from within the dictionary.

Parameters:

key (Optional [str]) – The key (or section) to remove from the property list.
value (str | None) – The specific value to remove within the key. If None, removes the entire key.

Returns:

True if removal was successful, False otherwise.

Return type:

bool

Completely resets the property list by deleting the property list file.

If the plist file exists, it is removed from disk. A new, empty plist will be created when values are next set.