Settings Core Documentation

class bedrock_server_manager.Settings

Bases: object

Manages loading, accessing, and saving application settings.

This class acts as a single source of truth for all configuration data. It handles:

Determining appropriate application data and configuration directories based on the environment (respecting BSM_DATA_DIR).

Loading settings from a JSON configuration file (bedrock_server_manager.json).

Providing sensible default values for missing settings.

Migrating settings from older formats (e.g., script_config.json or schema v1).

Saving changes back to the configuration file.

Ensuring critical directories (e.g., for servers, backups, logs) exist.

Settings are stored in a nested dictionary structure and can be accessed programmatically using dot-notation via the get() and set() methods (e.g., settings.get('paths.servers')).

A global instance of this class, named settings, is typically used throughout the application.

config_file_name

The name of the configuration file.

Type:: str

config_path

The full path to the configuration file.

Type:: str

__init__()

Initializes the Settings object.

This constructor performs the following actions:

Determines the application’s primary data and configuration directories.

Handles migration of the configuration file name from the old script_config.json to bedrock_server_manager.json if necessary.

Retrieves the installed package version.

Loads settings from the configuration file. If the file doesn’t exist, it’s created with default settings. If an old configuration schema is detected, it’s migrated.

Ensures all necessary application directories (e.g., for servers, backups, logs) exist on the filesystem.

property default_config: dict

Provides the default configuration values for the application.

These defaults are used when a configuration file is not found or when a specific setting is missing from an existing configuration file. Paths are constructed dynamically based on the determined application data directory (see _determine_app_data_dir()).

The structure of the default configuration is as follows:

{
    "config_version": CONFIG_SCHEMA_VERSION,
    "paths": {
        "servers": "<app_data_dir>/servers",
        "content": "<app_data_dir>/content",
        "downloads": "<app_data_dir>/.downloads",
        "backups": "<app_data_dir>/backups",
        "plugins": "<app_data_dir>/plugins",
        "logs": "<app_data_dir>/.logs",
    },
    "retention": {
        "backups": 3,
        "downloads": 3,
        "logs": 3,
    },
    "logging": {
        "file_level": logging.INFO,
        "cli_level": logging.WARN,
    },
    "web": {
        "host": "127.0.0.1",
        "port": 11325,
        "token_expires_weeks": 4,
        "threads": 4,
        "theme": "dark",
    },
    "custom": {}
}

Returns:: A dictionary of default settings with a nested structure.
Return type:: dict

load()

Loads settings from the JSON configuration file.

The process is as follows:

Starts with a fresh copy of the default settings (see default_config()).

If the configuration file (bedrock_server_manager.json) doesn’t exist, it’s created with these default settings.

If the file exists, it’s read:

If the loaded configuration does not contain a config_version key, it’s assumed to be an old (v1) flat format and is migrated to the current nested (v2) structure via _migrate_v1_to_v2(). The migrated config is then reloaded.

The loaded user settings (either original v2 or migrated v1) are deeply merged on top of the default settings. This ensures that any new settings added in later application versions are present, while user-defined values are preserved.

If any error occurs during loading (e.g., JSON decoding error, OS error), a warning is logged, and the application proceeds with default settings. The configuration will be saved with current (potentially default) settings on the next call to set() or _write_config().

Finally, _ensure_dirs_exist() is called to create any missing critical application directories.

get(key: str, default: Any = None) → Any

Retrieves a setting value using dot-notation for nested access.

Example

settings.get("paths.servers") settings.get("non_existent.key", "default_value")

Parameters:

key (str) – The dot-separated configuration key (e.g., “paths.servers”).
default (Any, optional) – The value to return if the key is not found or if any part of the path does not exist. Defaults to None.

Returns:

The value associated with the key, or the default value if the key is not found or an intermediate key is not a dictionary.

Return type:

Any

set(key: str, value: Any)

Sets a configuration value using dot-notation and saves the change.

Intermediate dictionaries are created if they do not exist along the path specified by key. The configuration is only written to disk via _write_config() if the new value is different from the existing value for the given key.

Example

settings.set("retention.backups", 5) This will update the “backups” key within the “retention” dictionary and then save the entire configuration to the file.

Parameters:

key (str) – The dot-separated configuration key to set (e.g., “retention.backups”).
value (Any) – The value to associate with the key.

reload()

Reloads the settings from the configuration file.

This method re-runs the load() method, which re-reads the configuration file (specified by config_path) and updates the in-memory settings dictionary. Any external changes made to the file since the last load or save will be reflected.

property config_dir: str

The absolute path to the application’s configuration directory.

This is determined by _determine_app_config_dir(). Example: ~/.bedrock-server-manager/.config

Type:: str

property app_data_dir: str

The absolute path to the application’s main data directory.

This is determined by _determine_app_data_dir(). Example: ~/.bedrock-server-manager

Type:: str

property version: str

The installed version of the bedrock_server_manager package.

This is retrieved using get_installed_version() from bedrock_server_manager.config.const.

Type:: str