SunsetSettings: a type-safe, extensible settings system with inheritance.
Project description
SunsetSettings
SunsetSettings is a Python library that lets you define, load and save settings in a type-safe manner.
It is mainly intended for software where the user can change settings on the fly, for instance with a settings dialog, and those settings need to be preserved between sessions.
Features
Type safety
SunsetSettings is type-safe; that is to say, if you are holding it wrong, type checkers will tell you.
>>> from sunset import Key
>>> # Types can be inferred from the provided default value:
>>> number_of_ponies = Key(default=0)
>>> number_of_ponies
<Key[int]:(0)>
>>> number_of_ponies.set(6) # Works!
>>> number_of_ponies.set("six") # Type error!
>>> number_of_ponies.get() # Value is unchanged.
6
>>> from typing import TYPE_CHECKING
>>> if TYPE_CHECKING:
... reveal_type(number_of_ponies.get())
>>> # Revealed type is "builtins.int"
Extensibility
You can store arbitrary types in your SunsetSettings provided they implement a
simple serialization protocol. (See sunset/protocols.py
.)
>>> import re
>>> from typing import Optional, TYPE_CHECKING
>>> class Coordinates:
... def __init__(self, x: int, y: int) -> None:
... self._x = x
... self._y = y
...
... def toStr(self) -> str:
... return f"{self._x},{self._y}"
...
... @classmethod
... def fromStr(cls, value: str) -> Optional["Coordinates"]:
... m = re.match(r"(\d+),(\d+)", value)
... if m is None:
... return None
... x = int(m.group(1))
... y = int(m.group(2))
... return cls(x, y)
>>> from sunset import Key
>>> coordinates = Key(default=Coordinates(0, 0))
>>> if TYPE_CHECKING:
... reveal_type(coordinates.get())
>>> # Revealed type is "Coordinates"
Inheritance
SunsetSettings lets the user have a general set of settings that can be partially overriden for specific cases (much like your VSCode settings can be overriden by workspace, for instance). The hierarchy of inheritance can be arbitrarily deep.
>>> from sunset import Key, Settings
>>> class Animals(Settings):
... paws: Key[int] = Key(default=4)
...
>>> animals = Animals()
>>> octopuses = animals.newSection(name="octopuses")
>>> octopuses.paws.get()
4
>>> octopuses.paws.set(8)
>>> octopuses.paws.get()
8
>>> animals.paws.get()
4
Callbacks
Each setting key can be given callbacks to be called when its value changes.
>>> from sunset import Key
>>> number_of_ponies = Key(default=0)
>>> def callback(value):
... print("Pony count updated:", value)
>>> number_of_ponies.onValueChangeCall(callback)
>>> number_of_ponies.set(6)
Pony count updated: 6
Requirements
- Python 3.9 or later.
- If installing from sources:
- The
flit
build tool.
- The
Installation
Installing from PyPI (recommended)
Run:
pip install SunsetSettings
This will install the latest version of SunsetSettings, with its required dependencies.
Installing from sources
-
Download the code:
git clone https://github.com/pvaret/SunsetSettings
-
Install the library:
cd SunsetSettings ; flit install
That's it.
API documentation
The API documentation is available at https://sunsetsettings.readthedocs.io/en/latest/.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sunsetsettings-0.3.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3b4ee14583bbf1f2134e0d9da15e1b5355bc838a330e49f155ebfc8b23b4854f |
|
MD5 | d6d16dafa50d492399ccd61ea978bfff |
|
BLAKE2b-256 | 3149cad24e263ee0afddaa2c515c52c4a2836f7037dd45537044250fa5b5374b |