Settings Core Documentation

class bedrock_server_manager.Settings(db: Database | None = None)

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 database.

  • 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 database.

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

Settings are stored in a key-value format in the database 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__(db: Database | None = None)

Initializes the Settings object.

This constructor performs the following actions:

  1. Determines the application’s primary data and configuration directories.

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

  3. Retrieves the installed package version.

  4. Loads settings from the database. If the database is empty, it’s created with default settings. If an old configuration schema is detected, it’s migrated.

  5. 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,
    },
    "custom": {}
}
Returns:

A dictionary of default settings with a nested structure.

Return type:

dict

load()

Loads settings from the database.

The process is as follows:

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

  2. If the database is empty, it’s populated with these default settings.

  3. If the database has settings, they are loaded:

    1. 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.

    2. 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.

  4. 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().

  5. 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 the database 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 database.

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 database.

This method re-runs the load() method, which re-reads the configuration from the database and updates the in-memory settings dictionary. Any external changes made to the database 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