Config¶

The GPPConfig class manages the local configuration file used by the GPP Client. It supports:

Loading and validating TOML configuration data
Storing per-environment API tokens
Selecting and activating environments
Disabling or enabling the use of OS environment variables
Exporting the configuration as TOML, JSON, or Python dictionaries

The configuration file is validated using Pydantic models. For details on the underlying schema, see Models.

Configuration File Location¶

The configuration file is stored in the system-appropriate application data directory:

POSIX: ~/.config/gpp-client/config.toml
Windows: %APPDATA%/gpp-client/config.toml

This path is determined by typer.get_app_dir() and the defaults defined in gpp_client.config.defaults.

For details on the default paths and filenames, see Defaults.

Configuration Structure¶

The configuration file is a TOML document validated against the ConfigFile model.

Example:

env = "PRODUCTION"
disable_env_vars = false

[tokens]
PRODUCTION = "prod-token"
DEVELOPMENT = "dev-token"
STAGING = "test-token"

Environment Selection¶

GPPConfig tracks the active environment, which determines which token GPPClient uses unless overridden explicitly.

Tokens may be stored for all environments, but only one environment is active at a time.

For details on available environments and rules, see Environment.

Loading and Saving¶

Configuration is loaded automatically on creation:

config = GPPConfig()
print(config.active_env)

Changes may be saved explicitly:

config.save()

Token Management¶

Store a token:

config.set_token("DEVELOPMENT", "dev-token", save=True)

Clear a token:

config.clear_token("STAGING", save=True)

Clear all tokens:

config.clear_tokens(save=True)

Environment Activation¶

The active environment determines which token is used by default:

config.activate("PRODUCTION", save=True)
print(config.active_env)

Combined operation:

config.set_credentials("DEVELOPMENT", "xyz", activate=True, save=True)

Environment Variable Control¶

Users may disable OS environment variables entirely:

config.disable_env_vars(save=True)

Or re-enable them:

config.enable_env_vars(save=True)

Note

Disabling environment variables affects credential resolution. For details, see Credentials.

Exporting Configuration¶

For debugging or automation purposes:

config.to_dict()
config.to_json()
config.to_toml()

Creating a Default Configuration File¶

GPPConfig.create_default_config_file()

This writes an empty, validated configuration with default values.

API Reference¶

class gpp_client.config.GPPConfig[source]¶

Bases: object

Manage loading, saving, and updating GPP client configuration.

This class manages user tokens and environment settings, stored in a TOML file.

activate(env: GPPEnvironment | str, save: bool = False) → None[source]¶

Activate the given environment.

Parameters:

env (GPPEnvironment | str) – The environment to activate.
save (bool, default=False) – Whether to save the configuration to disk immediately.

property active_env: GPPEnvironment¶

Return the currently active environment.

Returns:: The active GPP environment.
Return type:: GPPEnvironment

property active_token: str | None¶

Return the token for the currently active environment.

Returns:: The token for the active environment, or None if not set.
Return type:: str | None

clear_token(env: GPPEnvironment | str, save: bool = False) → None[source]¶

Clear the token for the given environment.

Parameters:

env (GPPEnvironment | str) – The environment to clear the token for.
save (bool, default=False) – Whether to save the configuration to disk immediately.

clear_tokens(save: bool = False) → None[source]¶

Clear all stored tokens for all environments.

Parameters:: save (bool, default=False) – Whether to save the configuration to disk immediately.

static create_default_config_file() → None[source]¶: Create an empty configuration file with placeholder tokens.

disable_env_vars(save: bool = False) → None[source]¶

Disable the use of environment variables for configuration.

Parameters:: save (bool, default=False) – Whether to save the configuration to disk immediately.

enable_env_vars(save: bool = False) → None[source]¶

Enable the use of environment variables for configuration.

Parameters:: save (bool, default=False) – Whether to save the configuration to disk immediately.

exists() → bool[source]¶

Whether the configuration file exists.

Returns:: True if the config file exists, False otherwise.
Return type:: bool

get_all_envs_with_tokens() → dict[GPPEnvironment, str][source]¶

Return all environments with non-empty tokens.

Returns:: A dictionary mapping environment names to their non-empty tokens.
Return type:: dict[GPPEnvironment, str]

get_token_for(env: GPPEnvironment | str) → str | None[source]¶

Return the token for a specific environment.

Parameters:: env (GPPEnvironment | str) – The environment to get the token for.
Returns:: The token for the specified environment, or None if not set.
Return type:: str | None

property has_credentials: bool¶

Checks whether credentials are set for the current environment.

Returns:: True if a token is set for the active environment, False otherwise.
Return type:: bool

save() → None[source]¶: Save the current configuration data to disk.

set_credentials(env: GPPEnvironment | str, token: str, activate: bool = True, save: bool = False) → None[source]¶

Set the token for a given environment and optionally activate it. By default, the environment will be activated.

Parameters:

env (GPPEnvironment | str) – The environment to store the token for.
token (str) – The bearer token.
activate (bool, default=True) – Whether to activate the given environment.
save (bool, default=False) – Whether to save the configuration to disk immediately.

Raises:

GPPValidationError – If the provided token is empty or whitespace.

set_token(env: GPPEnvironment | str, token: str, save: bool = False) → None[source]¶

Store a token for the given environment without activating it.

Parameters:

env (GPPEnvironment | str) – The environment to store the token for.
token (str) – The bearer token.
save (bool, default=False) – Whether to save the configuration to disk immediately.

Raises:

GPPValidationError – If the provided token is empty or whitespace.

to_dict() → dict[source]¶

Return the configuration as a dictionary.

Returns:: The configuration data as a dictionary.
Return type:: dict

to_json() → str[source]¶

Return the configuration as a JSON string.

Returns:: The configuration data as a JSON string.
Return type:: str

to_toml() → str[source]¶

Return the configuration as a TOML string.

Returns:: The configuration data as a TOML string.
Return type:: str

use_env_vars() → bool[source]¶

Whether to use environment variables based on config.

Returns:: True if environment variables should be used, False otherwise.
Return type:: bool