gmuse.exceptions#

Custom exceptions for gmuse.

This module defines all custom exception types used throughout the gmuse application. All exceptions inherit from GmuseError, allowing callers to catch all application errors with a single except clause if desired.

Exception Hierarchy: GmuseError ├── ConfigError ├── NotAGitRepositoryError ├── NoStagedChangesError ├── LLMError └── InvalidMessageError

Module Contents#

Functions#

_env_var_name

build_missing_credential_message

Build an actionable missing-credential error message.

build_no_secure_keyring_message

Build an actionable message for missing secure keyring support.

build_insecure_keyring_message

Build an actionable message for insecure keyring backends.

build_overwrite_message

Build the message shown when a credential already exists.

build_provider_validation_message

Build the message shown when provider validation fails.

API#

exception gmuse.exceptions.GmuseError#

Bases: Exception

Base exception for all gmuse errors.

All custom exceptions in gmuse inherit from this class, allowing callers to catch any gmuse-specific error with a single except clause:

try:
    result = generate_message(config)
except GmuseError as e:
    print(f"gmuse error: {e}")

Initialization

Initialize self. See help(type(self)) for accurate signature.

exception gmuse.exceptions.ConfigError#

Bases: gmuse.exceptions.GmuseError

Raised when configuration is invalid or cannot be loaded.

This error is raised in the following situations:

  • Invalid TOML syntax in config.toml

  • Invalid config values (e.g., negative history_depth)

  • Config file permission errors

  • Unknown or unsupported configuration options

Initialization

Initialize self. See help(type(self)) for accurate signature.

exception gmuse.exceptions.NotAGitRepositoryError#

Bases: gmuse.exceptions.GmuseError

Raised when the current directory is not a git repository.

This error is raised when:

  • Running gmuse outside a git repository

  • Git is not installed on the system

  • The .git directory is corrupted or missing

Initialization

Initialize self. See help(type(self)) for accurate signature.

exception gmuse.exceptions.NoStagedChangesError#

Bases: gmuse.exceptions.GmuseError

Raised when there are no staged changes to generate a message for.

This error is raised when:

  • User runs gmuse with no files staged

  • All staged changes have been unstaged

  • The staging area is empty

Initialization

Initialize self. See help(type(self)) for accurate signature.

exception gmuse.exceptions.LLMError#

Bases: gmuse.exceptions.GmuseError

Raised when LLM API call fails or returns invalid response.

This error is raised for:

  • No API key configured for any provider

  • Network timeout during API call

  • Invalid or malformed API response

  • Rate limiting by the provider

  • Model not found or unsupported

  • Provider-specific API errors

Initialization

Initialize self. See help(type(self)) for accurate signature.

exception gmuse.exceptions.InvalidMessageError#

Bases: gmuse.exceptions.GmuseError

Raised when generated commit message fails validation.

This error is raised when:

  • Message is empty or whitespace-only

  • Message exceeds maximum length limit

  • Message doesn’t match required format (e.g., conventional commits)

  • Message contains invalid characters

Initialization

Initialize self. See help(type(self)) for accurate signature.

gmuse.exceptions._env_var_name(prefix: str) → str#
exception gmuse.exceptions.CredentialError#

Bases: gmuse.exceptions.GmuseError

Raised when credential storage or lookup fails.

Initialization

Initialize self. See help(type(self)) for accurate signature.

exception gmuse.exceptions.CredentialLookupTimeout#

Bases: gmuse.exceptions.CredentialError

Raised when credential lookup exceeds the allowed time budget.

Initialization

Initialize self. See help(type(self)) for accurate signature.

exception gmuse.exceptions.KeyringUnavailableError#

Bases: gmuse.exceptions.CredentialError

Raised when no secure keyring backend is available.

Initialization

Initialize self. See help(type(self)) for accurate signature.

exception gmuse.exceptions.InsecureKeyringError#

Bases: gmuse.exceptions.CredentialError

Raised when the active keyring backend is insecure.

Initialization

Initialize self. See help(type(self)) for accurate signature.

gmuse.exceptions.build_missing_credential_message(variable_name: str | None = None) → str#

Build an actionable missing-credential error message.

gmuse.exceptions.build_no_secure_keyring_message() → str#

Build an actionable message for missing secure keyring support.

gmuse.exceptions.build_insecure_keyring_message() → str#

Build an actionable message for insecure keyring backends.

gmuse.exceptions.build_overwrite_message(variable_name: str) → str#

Build the message shown when a credential already exists.

gmuse.exceptions.build_provider_validation_message(provider: str) → str#

Build the message shown when provider validation fails.