Pythonの設定管理をスマートに！environsライブラリ徹底解説 ✨

はじめに：なぜ設定管理が重要なのか？🤔

現代のアプリケーション開発において、設定管理は避けて通れない重要な要素です。データベースの接続情報、APIキー、外部サービスのURL、デバッグモードの有効/無効など、アプリケーションの動作を環境ごとに制御するための情報は多岐にわたります。

これらの設定値をコード内に直接書き込む（ハードコーディングする）のは、セキュリティリスクやメンテナンス性の低下を招くため、一般的には推奨されません。そこで広く用いられているのが、環境変数や`.env`ファイルを利用する方法です。

• 環境変数: OSレベルで設定される変数。デプロイ環境（本番、ステージング、開発）ごとに異なる値を設定しやすい。
• `.env`ファイル: プロジェクトルートに配置されるテキストファイル。キーと値のペアで設定を記述し、開発環境での設定管理を容易にする。

しかし、これらの方法を素のPythonで扱う場合、いくつかの課題があります。

• 環境変数はすべて文字列として扱われるため、数値や真偽値など、期待するデータ型への変換が必要。
• 設定値が存在しない場合のデフォルト値の扱いや、必須項目のチェック。
• 設定値が特定のフォーマット（URL、メールアドレスなど）に準拠しているかのバリデーション。
• 設定項目が増えた場合の管理の複雑化。

こうした課題を解決し、より安全で効率的な設定管理を実現するために開発されたのが、今回ご紹介するPythonライブラリ `environs` です！ 🎉

この記事では、`environs` の基本的な使い方から、データ型のパース、バリデーション、高度な機能、実践的な利用例まで、徹底的に解説していきます。さあ、`environs` を使って、あなたのPythonプロジェクトの設定管理をスマートにしましょう！🚀

`environs` の基本 🛠️

まずは `environs` を使い始めるための基本的な手順を見ていきましょう。

インストール

`environs` は pip を使って簡単にインストールできます。

pip install environs

バリデーション機能を利用する場合は、`marshmallow` も一緒にインストールする必要があります。

pip install environs[marshmallow]

基本的な使い方

`environs` の中心となるのは `Env` クラスです。まず、このクラスのインスタンスを作成します。

from environs import Env

env = Env()

これで準備完了です。環境変数から値を読み込むには、`env()` メソッド（または `env.str()` メソッド）を使用します。

# 環境変数 'DATABASE_URL' の値を読み込む
db_url = env("DATABASE_URL")

# 環境変数 'SECRET_KEY' の値を読み込む (env.str() でも同じ)
secret_key = env.str("SECRET_KEY")

print(f"データベースURL: {db_url}")
print(f"シークレットキー: {secret_key}")

もし指定した環境変数が設定されていない場合、`environs.EnvError` 例外が発生します。これにより、必須の設定が漏れていることにすぐに気づくことができます。

`.env` ファイルのサポート

`environs` は、プロジェクトルートや親ディレクトリにある `.env` ファイルを自動的に検索し、そこに記述された設定値を環境変数として読み込みます。これにより、開発環境での設定管理が非常に簡単になります。

例えば、プロジェクトルートに以下のような `.env` ファイルを作成します。

#.env ファイルの例
DATABASE_URL=postgresql://user:password@host:port/dbname
SECRET_KEY=your-super-secret-key
DEBUG=True
CACHE_TIMEOUT=60

そして、Pythonコードで `Env` インスタンスを作成するだけで、これらの値が自動的に読み込まれます。

from environs import Env

env = Env()
# .env ファイルを読み込む場合は、インスタンス作成時に read_env() を呼ぶ必要はありません (デフォルトで読み込みます)
# env.read_env() # 明示的に呼ぶことも可能

db_url = env("DATABASE_URL")
secret_key = env("SECRET_KEY")
debug_mode = env.bool("DEBUG") # 型パースについては後述
cache_timeout = env.int("CACHE_TIMEOUT") # 型パースについては後述

print(f"データベースURL: {db_url}")
print(f"シークレットキー: {secret_key}")
print(f"デバッグモード: {debug_mode} (型: {type(debug_mode)})")
print(f"キャッシュタイムアウト: {cache_timeout} (型: {type(cache_timeout)})")

データ型のパース 🔄

環境変数は通常、文字列として扱われますが、アプリケーションでは数値、真偽値、リスト、URLなど、様々な型のデータが必要です。`environs` は、これらのデータ型への自動パース（変換）を簡単に行うための豊富なメソッドを提供します。

基本的な書式は `env.datatype(“VARIABLE_NAME”, default=None, **kwargs)` です。

これらのメソッドを使うことで、環境変数や `.env` ファイルから読み込んだ値を、適切な型に簡単に変換できます。型変換エラーが発生した場合（例: 整数を期待する変数に文字列 “abc” が設定されている）、`environs.EnvError` が発生し、設定の誤りに気づくことができます。

デフォルト値と必須設定 ✅

すべての設定項目が常に環境変数や `.env` ファイルで定義されているとは限りません。`environs` では、設定値が存在しない場合の挙動を制御できます。

デフォルト値の設定

各パースメソッド（`env.str`, `env.int` など）の第二引数に `default` を指定することで、対応する環境変数が設定されていない場合に使用されるデフォルト値を設定できます。

from environs import Env

env = Env()

# 環境変数 'HOST' がなければ 'localhost' を使用
host = env.str("HOST", default="localhost")

# 環境変数 'PORT' がなければ 8080 を使用
port = env.int("PORT", default=8080)

# 環境変数 'DEBUG' がなければ False を使用
debug = env.bool("DEBUG", default=False)

print(f"Host: {host}")
print(f"Port: {port}")
print(f"Debug: {debug}")

このように `default` を指定しておけば、環境変数が未設定でもエラーにならず、デフォルト値が使用されるため、柔軟な設定管理が可能です。

必須設定

一方で、`default` 引数を指定しない場合、その設定項目は必須であるとみなされます。もし対応する環境変数が設定されておらず、かつ `.env` ファイルにも記述がない場合、`environs.EnvError` 例外が発生します。

from environs import Env
from environs import EnvError

env = Env()

try:
    # 'SECRET_KEY' は必須。未設定ならエラーが発生する。
    secret_key = env("SECRET_KEY")
    print(f"Secret Key: {secret_key}")
except EnvError as e:
    print(f"エラー: 必須の設定項目 'SECRET_KEY' が見つかりません。")
    print(e) # エラーメッセージの詳細

# 'OPTIONAL_SETTING' はデフォルト値があるのでエラーにならない
optional_setting = env.str("OPTIONAL_SETTING", default="N/A")
print(f"Optional Setting: {optional_setting}")

この挙動により、アプリケーションの動作に不可欠な設定が漏れている場合に、開発の早い段階で問題を検知できます。データベース接続情報やAPIキーなど、必須の設定項目には `default` を指定しないでおくのが良いでしょう。

バリデーションとスキーマ定義 🛡️

設定値が正しいデータ型であることだけでなく、さらに複雑な条件（例: 特定の範囲内の数値、有効なメールアドレス形式、特定の選択肢の中から選ばれているかなど）を満たしているか検証したい場合があります。`environs` は、人気のあるデータバリデーションライブラリ `marshmallow` とシームレスに連携し、高度なバリデーション機能を提供します。

この機能を利用するには、`marshmallow` がインストールされている必要があります (`pip install environs[marshmallow]`)。

Marshmallow スキーマの定義

まず、`marshmallow` を使って設定のスキーマ（構造とバリデーションルール）を定義します。`marshmallow.Schema` を継承したクラスを作成し、フィールドを定義します。

import marshmallow as ma
from marshmallow import fields
from environs import Env

class AppConfigSchema(ma.Schema):
    # 必須の文字列、長さ制限付き
    secret_key = fields.Str(required=True, validate=ma.validate.Length(min=16))
    # 真偽値、デフォルトは False
    debug = fields.Bool(load_default=False)
    # 整数、範囲指定
    port = fields.Int(load_default=8000, validate=ma.validate.Range(min=1024, max=65535))
    # URL形式の文字列、必須
    database_url = fields.URL(required=True, schemes={"postgres", "postgresql"})
    # リスト（要素は文字列）、デフォルトは空リスト
    allowed_hosts = fields.List(fields.Str(), load_default=[])
    # メール形式の文字列、任意
    admin_email = fields.Email()
    # 選択肢の中から選ぶ, デフォルト値あり
    log_level = fields.Str(
        load_default="INFO",
        validate=ma.validate.OneOf(["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"])
    )

    # .env ファイルや環境変数は大文字が一般的なので、
    # スキーマのフィールド名（小文字スネークケース）にマッピングする
    class Meta:
        # 環境変数名からフィールド名へのマッピング (キーが環境変数名、値がフィールド名)
        # environs は自動で大文字->小文字変換を試みるため、通常は不要な場合も多い
        # load_by = {
        #     'SECRET_KEY': 'secret_key',
        #     'DEBUG': 'debug',
        #     'PORT': 'port',
        #     'DATABASE_URL': 'database_url',
        #     'ALLOWED_HOSTS': 'allowed_hosts',
        #     'ADMIN_EMAIL': 'admin_email',
        #     'LOG_LEVEL': 'log_level',
        # }
        # marshmallow 3 以降では load_by は非推奨 -> dump_only/load_only や data_key を使用
        # environs は環境変数名 (大文字) をフィールド名 (小文字) に自動でマッピングしようと試みます
        pass

このスキーマでは、各設定項目に対して以下の情報を定義しています。

• データ型: `fields.Str`, `fields.Bool`, `fields.Int`, `fields.URL`, `fields.List`, `fields.Email` など。
• 必須かどうか: `required=True`。
• デフォルト値: `load_default=…` (Marshmallow 3以降)。Marshmallow 2では `missing=…`。
• バリデーションルール: `validate=…` を使って、長さ、範囲、選択肢、正規表現などを指定できます。

スキーマを使った設定の読み込みとバリデーション

定義したスキーマを使って設定を読み込み、バリデーションを行う方法は主に2つあります。

方法1: `env.read_env(schema=…)` を使う

`Env` インスタンスの `read_env()` メソッド（またはインスタンス化時の `Env()`）に `schema` 引数としてスキーマクラスのインスタンスを渡します。これにより、環境変数や `.env` ファイルが読み込まれる際にスキーマに基づいたパースとバリデーションが実行されます。

バリデーションが成功すると、パースおよび検証済みの設定値を持つオブジェクト（通常は辞書）が返されます。バリデーションエラーが発生した場合は、`marshmallow.ValidationError` が発生します。

from environs import Env
from environs import EnvError
import marshmallow as ma

# (AppConfigSchema は上記で定義済みとする)

env = Env()
config = None

try:
    # スキーマを指定して .env ファイルと環境変数を読み込む
    # schema 引数にはスキーマクラスのインスタンスを渡す
    loaded_config = env.read_env(schema=AppConfigSchema())

    # environs < 9.0 では env.read_env() は None を返すため、
    # スキーマを使った読み込みは @env.parser_for を使うか、
    # 読み込み後に手動でスキーマを適用する必要があった。
    # environs 9.0 以降では、env.read_env(schema=...) や Env(schema=...) で
    # バリデーション済みの辞書が返されるようになった、と言及されている場合があるが、
    # 公式ドキュメント (2023年時点) では schema 引数は parser の登録用とされている。
    # より確実な方法は、以下のように個別に読み込むか、後述のデコレータを使う方法。

    # --- 代替案: 個別にスキーマで検証 ---
    # 1. まず environs で値を読み込む (型パースは environs が行う)
    raw_config_data = {
        'SECRET_KEY': env('SECRET_KEY'), # 必須
        'DEBUG': env.bool('DEBUG', False),
        'PORT': env.int('PORT', 8000),
        'DATABASE_URL': env('DATABASE_URL'), # 必須 (URL型チェックはスキーマで行う)
        'ALLOWED_HOSTS': env.list('ALLOWED_HOSTS', [], subcast=str),
        'ADMIN_EMAIL': env('ADMIN_EMAIL', None), # 任意なので default=None
        'LOG_LEVEL': env('LOG_LEVEL', 'INFO')
    }

    # None の値を持つキーを除去 (MarshmallowスキーマはNoneを欠損値として扱うことがあるため)
    raw_config_data = {k: v for k, v in raw_config_data.items() if v is not None}

    # 2. Marshmallowスキーマでロード（バリデーション）
    schema = AppConfigSchema()
    config = schema.load(raw_config_data) # ここで ValidationError が発生する可能性がある

    print("設定の読み込みとバリデーションに成功しました！")
    print(config)

except EnvError as e:
    print(f"設定読み込みエラー (environs): {e}")
except ma.ValidationError as e:
    print("設定のバリデーションエラー (marshmallow):")
    # エラーの詳細を表示 (どのフィールドでどのようなエラーが発生したか)
    print(e.messages)
except Exception as e:
    print(f"予期せぬエラー: {e}")

if config:
    # バリデーション済みの設定値にアクセス
    print(f"デバッグモード: {config.get('debug')}")
    print(f"ポート番号: {config.get('port')}")
    print(f"許可ホスト: {config.get('allowed_hosts')}")
    print(f"ログレベル: {config.get('log_level')}")

方法2: `@env.parser_for()` デコレータを使う

より直接的な方法として、`@env.parser_for(field_name)` デコレータを使って、特定のMarshmallowフィールドを特定の環境変数名のパーサーとして登録する方法があります。

from environs import Env
import marshmallow as ma
from marshmallow import fields

env = Env()

# Marshmallow フィールドを直接パーサーとして登録
# SECRET_KEY 環境変数を読み込む際に、この fields.Str によるバリデーションが適用される
@env.parser_for("SECRET_KEY")
def secret_key_parser(value):
    field = fields.Str(required=True, validate=ma.validate.Length(min=16))
    return field.deserialize(value) # deserialize は marshmallow 2 のメソッド, 3 では _deserialize

@env.parser_for("PORT")
def port_parser(value):
    field = fields.Int(validate=ma.validate.Range(min=1024, max=65535))
    return field.deserialize(value)

@env.parser_for("ADMIN_EMAIL")
def email_parser(value):
    # 必須ではないので required=False (デフォルト)
    field = fields.Email()
    try:
        return field.deserialize(value)
    except ma.ValidationError:
        # バリデーションエラーの場合は None を返すか、エラーを再raiseするかなど挙動を決める
        # ここでは None を返してみる (オプション設定の場合)
        return None

try:
    # 通常通り env() で読み込むと、登録されたパーサー（バリデーター）が自動で適用される
    secret = env("SECRET_KEY") # secret_key_parser が呼ばれる
    port = env.int("PORT", 8000) # port_parser が呼ばれる (env.int は内部で parser を使う)
    admin_email = env("ADMIN_EMAIL", None) # email_parser が呼ばれる

    print(f"Secret Key (validated): {secret}")
    print(f"Port (validated): {port}")
    print(f"Admin Email (validated): {admin_email}")

except EnvError as e:
    print(f"設定読み込みエラー: {e}")
except ma.ValidationError as e: # パーサー内で発生したバリデーションエラーをキャッチする場合
    print(f"設定のバリデーションエラー: {e}")

この方法では、各環境変数に対して個別にMarshmallowフィールドを関連付けることができます。`env()` や `env.int()` などで値を読み込む際に、登録されたパーサーが自動的に適用され、バリデーションが行われます。バリデーションに失敗すると `marshmallow.ValidationError` が発生します（またはパーサー内でハンドルされます）。

バリデーションの利点

Marshmallow と連携することで、`environs` は単なる型パースを超えた強力な設定管理ツールとなります。

• ✅ **設定ミスからの保護:** アプリケーション起動時に設定値の妥当性をチェックし、不正な値による予期せぬエラーを防ぎます。
• 📖 **設定仕様の明確化:** スキーマ定義が、アプリケーションが必要とする設定とその条件をドキュメント化する役割を果たします。
• 🔧 **一貫性の維持:** 複雑なバリデーションロジックをスキーマに集約することで、コード全体での一貫性を保ちやすくなります。

高度な機能 ⚙️

`environs` は基本的な機能に加えて、より複雑なユースケースに対応するための高度な機能も提供しています。

プレフィックスの使用

複数のアプリケーションやコンポーネントが同じ環境で動作する場合、環境変数名が衝突する可能性があります。`environs` では、`Env` インスタンスを作成する際に `prefix` を指定することで、特定のプレフィックスを持つ環境変数のみを対象とすることができます。

from environs import Env

# 'MYAPP_' プレフィックスを持つ環境変数のみを対象とする
app_env = Env(prefix="MYAPP_")

# 環境変数 'MYAPP_DATABASE_URL' を読み込む (プレフィックスは含めずに指定)
db_url = app_env("DATABASE_URL")

# 環境変数 'MYAPP_CACHE_TYPE' を読み込む (プレフィックスは含めずに指定)
cache_type = app_env("CACHE_TYPE", default="redis")

# 環境変数 'OTHER_VAR' はプレフィックスがないため、app_env では無視される
# other = app_env("OTHER_VAR") # -> EnvError になる

print(f"App DB URL: {db_url}")
print(f"App Cache Type: {cache_type}")

# プレフィックスなしの Env インスタンスも併用可能
general_env = Env()
other_var = general_env("OTHER_VAR", default="some_value")
print(f"Other Var: {other_var}")

`prefix` を指定すると、`env(“VAR_NAME”)` は実際には環境変数 `PREFIX_VAR_NAME` を探しに行きます。これにより、設定のスコープを明確にし、意図しない設定の読み込みを防ぐことができます。

ネストされた設定

設定値を階層構造で管理したい場合があります。`environs` はいくつかの方法でこれをサポートします。

`subcast` と `dict` / `list`

前述の `env.dict()` や `env.list()` で `subcast` を使用することで、簡単なネスト構造を実現できます。

from environs import Env

env = Env()

# .env ファイルに以下があると仮定:
# CACHE_SETTINGS=host=localhost,port=6379,timeout=300
# FEATURE_FLAGS=new_ui=true,beta_access=false

# 値が文字列の辞書
cache_settings = env.dict("CACHE_SETTINGS")
print(cache_settings) # {'host': 'localhost', 'port': '6379', 'timeout': '300'}

# 値が真偽値の辞書
feature_flags = env.dict("FEATURE_FLAGS", subcast=bool)
print(feature_flags) # {'new_ui': True, 'beta_access': False}

`Env(expand_vars=True)`

`Env` インスタンス化時に `expand_vars=True` を指定すると、環境変数の値に含まれる他の環境変数（例: `${OTHER_VAR}` や `$OTHER_VAR`）を展開できます。これは Docker Compose などでよく使われる形式です。

import os
from environs import Env

# 環境変数を設定 (実際には OS や .env で設定)
os.environ['BASE_DIR'] = '/app'
os.environ['LOG_PATH'] = '${BASE_DIR}/logs/app.log' # または $BASE_DIR/logs/app.log

env = Env(expand_vars=True)

log_path = env("LOG_PATH")
print(log_path) # 出力: /app/logs/app.log

Marshmallow スキーマによるネスト

より複雑なネスト構造や、ネストされた要素のバリデーションが必要な場合は、Marshmallow の `fields.Nested()` を使用するのが最も強力です。

import marshmallow as ma
from marshmallow import fields
from environs import Env

# ネストされるスキーマ
class DatabaseConfigSchema(ma.Schema):
    url = fields.URL(required=True)
    pool_size = fields.Int(load_default=10, validate=ma.validate.Range(min=1))

class CacheConfigSchema(ma.Schema):
    type = fields.Str(load_default='redis', validate=ma.validate.OneOf(['redis', 'memcached']))
    host = fields.Str(required=True)
    port = fields.Int(required=True)

# メインのスキーマ
class AppConfigSchema(ma.Schema):
    # 環境変数 'DATABASE_URL' と 'DATABASE_POOL_SIZE' を
    # 'database' フィールドのネストされたオブジェクトにマッピングする想定
    # Marshmallow単体では環境変数名を直接扱えないため、environs側で読み取った値を渡す必要がある
    database = fields.Nested(DatabaseConfigSchema, required=True)
    # 同様にキャッシュ設定もネスト
    cache = fields.Nested(CacheConfigSchema, required=True)
    debug = fields.Bool(load_default=False)

env = Env()

try:
    # environs で関連する環境変数を読み込む
    # ネスト構造を意識して読み込む必要がある
    raw_config_data = {
        'debug': env.bool('DEBUG', False),
        'database': {
             # 環境変数名からキー名を変換 (例: DATABASE_URL -> url)
            'url': env('DATABASE_URL'),
            'pool_size': env.int('DATABASE_POOL_SIZE', 10)
        },
        'cache': {
            'type': env('CACHE_TYPE', 'redis'),
            'host': env('CACHE_HOST'),
            'port': env.int('CACHE_PORT')
        }
    }

    # スキーマでロード（バリデーション）
    schema = AppConfigSchema()
    config = schema.load(raw_config_data)

    print("ネストされた設定の読み込みとバリデーション成功！")
    print(config)
    # ネストされた値へのアクセス
    print(f"Database URL: {config['database']['url']}")
    print(f"Cache Host: {config['cache']['host']}")

except EnvError as e:
    print(f"設定読み込みエラー: {e}")
except ma.ValidationError as e:
    print(f"設定のバリデーションエラー: {e.messages}")

この方法では、環境変数名をスキーマのフィールド構造にマッピングする前処理が必要になることが多いですが、非常に柔軟で強力なネスト設定管理とバリデーションが可能です。

メソッドとデコレータの使い分け

`environs` では、設定の読み込みとパースにメソッド形式 (`env.str()`, `env.int()`) とデコレータ形式 (`@env.parser_for()`) を利用できます。

• メソッド形式 (`env.str()`, etc.):
  • シンプルで直感的。
  • 基本的な型パースやデフォルト値の設定に手軽に使える。
  • コード内で設定値を直接取得する際に使用。
• デコレータ形式 (`@env.parser_for()`):
  • 特定の環境変数に対するカスタムパースロジックやMarshmallowフィールドによるバリデーションを定義するのに適している。
  • パーサーを一度定義すれば、`env(“VAR_NAME”)` で呼び出すだけで適用される。
  • 設定の読み込みロジックを特定の関数やクラスにカプセル化しやすい。

どちらを使うかは状況や好みに応じて選択できます。単純なケースではメソッド形式、複雑なパースやバリデーションが必要な場合はデコレータ形式（またはスキーマ全体でのバリデーション）が有効です。

設定の確定 (`Env.seal()`)

アプリケーションの初期化時にすべての設定を読み込んだ後、意図しないタイミングで再度 `.env` ファイルが読み込まれたり、設定値が変更されたりするのを防ぎたい場合があります。そのような場合に `Env.seal()` メソッドを使用できます。

from environs import Env

env = Env()
env.read_env() # 初回の読み込み

# 設定値を取得
db_url = env("DATABASE_URL")
debug_mode = env.bool("DEBUG")

# 設定を確定する
env.seal()

# これ以降、env.read_env() を呼び出しても再読み込みは行われない
env.read_env(path='.env.other', overwrite=True) # 何も起こらない

# 新しい環境変数を読み込もうとするとエラーになる (既に確定されているため)
# try:
#     new_var = env("NEW_VAR")
# except EnvError as e:
#     print(f"エラー: Env は既に確定 (sealed) されています。 {e}")

print("設定は確定されました。")

`Env.seal()` を呼び出すと、`Env` インスタンスは不変（immutable）となり、以降の `.env` ファイルの読み込みや、まだ読み込まれていない環境変数のパースがブロックされます。これにより、アプリケーション実行中の設定の安定性を高めることができます。

実践的な使い方 🚀

`environs` を実際のプロジェクトでどのように活用できるか、いくつかのパターンを見てみましょう。

設定ファイルを別モジュールに切り出す

設定関連のロジックをアプリケーションコードから分離するために、専用の設定モジュール（例: `config.py`）を作成するのが一般的です。

`config.py` の例:

# config.py
import os
from environs import Env
import marshmallow as ma
from marshmallow import fields

env = Env()
# .env ファイルを読み込む (プロジェクトルートにあると仮定)
env.read_env()

# --- Marshmallow スキーマ定義 (オプション) ---
class AppConfigSchema(ma.Schema):
    secret_key = fields.Str(required=True, validate=ma.validate.Length(min=16))
    debug = fields.Bool(load_default=False)
    database_url = fields.URL(required=True, schemes={"postgres", "postgresql"})
    redis_host = fields.Str(load_default='localhost')
    redis_port = fields.Int(load_default=6379)

# --- 設定値の読み込みとエクスポート ---
# スキーマを使わない場合:
# SECRET_KEY = env.str("SECRET_KEY")
# DEBUG = env.bool("DEBUG", default=False)
# DATABASE_URL = env.url("DATABASE_URL")
# REDIS_HOST = env.str("REDIS_HOST", default="localhost")
# REDIS_PORT = env.int("REDIS_PORT", default=6379)

# --- スキーマを使う場合 ---
try:
    # 環境変数を読み込んで辞書を作成
    raw_config_data = {
        'secret_key': env('SECRET_KEY'),
        'debug': env.bool('DEBUG', False),
        'database_url': env('DATABASE_URL'),
        'redis_host': env('REDIS_HOST', 'localhost'),
        'redis_port': env.int('REDIS_PORT', 6379),
    }
    # 不要なキーを除去 (任意)
    raw_config_data = {k: v for k, v in raw_config_data.items() if v is not None}

    schema = AppConfigSchema()
    validated_config = schema.load(raw_config_data)

    # 検証済みデータをグローバル変数としてエクスポート
    SECRET_KEY = validated_config['secret_key']
    DEBUG = validated_config['debug']
    DATABASE_URL = validated_config['database_url'] # これは ParseResult オブジェクトになる
    REDIS_HOST = validated_config['redis_host']
    REDIS_PORT = validated_config['redis_port']

    # 必要であれば他の設定もここに追加
    BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
    # ...

except (env.EnvError, ma.ValidationError) as e:
    print(f"設定エラー: {e}")
    # エラー発生時にどうするか (デフォルト値を使う、例外を再発生させるなど)
    raise SystemExit(f"アプリケーションの設定に失敗しました: {e}") from e


# --- アプリケーションコードでの利用 ---
# from config import DEBUG, DATABASE_URL, REDIS_HOST, REDIS_PORT
#
# if DEBUG:
#     print("デバッグモードで実行中")
#
# print(f"データベース接続先: {DATABASE_URL.geturl()}") # ParseResultなので .geturl() などを使う
# print(f"Redis接続先: {REDIS_HOST}:{REDIS_PORT}")

このように設定モジュールを作成することで、設定の読み込み、パース、バリデーションを一箇所にまとめ、アプリケーションの他の部分からは `from config import SETTING_NAME` のように簡単に利用できます。

Webフレームワークでの利用 (Django, Flask)

Django や Flask などのWebフレームワークでも `environs` は非常に役立ちます。

Django

Django プロジェクトでは、`settings.py` ファイル内で `environs` を使用して環境変数や `.env` から設定を読み込むのが一般的です。

`settings.py` の例:

# settings.py
import os
from pathlib import Path
from environs import Env

env = Env()
# .env ファイルを BASE_DIR 直下から読み込む
BASE_DIR = Path(__file__).resolve().parent.parent
env.read_env(os.path.join(BASE_DIR, '.env'))

# Quick-start development settings - unsuitable for production
# See https://docs.djangoproject.com/en/stable/howto/deployment/checklist/

# SECURITY WARNING: keep the secret key used in production secret!
SECRET_KEY = env.str('SECRET_KEY') # 必須

# SECURITY WARNING: don't run with debug turned on in production!
DEBUG = env.bool('DEBUG', default=False)

ALLOWED_HOSTS = env.list('ALLOWED_HOSTS', default=['localhost', '127.0.0.1'])

# Application definition
INSTALLED_APPS = [
    # ...
]

# Database
# https://docs.djangoproject.com/en/stable/ref/settings/#databases
DATABASES = {
    # DATABASE_URL 環境変数からデータベース設定を読み込む (dj-database-url と併用すると便利)
    'default': env.dj_db_url('DATABASE_URL', default=f'sqlite:///{BASE_DIR / "db.sqlite3"}')
    # environs には Django データベース URL 用のパーサーも組み込まれている (dj-database-url が必要)
    # pip install environs[django]
}

# Email settings
EMAIL_BACKEND = env.str('EMAIL_BACKEND', default='django.core.mail.backends.console.EmailBackend')
EMAIL_HOST = env.str('EMAIL_HOST', default='localhost')
EMAIL_PORT = env.int('EMAIL_PORT', default=25)
EMAIL_HOST_USER = env.str('EMAIL_HOST_USER', default='')
EMAIL_HOST_PASSWORD = env.str('EMAIL_HOST_PASSWORD', default='')
EMAIL_USE_TLS = env.bool('EMAIL_USE_TLS', default=False)

# Static files (CSS, JavaScript, Images)
# https://docs.djangoproject.com/en/stable/howto/static-files/
STATIC_URL = '/static/'
STATIC_ROOT = env.path('STATIC_ROOT', default=BASE_DIR / 'staticfiles')

# ... 他の設定も同様に env を使って読み込む

`env.dj_db_url()` や `env.dj_cache_url()` など、Django 固有の設定形式に対応したパーサーも用意されています（`pip install environs[django]` が必要）。

Flask

Flask プロジェクトでは、アプリケーションファクトリパターンを使用している場合、設定オブジェクトや `app.config.from_mapping()` などで `environs` を利用できます。

アプリケーションファクトリ内での例:

# app.py (一部抜粋)
import os
from flask import Flask
from environs import Env

def create_app(test_config=None):
    app = Flask(__name__, instance_relative_config=True)
    env = Env()
    env.read_env() # .env ファイルを読み込む

    app.config.from_mapping(
        SECRET_KEY=env.str("SECRET_KEY"), # 必須
        DEBUG=env.bool("DEBUG", default=False),
        DATABASE_URI=env.str("DATABASE_URI", default="sqlite:///default.db"),
        # 他の Flask 設定や独自設定
        MAIL_SERVER=env.str("MAIL_SERVER", default="localhost"),
        MAIL_PORT=env.int("MAIL_PORT", default=25),
    )

    if test_config is None:
        # instance/config.py があれば読み込む (オプション)
        app.config.from_pyfile('config.py', silent=True)
    else:
        # テスト用設定を読み込む
        app.config.from_mapping(test_config)

    # アプリケーションの初期化処理（データベース接続、Blueprint登録など）
    # ...

    return app

これにより、Flask アプリケーションの設定も環境変数や `.env` ファイル経由で安全かつ柔軟に管理できます。

テストでの利用

テスト実行時には、本番や開発環境とは異なる設定（テスト用データベース、モックサービスのURLなど）を使用したい場合がよくあります。`environs` はテストコード内でも簡単に利用できます。

テスト用の `.env.test` ファイルを用意し、テスト実行前にそれを読み込むか、`unittest.mock.patch.dict` や `pytest` のフィクスチャ/フックを使って、テスト実行中だけ環境変数を一時的に変更する方法があります。

`pytest` のフィクスチャを使った例:

# tests/conftest.py
import pytest
import os

@pytest.fixture(autouse=True)
def test_env(monkeypatch):
    """テスト用の環境変数を設定するフィクスチャ"""
    monkeypatch.setenv("SECRET_KEY", "test-secret-key")
    monkeypatch.setenv("DEBUG", "True")
    monkeypatch.setenv("DATABASE_URL", "sqlite:///test.db")
    # 他のテスト用設定
    monkeypatch.setenv("API_ENDPOINT", "http://localhost:5001/mock-api")

# tests/test_config.py
from config import SECRET_KEY, DEBUG, DATABASE_URL # 設定モジュールをインポート

def test_config_loading():
    """フィクスチャによって設定された値が読み込めているか確認"""
    assert SECRET_KEY == "test-secret-key"
    assert DEBUG is True
    # DATABASE_URL は environs で ParseResult になっている場合があるため注意
    # assert str(DATABASE_URL) == "sqlite:///test.db" # 文字列比較
    assert DATABASE_URL.scheme == "sqlite" # またはオブジェクトの属性を比較

`pytest` の `monkeypatch` フィクスチャを使うと、テスト関数/モジュールの実行期間中だけ環境変数を安全に変更でき、テスト終了後には元に戻ります。これにより、テストごとに独立した環境設定でテストを実行できます。

他のライブラリとの比較 (軽く触れる) ⚖️

Python の設定管理ライブラリは `environs` 以外にもいくつか存在します。それぞれ特徴が異なるため、プロジェクトの要件に合わせて選択することが重要です。

• python-dotenv:
  • `.env` ファイルを読み込んで環境変数に設定することに特化した、非常にシンプルなライブラリ。
  • 型パースやバリデーション機能は持たないため、これらの機能が必要な場合は他のライブラリ（`environs` など）と組み合わせるか、自前で実装する必要がある。
  • シンプルさを求める場合に適している。
• Pydantic:
  • 元々はデータバリデーションとシリアライズのためのライブラリだが、設定管理機能 (`pydantic-settings`) も強力。
  • Python の型ヒントを使ってスキーマを定義し、自動で環境変数や `.env` ファイルから読み込み、バリデーションを行える。
  • 型ヒントベースの開発スタイルと相性が良い。`environs` + `marshmallow` と同様の機能を提供するが、より Pythonic な書き方ができる場合がある。
  • 多機能だが、`environs` に比べると学習コストがやや高いかもしれない。
• Dynaconf:
  • 非常に多機能な設定管理ライブラリ。
  • 環境変数、`.env` ファイル、YAML、TOML、JSON、Redis、Vault など、多様なソースから設定を階層的に読み込める。
  • 環境（development, production, testingなど）ごとの設定のマージや切り替えが容易。
  • 高機能な分、設定や使い方の理解には `environs` よりも時間がかかる可能性がある。大規模プロジェクトや複雑な設定要件を持つ場合に検討価値がある。

まとめ 🏁

`environs` は、Python アプリケーションにおける環境変数と `.env` ファイルベースの設定管理を、驚くほど簡単かつ堅牢にするライブラリです。

この記事では、以下の点について詳しく解説しました。

• 基本的な使い方（インストール、`Env` クラス、`.env` の自動読み込み）
• 豊富なデータ型パース機能（`str`, `int`, `bool`, `list`, `dict`, `url` など）
• デフォルト値の設定と必須項目の強制
• `marshmallow` と連携した強力なバリデーションとスキーマ定義
• 高度な機能（プレフィックス、ネスト設定、`seal()`）
• 実践的な利用例（設定モジュール、Webフレームワーク、テスト）

`environs` を活用することで、以下のようなメリットが得られます。

• ✨ 設定コードの簡潔化と可読性の向上
• 🛡️ 型エラーや設定漏れによるバグの早期発見
• 🔒 安全な設定管理（ハードコーディングの排除）
• 🔧 開発、ステージング、本番など、環境ごとの設定切り替えの容易化

もしあなたが Python プロジェクトで設定管理に課題を感じているなら、ぜひ `environs` の導入を検討してみてください。きっと、よりクリーンで信頼性の高いアプリケーション開発の助けとなるはずです。😊

Happy coding! 💻