Settings API Documentation

Provides an API for interacting with global application settings.

This module offers functions to read, write, and reload application-wide configuration values. These settings are managed by the Settings class and are typically stored in the main bedrock_server_manager.json configuration file.

The functions provided here allow other parts of the application, including plugins (via methods exposed by api_method()), to programmatically access and modify these global settings.

bedrock_server_manager.api.settings.get_global_setting(key: str, app_context: AppContext) → Dict[str, Any]

Reads a single value from the global application settings.

This function uses get() to retrieve the value associated with the given key.

Parameters:

key (str) – The dot-notation key for the setting (e.g., “paths.backups”, “web.port”).

Returns:

A dictionary with the operation result. On success: {"status": "success", "value": <retrieved_value>}. The <retrieved_value> will be None if the key does not exist in the settings. On error (unexpected): {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, Any]

Raises:

MissingArgumentError – If key is empty.

bedrock_server_manager.api.settings.get_all_global_settings(app_context: AppContext) → Dict[str, Any]

Reads the entire global application settings configuration.

Returns a copy of all currently loaded settings from the Settings instance.

Returns:

A dictionary with the operation result. On success: {"status": "success", **<all_settings_dict>}. On error (unexpected): {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, Any]

bedrock_server_manager.api.settings.set_global_setting(key: str, value: Any, app_context: AppContext) → Dict[str, Any]

Writes a value to the global application settings.

This function uses set() to update the value associated with the given key and persists the changes to the main application configuration file (e.g., bedrock_server_manager.json).

Parameters:

• key (str) – The dot-notation key for the setting to update (e.g., “web.port”, “paths.backups”).

• value (Any) – The new value to set. This value must be JSON-serializable.

Returns:

A dictionary with the operation result. On success: {"status": "success", "message": "Global setting '<key>' updated successfully."} On error: {"status": "error", "message": "<error_message>"}

Return type:

Dict[str, Any]

Raises:

• MissingArgumentError – If key is empty.

• BSMError – Can be raised by set() for issues like write errors (e.g., ConfigWriteError) or if the value is not JSON serializable.

bedrock_server_manager.api.settings.set_custom_global_setting(key: str, value: Any, app_context: AppContext) → Dict[str, Any]

Writes a custom value to the global application settings.

This function uses set() to update the value associated with the given key and persists the changes to the main application configuration file (e.g., bedrock_server_manager.json).

Parameters:

• key (str) – The key for the setting to update (e.g., “custom_dir”, “somekey”). This will be prefixed with “custom.”.

• value (Any) – The new value to set. This value must be JSON-serializable.

Returns:

A dictionary with the operation result. On success: {"status": "success", "message": "Global setting '<key>' updated successfully."} On error: {"status": "error", "message": "<error_message>"}

Return type:

Dict[str, Any]

Raises:

• MissingArgumentError – If key is empty.

• BSMError – Can be raised by set() for issues like write errors (e.g., ConfigWriteError) or if the value is not JSON serializable.

bedrock_server_manager.api.settings.reload_global_settings(app_context: AppContext) → Dict[str, str]

Forces a reload of settings and logging config from the file.

This is useful if bedrock_server_manager.json has been edited manually and the application needs to pick up the changes without restarting. It calls reload() to re-read the configuration file, and then calls setup_logging() to re-apply the logging configuration based on the (potentially) new settings.

Returns:

A dictionary with the operation result. On success: {"status": "success", "message": "Global settings and logging configuration have been reloaded."} On error: {"status": "error", "message": "<error_message>"}

Return type:

Dict[str, str]

Raises:

BSMError – Can be raised by reload() (e.g., ConfigLoadError) or by setup_logging() if critical logging settings are missing or invalid after reload.