`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): 1. CLI arguments (cli_args) 2. Environment variables (env_vars) 3. Config file (config_file) 4. 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`#