orangeqs.juice.settings#

Configuration management for OrangeQS Juice.

Package Contents#

Classes#

BaseConfigurable

Base class for a sub schema of a Configurable.

Configurable

Base class for configurations that can be loaded from disk.

RuntimeData

Base class for runtime data that can be stored to and loaded from disk.

Data#

SHARED_RUNTIME_PATH

Path to the runtime directory for OrangeQS Juice, which is /var/run/juice.

SYSTEM_CONFIG_PATH

Path to the system configuration directory for OrangeQS Juice.

API#

class orangeqs.juice.settings.BaseConfigurable(/, **data: Any)#

Bases: pydantic.BaseModel

Base class for a sub schema of a Configurable.

Should be used for as a base class for fields of a Configurable class.

Examples#

class SubConfig(BaseConfigurable):
    some_setting: str = "default"

class MyConfig(Configurable):
    filename = "my_config"

    another_setting: int = 42
    sub_config: SubConfig
model_config#

‘ConfigDict(…)’

class orangeqs.juice.settings.Configurable(/, **data: Any)#

Bases: orangeqs.juice.settings._loading.BaseConfigurable

Base class for configurations that can be loaded from disk.

This method should be subclassed by any model that needs to load its configuration from disk. The filename class variable defines which files to load, which should be unique across all configurations in an OrangeQS Juice installation.

Examples#

Create a subclass of Configurable to define your configuration model:

class ExampleConfig(Configurable):
    filename = "example"

    some_setting: str = "default_value"
    another_setting: int = 42

config = ExampleConfig.load()
assert config.some_setting == "default_value"
filename: ClassVar[str]#

None

The unique filename key for this configuration class.

This name is used to look up the configuration files for this model, and will load any file that matches the pattern <priority>-<filename>.toml. It should be unique across all models in the OrangeQS Juice system.

classmethod load(cache: bool = False) → Self#

Load the configuration for this model from disk (default) or the cache.

This loads configuration files from the two types of sources:

  • The /etc/juice/config/ folder, which contains configurations by the system administrator.

  • All folders specified in the "juice.config" entry points of installed OrangeQS Juice extension, which contains configurations by the extension developers. Note that the lab package is also an extension, which is the way for users to configure the OrangeQS Juice installation.

From the above folders it loads all <filename>.toml, <filename>.d/*.toml files and merges them into a single configuration dictionary. It will merge dictionaries recursively, but will not merge lists. See How configurations are stored and loaded in the Reference guide for details, for example on how to use priority in configuration files.

Parameters#

  • cache (bool, optional): If True, return a cached configuration if available; otherwise load from from disk and update the cache. If False, always load from disk and update the cache. Defaults to False.

Returns#

  • (Self): An instance of the model with the loaded configuration.

class orangeqs.juice.settings.RuntimeData(/, **data: Any)#

Bases: orangeqs.juice.settings._loading.Configurable

Base class for runtime data that can be stored to and loaded from disk.

This base class should be subclassed by any model that needs to load/store its data from/to disk. The filename class variable defines which files to load, which should be unique across all configurations and runtime data in OrangeQS Juice.

Runtime data is stored at SHARED_RUNTIME_PATH, which is shared between all OrangeQS Juice services and users.

Examples#

Create a subclass of RuntimeData to store and load service information:

from typing import ClassVar

class ServiceInfo(RuntimeData):
    filename: ClassVar[str] = "service-info"

    state: dict[str, str] = Field(default_factory=dict)

# From my-service
service_info = ServiceInfo({
    "my-service": "running",
})
service_info.store(key="my-service")

# From another service or process
assert ServiceInfo.load()["my-service"] == "running"
store(key: str, exist_ok: bool = False) → pathlib.Path#

Store the runtime data to disk.

Will create a file in the shared runtime directory with the given key. It excludes fields that are not explicitly set or are None.

The runtime directory is defined by SHARED_RUNTIME_PATH.

Parameters#

  • key (str): The key of the runtime data file.

  • exist_ok (bool, optional): If True, do not raise an error if the file already exists. Defaults to False.

Returns#

  • (Path): The path to the stored file.

Raises#

  • (FileExistsError): If the file already exists and exist_ok is False.

See also

settings.SHARED_RUNTIME_PATH: Location where runtime data is stored.

classmethod load(cache: bool = False) → Self#

Load the runtime data from disk (default) or the cache.

This method loads the runtime data stored associated with this schema from the shared runtime directory.

The runtime directory is defined by SHARED_RUNTIME_PATH.

Parameters#

  • cache (bool, optional): If True, return a cached instance if available; otherwise load from from disk and update the cache. If False, always load from disk and update the cache. Defaults to False.

Returns#

  • (Self): An instance of the runtime data class loaded from disk (or the cache).

orangeqs.juice.settings.SHARED_RUNTIME_PATH#

‘/var/run/juice’

Path to the runtime directory for OrangeQS Juice, which is /var/run/juice.

This is where shared runtime data is stored, such as service info and kernel specs. Even though this folder might contain sensitive data, for now this folder is shared with all OrangeQS Juice services and users.

orangeqs.juice.settings.SYSTEM_CONFIG_PATH#

‘/etc/juice/config’

Path to the system configuration directory for OrangeQS Juice.