python-configuration

Python の構成管理

環境変数と型付き設定を使用して、コードから構成を外部化します。適切に管理された構成により、同じコードを変更なしで任意の環境で実行できます。

このスキルを使用する場面

• 新しいプロジェクトの構成システムをセットアップするとき
• ハードコードされた値から環境変数へ移行するとき
• 型付き設定のために pydantic-settings を実装するとき
• シークレットや機密値を管理するとき
• 環境固有の設定（dev/staging/prod）を作成するとき
• アプリケーションの起動時に構成を検証するとき

中核となる概念

1. 外部化された構成

すべての環境固有の値（URL、シークレット、フィーチャーフラグ）は、コードではなく環境変数から取得します。

2. 型付き設定

起動時に構成を型付きオブジェクトに解析して検証し、コード全体に散在させないようにします。

3. フェイルファスト

アプリケーションの起動時に、必須の構成をすべて検証します。構成が不足している場合は、明確なメッセージとともに即座にクラッシュさせるべきです。

4. 適切なデフォルト値

ローカル開発には妥当なデフォルト値を提供しつつ、機密性の高い設定には明示的な値を要求します。

クイックスタート

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

基本的なパターン

パターン 1: Pydantic による型付き設定

すべての構成を読み込んで検証する中央の設定クラスを作成します。

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)

アプリケーション全体で settings をインポートします:

from myapp.config import settings

def get_database_connection():
    return connect(
        host=settings.db_host,
        port=settings.db_port,
        database=settings.db_name,
    )

パターン 2: 構成の不足時にフェイルファスト

必須の設定が不足している場合は、明確なエラーとともにアプリケーションを即座にクラッシュさせるべきです。

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)

起動時の明確なエラーは、リクエスト処理の途中で発生する不可解な None の失敗よりも優れています。

パターン 3: ローカル開発用のデフォルト値

ローカル開発には妥当なデフォルト値を提供しつつ、シークレットには明示的な値を要求します。

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"}

ローカル開発用の .env ファイルを作成します（決してコミットしないでください）:

# .env (add to .gitignore)
DB_PASSWORD=local_dev_password
API_SECRET_KEY=dev-secret-key
DEBUG=true

パターン 4: 名前空間付きの環境変数

関連する変数にプレフィックスを付けることで、明確さとデバッグのしやすさを実現します。

# 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

これにより、env | grep DB_ がデバッグに役立ちます。

詳細な実例とパターン

詳細なセクション（## Advanced Patterns で始まるもの）は references/details.md にあります。上記のナビゲーション概要で不十分な場合は、そのファイルを参照してください。

ベストプラクティスのまとめ

1. 構成をハードコードしない - 環境固有の値はすべて環境変数から取得する
2. 型付き設定を使用する - 検証付きの pydantic-settings
3. フェイルファスト - 起動時に必須の構成が不足している場合はクラッシュさせる
4. 開発用のデフォルト値を提供する - ローカル開発を容易にする
5. シークレットを決してコミットしない - .env ファイル（gitignore 対象）またはシークレットマネージャーを使用する
6. 変数に名前空間を付ける - 明確さのために DB_HOST、REDIS_URL
7. settings シングルトンをインポートする - コード全体で os.getenv() を呼び出さない
8. すべての変数を文書化する - README に必須の環境変数を記載する
9. 早期に検証する - 起動時に構成の正確性を確認する
10. secrets_dir を使用する - コンテナ内でマウントされたシークレットをサポートする