wshobson/python-configuration

python-configuration 是做什麼的？

透過環境變數與型別設定來管理 Python 組態。適用於外部化組態、設定 pydantic-settings、管理秘密或實作環境特定行為。

概述

此技能協助你使用環境變數和型別設定來管理 Python 應用程式的組態。它基於 pydantic-settings 函式庫，讓你能夠定義帶有型別標註的設定類別，並從環境變數、.env 檔案或其他來源自動載入值。

使用方式

1. 在你的專案中安裝 pydantic-settings：

   pip install pydantic-settings
   

2. 建立一個設定類別，例如 settings.py：

   from pydantic_settings import BaseSettings
   
   class Settings(BaseSettings):
       app_name: str = "My App"
       debug: bool = False
       database_url: str
       secret_key: str
   
       class Config:
           env_file = ".env"
   

3. 在你的程式碼中使用設定：

   from settings import Settings
   
   settings = Settings()
   print(settings.app_name)
   

環境變數

你可以透過環境變數來覆蓋設定值。變數名稱會自動對應至設定類別的屬性名稱（大寫）。

例如，若要設定 database_url，請設定環境變數 DATABASE_URL。

支援的檔案格式

• .env 檔案（透過 env_file 設定）
• 系統環境變數
• 其他自訂來源（透過繼承 BaseSettings）

安全注意事項

• 永遠不要將 .env 檔案提交到版本控制系統。
• 使用 .env.example 檔案來記錄所需的環境變數。
• 將敏感值（如秘密金鑰）儲存在環境變數或安全的秘密管理服務中。

進階用法

巢狀設定

你可以使用 pydantic 的巢狀模型來建立複雜的設定結構：

from pydantic import BaseModel
from pydantic_settings import BaseSettings

class DatabaseConfig(BaseModel):
    host: str = "localhost"
    port: int = 5432

class Settings(BaseSettings):
    database: DatabaseConfig = DatabaseConfig()

    class Config:
        env_nested_delimiter = "__"

然後使用 DATABASE__HOST 和 DATABASE__PORT 環境變數來設定。

環境特定檔案

你可以根據環境載入不同的 .env 檔案：

import os
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    # ...

    class Config:
        env_file = f".env.{os.getenv('APP_ENV', 'development')}"

結論

這個技能簡化了 Python 專案中組態的管理，提升了程式碼的可維護性和安全性。透過型別設定和環境變數，你可以輕鬆地實作環境特定的行為，同時保持程式碼的整潔和一致性。