Configuration

Overview

The client uses pydantic-settings to resolve configuration at runtime.

Configuration is:

  • Environment-aware

  • Strictly validated

  • Resolved from multiple sources

Environment Model

The active environment is determined by the installed package:

  • Development builds → development environment

  • Production builds → production environment

The environment cannot be changed at runtime.

Note

The environment_override option exists for internal tooling (e.g., code generation) and should not be used in normal client usage.

Authentication

Authentication is environment-specific.

  • Development requires GPP_DEVELOPMENT_TOKEN

  • Production requires GPP_TOKEN

export GPP_DEVELOPMENT_TOKEN=...
export GPP_TOKEN=...

An explicit token may also be provided when creating the client:

client = GPPClient(token="my-token")

The token is applied to the active environment.

Note

When passing token= explicitly:

  • In development builds, the token is used as development_token

  • In production builds, the token is used as token

This allows the same code to work across environments without modification.

Warning

Tokens are not interchangeable. A development client will not use GPP_TOKEN and will fail if GPP_DEVELOPMENT_TOKEN is not set.

Configuration Sources

Settings are resolved using the following precedence:

  1. Initialization parameters

  2. Environment variables

  3. .env file

  4. Application config file

  5. Model defaults

Each field is resolved independently.

Tip

Different fields may come from different sources. For example:

  • token from environment variables

  • debug from a TOML config file

Configuration File

An optional TOML configuration file may be used.

The directory is determined using typer.get_app_dir() and follows platform-specific conventions.

Typical locations:

  • macOS: ~/Library/Application Support/<App Name>

  • Linux: ~/.config/<app-name>

  • Windows: C:\Users\<user>\AppData\Roaming\<App Name>

The full path is:

<app-dir>/<config-file-name>

Example:

~/.config/gpp-client/settings.toml

The file is only used if it exists.

Example contents:

token = "prod-token"
development_token = "dev-token"
debug = true

Tip

To see the exact path used on your system:

from gpp_client.settings import get_config_path
print(get_config_path())

API Reference

class gpp_client.settings.GPPSettings(_case_sensitive: bool | None = None, _nested_model_default_partial_update: bool | None = None, _env_prefix: str | None = None, _env_prefix_target: EnvPrefixTarget | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_nested_max_split: int | None = None, _env_parse_none_str: str | None = None, _env_parse_enums: bool | None = None, _cli_prog_name: str | None = None, _cli_parse_args: bool | list[str] | tuple[str, ...] | None = None, _cli_settings_source: CliSettingsSource[Any] | None = None, _cli_parse_none_str: str | None = None, _cli_hide_none_type: bool | None = None, _cli_avoid_json: bool | None = None, _cli_enforce_required: bool | None = None, _cli_use_class_docs_for_groups: bool | None = None, _cli_exit_on_error: bool | None = None, _cli_prefix: str | None = None, _cli_flag_prefix_char: str | None = None, _cli_implicit_flags: bool | Literal['dual', 'toggle'] | None = None, _cli_ignore_unknown_args: bool | None = None, _cli_kebab_case: bool | Literal['all', 'no_enums'] | None = None, _cli_shortcuts: Mapping[str, str | list[str]] | None = None, _secrets_dir: PathType | None = None, _build_sources: tuple[tuple[PydanticBaseSettingsSource, ...], dict[str, Any]] | None = None, *, token: SecretStr | None = None, development_token: SecretStr | None = None, debug: bool = False, environment_override: GPPEnvironment | None = None)[source]

Bases: BaseSettings

Effective runtime settings for the installed GPP client package.

Notes

Supported environment variables:

  • GPP_TOKEN

  • GPP_DEVELOPMENT_TOKEN

  • GPP_DEBUG

Token resolution behavior:

  • Production package uses token.

  • Development package uses development_token.

debug: bool
development_token: SecretStr | None
property environment: GPPEnvironment

Determine the effective package environment.

Returns:

Effective package environment, either from the override or the generated constant.

Return type:

GPPEnvironment

environment_override: GPPEnvironment | None
property resolved_token: str

Return the token appropriate for the installed package environment.

Returns:

Resolved API token.

Return type:

str

Raises:

GPPAuthError – If no valid token is available for the active environment.

classmethod settings_customise_sources(settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) → tuple[PydanticBaseSettingsSource, ...][source]

Customise the settings sources to ensure the expected precedence order.

Parameters:

  • settings_cls (type[BaseSettings]) – The settings class being constructed.

  • init_settings (PydanticBaseSettingsSource) – Source for initialization parameters.

  • env_settings (PydanticBaseSettingsSource) – Source for environment variables.

  • dotenv_settings (PydanticBaseSettingsSource) – Source for dotenv file.

  • file_secret_settings (PydanticBaseSettingsSource) – Source for file secrets.

Returns:

Ordered tuple of settings sources.

Return type:

tuple[PydanticBaseSettingsSource, …]

Notes

The default precedence order is:

  1. Initialization parameters

  2. Environment variables

  3. Dotenv file

  4. App TOML file

  5. File secrets

token: SecretStr | None