gpconfig

简体中文 | English

General Purpose Configuration management library for Python projects.

A type-safe, YAML-based configuration management library built on Pydantic.

Features

• Type-safe configuration - Built on Pydantic with full type validation
• YAML-based - Human-readable configuration files
• Nested configs - Organize configs in directories (e.g., llm/openai.yaml)
• Auto-detection - Automatically detect config classes from YAML files
• Configurable objects - Create object instances directly from configs
• Environment variable support - Configure paths via environment variables
• Readonly configs - Protect sensitive configurations

Installation

pip install gpconfig

Quick Start

1. Define Config Classes

from typing import ClassVar
from gpconfig import GPConfig

class DatabaseConfig(GPConfig):
    cfg_class_name: ClassVar[str] = "DatabaseConfig"
    host: str
    port: int = 5432
    username: str
    password: str
    database: str

2. Create Config Folder

myapp/
├── global_env.yaml    # Required: global environment config
├── database.yaml      # Your config files
└── llm/               # Nested configs
    ├── openai.yaml
    └── anthropic.yaml

global_env.yaml:

version: "1.0.0"
debug: true
log_level: INFO

database.yaml:

cfg_class_name: "DatabaseConfig"
host: localhost
port: 5432
username: admin
password: secret
database: myapp

Naming rule: . is the path separator in dot-notation, so .yaml file names and subdirectory names must not contain . (construction fails with ConfigFolderError otherwise). To use a name with literal dots — e.g. an internet domain — write each . as @: domain_name@com.yaml is addressed as get_config("domain_name@com"). @ is a plain pass-through character at the addressing layer; consumer libraries that need real dots implement "escape on addressing, restore after loading" client-side (config.name always returns the raw stem). See the naming rule in the docs.

3. Initialize Manager and Load Configs

from gpconfig import GPConfigManager

# Config folder search order:
# 1. Explicit cfg_folder parameter
# 2. Environment variable: {PROJECT_NAME}_CFG_PATH
# 3. User directory: ~/.{project_name}/
manager = GPConfigManager("myapp", cfg_folder="/path/to/myapp")

# Read global_env values
debug = manager.get_config("global_env.debug")

# Load config (auto-detects the registered class by cfg_class_name;
#               returns a plain dict if no class is registered for it)
db_config = manager.get_config("database")

# Load nested config
llm_config = manager.get_config("llm.openai")

# Read specific field
host = manager.get_config("database.host")

4. Create Configurable Objects

from gpconfig import GPConfigurable

class Database(GPConfigurable):
    def __init__(self, config: DatabaseConfig) -> None:
        super().__init__(config)
        self.host = config.host
        self.port = config.port
        self.username = config.username
        self.password = config.password
        self.database = config.database

    @property
    def connection_string(self) -> str:
        return f"postgresql://{self.username}:{self.password}@{self.host}:{self.port}/{self.database}"

# Register classes
GPConfigManager.register_config_class(DatabaseConfig)
GPConfigManager.register_configurable_class(Database)

# Create object instance
db = manager.get_object("database")
print(db.connection_string)

Note: Add configured_class_name to your YAML for get_object():

cfg_class_name: "DatabaseConfig"
configured_class_name: "Database"
host: localhost
port: 5432

5. Save Configs

# Modify and save
db_config.port = 5433
db_config.save()

# Save to new location
manager.save(db_config, "backups/database_backup")

Core Components

Exceptions

API Reference

See the API documentation for detailed usage.

License

MIT