`gmuse.config`#

Configuration management for gmuse.

This module handles loading, validation, and merging of configuration from multiple sources:

CLI flags (highest priority)
config.toml file
Environment variables
Defaults (lowest priority)

The configuration is represented as a dictionary (ConfigDict) with string keys and values of various types depending on the setting.

Module Contents#

Functions#

`get_config_path`	Get the path to the configuration file using XDG Base Directory specification.
`load_config`	Load configuration from TOML file.
`load_config_raw`	Load raw config file contents as text.
`parse_config_value`	Parse a CLI-provided raw value according to the expected key type.
`_validate_integer_range`	Validate an integer config value is within the allowed range.
`_validate_float_range`	Validate a float config value is within the allowed range.
`_validate_string_choice`	Validate a string config value is one of the allowed choices.
`_validate_boolean`	Validate a config value is a boolean.
`_validate_optional_string`	Validate a config value is a string or None.
`_parse_env_int`	Parse an integer environment variable.
`_parse_env_float`	Parse a float environment variable.
`validate_config`	Validate configuration values.
`merge_config`	Merge configuration from multiple sources with priority.
`_load_toml_document`	Load a TOML document for round-trip editing.
`_atomic_write_text`
`update_config_key`	Update (or remove) a single key in the global config file.
`get_env_config`	Load configuration from environment variables.

Data#

`logger`
`ConfigDict`	Type alias for configuration dictionaries.
`VALID_FORMATS`	Allowed values for the ‘format’ configuration option.
`HISTORY_DEPTH_MIN`
`HISTORY_DEPTH_MAX`	Valid range for history_depth configuration.
`TIMEOUT_MIN`
`TIMEOUT_MAX`	Valid range for timeout configuration (in seconds).
`TEMPERATURE_MIN`
`TEMPERATURE_MAX`	Valid range for temperature configuration.
`MAX_TOKENS_MIN`
`MAX_TOKENS_MAX`	Valid range for max_tokens configuration.
`MAX_DIFF_BYTES_MIN`
`MAX_DIFF_BYTES_MAX`	Valid range for max_diff_bytes configuration.
`MAX_MESSAGE_LENGTH_MIN`
`MAX_MESSAGE_LENGTH_MAX`	Valid range for max_message_length configuration.
`MAX_CHARS_MIN`
`MAX_CHARS_MAX`	Valid range for max_chars configuration (characters).
`CHARS_PER_TOKEN_MIN`
`CHARS_PER_TOKEN_MAX`	Valid range for chars_per_token configuration.
`BRANCH_MAX_LENGTH_MIN`
`BRANCH_MAX_LENGTH_MAX`	Valid range for branch_max_length configuration.
`DEFAULTS`	Default configuration values used when no override is provided.
`ALLOWED_CONFIG_KEYS`	Allowlist of configuration keys that can be set via the CLI.
`ENV_VAR_BY_KEY`	Mapping from config keys to their overriding environment variables.

API#

gmuse.config.logger = 'get_logger(...)'#

gmuse.config.ConfigDict = None#: Type alias for configuration dictionaries.

gmuse.config.VALID_FORMATS: Final[frozenset[str]] = 'frozenset(...)'#: Allowed values for the ‘format’ configuration option.

gmuse.config.HISTORY_DEPTH_MIN: Final[int] = 0#

gmuse.config.HISTORY_DEPTH_MAX: Final[int] = 50#: Valid range for history_depth configuration.

gmuse.config.TIMEOUT_MIN: Final[int] = 5#

gmuse.config.TIMEOUT_MAX: Final[int] = 300#: Valid range for timeout configuration (in seconds).

gmuse.config.TEMPERATURE_MIN: Final[float] = 0.0#

gmuse.config.TEMPERATURE_MAX: Final[float] = 2.0#: Valid range for temperature configuration.

gmuse.config.MAX_TOKENS_MIN: Final[int] = 1#

gmuse.config.MAX_TOKENS_MAX: Final[int] = 100000#: Valid range for max_tokens configuration.

gmuse.config.MAX_DIFF_BYTES_MIN: Final[int] = 1000#

gmuse.config.MAX_DIFF_BYTES_MAX: Final[int] = 10000000#: Valid range for max_diff_bytes configuration.

gmuse.config.MAX_MESSAGE_LENGTH_MIN: Final[int] = 10#

gmuse.config.MAX_MESSAGE_LENGTH_MAX: Final[int] = 10000#: Valid range for max_message_length configuration.

gmuse.config.MAX_CHARS_MIN: Final[int] = 1#

gmuse.config.MAX_CHARS_MAX: Final[int] = 500#: Valid range for max_chars configuration (characters).

gmuse.config.CHARS_PER_TOKEN_MIN: Final[int] = 1#

gmuse.config.CHARS_PER_TOKEN_MAX: Final[int] = 10#: Valid range for chars_per_token configuration.

gmuse.config.BRANCH_MAX_LENGTH_MIN: Final[int] = 20#

gmuse.config.BRANCH_MAX_LENGTH_MAX: Final[int] = 200#: Valid range for branch_max_length configuration.

gmuse.config.DEFAULTS: Final[gmuse.config.ConfigDict] = None#: Default configuration values used when no override is provided.

gmuse.config.ALLOWED_CONFIG_KEYS: Final[frozenset[str]] = 'frozenset(...)'#: Allowlist of configuration keys that can be set via the CLI.

gmuse.config.ENV_VAR_BY_KEY: Final[dict[str, str]] = None#: Mapping from config keys to their overriding environment variables.

gmuse.config.get_config_path() → pathlib.Path#

Get the path to the configuration file using XDG Base Directory specification.

Returns: Path to config.toml (e.g., ~/.config/gmuse/config.toml)

Example: >>> config_path = get_config_path() >>> print(config_path) /home/user/.config/gmuse/config.toml

gmuse.config.load_config(config_path: Optional[pathlib.Path] = None) → gmuse.config.ConfigDict#

Load configuration from TOML file.

Args: config_path: Path to config file, defaults to XDG location

Returns: Dictionary of configuration values (empty if file doesn’t exist)

Raises: ConfigError: If TOML file is invalid or cannot be read

Example: >>> config = load_config() >>> print(config.get(“model”)) gpt-4

gmuse.config.load_config_raw(config_path: Optional[pathlib.Path] = None) → str | None#

Load raw config file contents as text.

This is used by gmuse config view to display the file contents verbatim while still providing clear errors for unreadable files.

Args: config_path: Path to config file, defaults to XDG location.

Returns: The file contents if the file exists, otherwise None.

Raises: ConfigError: If the file exists but cannot be read.

gmuse.config.parse_config_value(key: str, raw: str) → Any#

Parse a CLI-provided raw value according to the expected key type.

Args: key: Configuration key (must be in DEFAULTS). raw: Raw user-provided value string.

Returns: Parsed Python value.

Raises: ConfigError: If the key is unknown or the value cannot be parsed.

gmuse.config._validate_integer_range(config: gmuse.config.ConfigDict, key: str, min_val: int, max_val: int) → None#

Validate an integer config value is within the allowed range.

Args: config: Configuration dictionary key: Configuration key to validate min_val: Minimum allowed value (inclusive) max_val: Maximum allowed value (inclusive)

Raises: ConfigError: If value is not an integer or out of range

gmuse.config._validate_float_range(config: gmuse.config.ConfigDict, key: str, min_val: float, max_val: float) → None#

Validate a float config value is within the allowed range.

Args: config: Configuration dictionary key: Configuration key to validate min_val: Minimum allowed value (inclusive) max_val: Maximum allowed value (inclusive)

Raises: ConfigError: If value is not a number or out of range

gmuse.config._validate_string_choice(config: gmuse.config.ConfigDict, key: str, valid_choices: frozenset[str], allow_none: bool = False) → None#

Validate a string config value is one of the allowed choices.

Args: config: Configuration dictionary key: Configuration key to validate valid_choices: Set of allowed string values allow_none: Whether None is a valid value

Raises: ConfigError: If value is not a string or not in valid choices

gmuse.config._validate_boolean(config: gmuse.config.ConfigDict, key: str) → None#

Validate a config value is a boolean.

Args: config: Configuration dictionary key: Configuration key to validate

Raises: ConfigError: If value is not a boolean

gmuse.config._validate_optional_string(config: gmuse.config.ConfigDict, key: str) → None#

Validate a config value is a string or None.

Args: config: Configuration dictionary key: Configuration key to validate

Raises: ConfigError: If value is not a string or None

gmuse.config._parse_env_int(env_var: str, config_key: str) → tuple[str, int] | None#

Parse an integer environment variable.

Args: env_var: Environment variable name (e.g., “GMUSE_TIMEOUT”) config_key: Configuration key name (e.g., “timeout”)

Returns: Tuple of (config_key, parsed_value) if valid, None otherwise

gmuse.config._parse_env_float(env_var: str, config_key: str) → tuple[str, float] | None#

Parse a float environment variable.

Args: env_var: Environment variable name (e.g., “GMUSE_TEMPERATURE”) config_key: Configuration key name (e.g., “temperature”)

Returns: Tuple of (config_key, parsed_value) if valid, None otherwise

gmuse.config.validate_config(config: gmuse.config.ConfigDict) → None#

Validate configuration values.

Checks that all configuration values are of the correct type and within valid ranges. Unknown keys are logged as warnings but do not cause errors.

Args: config: Configuration dictionary to validate

Raises: ConfigError: If any configuration value is invalid

Example: >>> config = {“history_depth”: 5, “format”: “conventional”} >>> validate_config(config) # No error >>> config = {“history_depth”: -1} >>> validate_config(config) # Raises ConfigError

gmuse.config.merge_config(cli_args: Optional[gmuse.config.ConfigDict] = None, config_file: Optional[gmuse.config.ConfigDict] = None, env_vars: Optional[gmuse.config.ConfigDict] = None) → gmuse.config.ConfigDict#

Merge configuration from multiple sources with priority.

Priority (highest to lowest):

CLI arguments (cli_args)
Environment variables (env_vars)
Config file (config_file)
Defaults (DEFAULTS)

Args: cli_args: Configuration from CLI flags config_file: Configuration from config.toml env_vars: Configuration from environment variables

Returns: Merged configuration dictionary

Example: >>> cli = {“model”: “gpt-4”} >>> file = {“model”: “claude-3”, “format”: “conventional”} >>> merged = merge_config(cli_args=cli, config_file=file) >>> print(merged[“model”]) # CLI wins gpt-4 >>> print(merged[“format”]) # File value used conventional

gmuse.config._load_toml_document(config_path: pathlib.Path)#

Load a TOML document for round-trip editing.

Raises: ConfigError: If the file cannot be read or TOML is invalid.

gmuse.config._atomic_write_text(path: pathlib.Path, text: str) → None#

gmuse.config.update_config_key(key: str, value: Any, config_path: Optional[pathlib.Path] = None) → pathlib.Path#

Update (or remove) a single key in the global config file.

This preserves unrelated settings and comments by using tomlkit round-trip editing and writes the file atomically.

Args: key: Config key to set. value: Parsed value. config_path: Optional path override (defaults to XDG location).

Returns: The path that was written.

Raises: ConfigError: On read/write errors or invalid TOML.

gmuse.config.get_env_config() → gmuse.config.ConfigDict#

Load configuration from environment variables.

Environment variables: - GMUSE_MODEL: Model name - GMUSE_FORMAT: Message format - GMUSE_HISTORY_DEPTH: Number of commits for context - GMUSE_TIMEOUT: Request timeout in seconds - GMUSE_COPY: Copy to clipboard (true/false) - GMUSE_LEARNING: Enable learning mode (true/false) - GMUSE_LOG_FILE: Log file path - GMUSE_TEMPERATURE: LLM sampling temperature - GMUSE_MAX_TOKENS: Maximum tokens in response - GMUSE_MAX_DIFF_BYTES: Maximum diff size before truncation - GMUSE_MAX_MESSAGE_LENGTH: Maximum commit message length - GMUSE_MAX_CHARS: Optional maximum characters for generated message - GMUSE_INCLUDE_BRANCH: Include branch name as context (1/true/yes) - GMUSE_BRANCH_MAX_LENGTH: Maximum length for branch summary

Returns: Configuration dictionary from environment variables

Example: >>> os.environ[“GMUSE_MODEL”] = “gpt-4” >>> config = get_env_config() >>> print(config[“model”]) gpt-4

gmuse.config#

Module Contents#

Functions#

Data#

API#

`gmuse.config`#