AutoGineer
Generated banner for Python Configuration
Generated logo for Python Configuration

Python Configuration

Seth HobsonCommunityCreated by Seth Hobson

  • Skill
  • Guidelines
  • Software development
  • MIT
  • No issues found
Download ZIP

From the author

Python configuration management via environment variables and typed settings. Use when externalizing config, setting up pydantic-settings, managing secrets, or implementing environment-specific behavior.
— the description by Seth Hobson

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to externalizing configuration in Python applications. By leveraging pydantic-settings, developers can move away from hardcoded values toward a robust system that loads, validates, and types configuration data from environment variables. It emphasizes a 'fail-fast' philosophy, ensuring that applications crash immediately with clear error messages if required configuration is missing or invalid at startup.

What it does

  • Externalizes environment-specific settings from source code.
  • Provides automatic type conversion and validation for configuration values.
  • Supports nested configuration structures for complex applications.
  • Enables environment-specific behavior using enums and computed fields.
  • Integrates with containerized secret management systems.
  • Implements fail-fast validation to catch configuration errors at boot time.

When to use it

  • When setting up configuration for a new Python project.
  • When migrating from hardcoded settings to environment variables.
  • When you need to enforce strict validation on application configuration.
  • When managing sensitive secrets across different deployment environments.
  • When you need to support local development defaults alongside production overrides.

Advantages

  • Reduces runtime errors by validating configuration at startup.
  • Improves security by keeping secrets out of the codebase.
  • Simplifies environment management (dev, staging, prod) via a single interface.
  • Enhances code readability by using typed objects instead of scattered os.getenv calls.
  • Provides clear, actionable error messages for missing or malformed configuration.

Usage examples

“How do I define a typed configuration class for my database connection?”
The agent will provide a Pydantic BaseSettings class with fields for host, port, user, and password, demonstrating how to map them to environment variables.
“How can I make my application crash if a required API key is missing?”
The agent will show how to define a required field in a Pydantic model without a default value, which triggers a ValidationError upon instantiation.
“How do I handle nested configuration groups like database and redis settings?”
The agent will demonstrate using nested Pydantic models with the env_nested_delimiter configuration to map environment variables like DATABASE__HOST.
“How can I support local development defaults while requiring production secrets?”
The agent will explain how to set default values in the Pydantic model for non-sensitive fields while leaving secret fields without defaults to force explicit definition.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/wshobson/python-configuration/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip python-configuration.zip -d .agents/skills

Documentation by Seth Hobson

Python Configuration Management

Externalize configuration from code using environment variables and typed settings. Well-managed configuration enables the same code to run in any environment without modification.

When to Use This Skill

  • Setting up a new project's configuration system

  • Migrating from hardcoded values to environment variables

  • Implementing pydantic-settings for typed configuration

  • Managing secrets and sensitive values

  • Creating environment-specific settings (dev/staging/prod)

  • Validating configuration at application startup

Core Concepts

1. Externalized Configuration

All environment-specific values (URLs, secrets, feature flags) come from environment variables, not code.

2. Typed Settings

Parse and validate configuration into typed objects at startup, not scattered throughout code.

3. Fail Fast

Validate all required configuration at application boot. Missing config should crash immediately with a clear message.

4. Sensible Defaults

Provide reasonable defaults for local development while requiring explicit values for sensitive settings.

Quick Start

from pydantic_settings import BaseSettings
from pydantic import Field

class Settings(BaseSettings):
    database_url: str = Field(alias="DATABASE_URL")
    api_key: str = Field(alias="API_KEY")
    debug: bool = Field(default=False, alias="DEBUG")

settings = Settings()  # Loads from environment

Fundamental Patterns

Pattern 1: Typed Settings with Pydantic

Create a central settings class that loads and validates all configuration.

from pydantic_settings import BaseSettings
from pydantic import Field, PostgresDsn, ValidationError
import sys

class Settings(BaseSettings):
    """Application configuration loaded from environment variables."""

    # Database
    db_host: str = Field(alias="DB_HOST")
    db_port: int = Field(default=5432, alias="DB_PORT")
    db_name: str = Field(alias="DB_NAME")
    db_user: str = Field(alias="DB_USER")
    db_password: str = Field(alias="DB_PASSWORD")

    # Redis
    redis_url: str = Field(default="redis://localhost:6379", alias="REDIS_URL")

    # API Keys
    api_secret_key: str = Field(alias="API_SECRET_KEY")

    # Feature flags
    enable_new_feature: bool = Field(default=False, alias="ENABLE_NEW_FEATURE")

    model_config = {
        "env_file": ".env",
        "env_file_encoding": "utf-8",
    }

# Create singleton instance at module load
try:
    settings = Settings()
except ValidationError as e:
    print(f"Configuration error:\n{e}")
    sys.exit(1)

Import settings throughout your application:

from myapp.config import settings

def get_database_connection():
    return connect(
        host=settings.db_host,
        port=settings.db_port,
        database=settings.db_name,
    )
Pattern 2: Fail Fast on Missing Configuration

Required settings should crash the application immediately with a clear error.

from pydantic_settings import BaseSettings
from pydantic import Field, ValidationError
import sys

class Settings(BaseSettings):
    # Required - no default means it must be set
    api_key: str = Field(alias="API_KEY")
    database_url: str = Field(alias="DATABASE_URL")

    # Optional with defaults
    log_level: str = Field(default="INFO", alias="LOG_LEVEL")

try:
    settings = Settings()
except ValidationError as e:
    print("=" * 60)
    print("CONFIGURATION ERROR")
    print("=" * 60)
    for error in e.errors():
        field = error["loc"][0]
        print(f"  - {field}: {error['msg']}")
    print("\nPlease set the required environment variables.")
    sys.exit(1)

A clear error at startup is better than a cryptic None failure mid-request.

Pattern 3: Local Development Defaults

Provide sensible defaults for local development while requiring explicit values for secrets.

class Settings(BaseSettings):
    # Has local default, but prod will override
    db_host: str = Field(default="localhost", alias="DB_HOST")
    db_port: int = Field(default=5432, alias="DB_PORT")

    # Always required - no default for secrets
    db_password: str = Field(alias="DB_PASSWORD")
    api_secret_key: str = Field(alias="API_SECRET_KEY")

    # Development convenience
    debug: bool = Field(default=False, alias="DEBUG")

    model_config = {"env_file": ".env"}

Create a .env file for local development (never commit this):

# .env (add to .gitignore)
DB_PASSWORD=local_dev_password
API_SECRET_KEY=dev-secret-key
DEBUG=true
Pattern 4: Namespaced Environment Variables

Prefix related variables for clarity and easy debugging.

# Database configuration
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp
DB_USER=admin
DB_PASSWORD=secret

# Redis configuration
REDIS_URL=redis://localhost:6379
REDIS_MAX_CONNECTIONS=10

# Authentication
AUTH_SECRET_KEY=your-secret-key
AUTH_TOKEN_EXPIRY_SECONDS=3600
AUTH_ALGORITHM=HS256

# Feature flags
FEATURE_NEW_CHECKOUT=true
FEATURE_BETA_UI=false

Makes the database settings easy to list for debugging. Print only the names, so no value (such as a password inside a connection URL) reaches your terminal or logs:

env | grep -o '^DB_[A-Za-z0-9_]*'

Detailed worked examples and patterns

Detailed sections (starting with ## Advanced Patterns) live in references/details.md. Read that file when the navigation summary above is insufficient.

Best Practices Summary

  1. Never hardcode config - All environment-specific values from env vars

  2. Use typed settings - Pydantic-settings with validation

  3. Fail fast - Crash on missing required config at startup

  4. Provide dev defaults - Make local development easy

  5. Never commit secrets - Use .env files (gitignored) or secret managers

  6. Namespace variables - DB_HOST, REDIS_URL for clarity

  7. Import settings singleton - Don't call os.getenv() throughout code

  8. Document all variables - README should list required env vars

  9. Validate early - Check config correctness at boot time

  10. Use secrets_dir - Support mounted secrets in containers

Files

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an API key, Needs Python

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Seth Hobson
Publisher
Seth Hobson (Community)
Source
wshobson/agents · plugins/python-development/skills/python-configuration · commit 4bde316
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Seth Hobson or Seth Hobson.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download python-configuration.zip