environs: типизированные переменные окружения

environs — библиотека для чтения переменных окружения из .env файла с поддержкой типов. Это эволюция python-dotenv: не просто загружает строки, а возвращает нужные типы и падает с понятной ошибкой если переменная не задана.

Зачем не python-dotenv

# python-dotenv + os.getenv:
from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv("ANTHROPIC_API_KEY")  # строка или None
debug = os.getenv("DEBUG")               # "True" — это строка, не bool!
port = int(os.getenv("PORT", "8000"))    # приходится конвертировать вручную

# Если переменная не задана — None, программа упадёт где-то глубже
# с непонятным AttributeError: 'NoneType'

# environs:
from environs import Env

env = Env()
env.read_env()
api_key = env.str("ANTHROPIC_API_KEY")   # строка — явно
debug = env.bool("DEBUG", False)         # настоящий bool
port = env.int("PORT", 8000)            # настоящий int

# Если ANTHROPIC_API_KEY не задан — EnvError сразу при старте:
# environs.EnvError: 'ANTHROPIC_API_KEY' not set or empty

С environs типы объявлены явно, ошибки вылезают сразу при запуске — не в середине работы программы.

Установка

uv add environs

Базовое использование

from environs import Env

env = Env()
env.read_env()  # читает .env из текущей папки

# Строки
api_key = env.str("ANTHROPIC_API_KEY")
base_url = env.url("API_BASE_URL")

# Числа
port = env.int("PORT", 8000)           # с дефолтом
timeout = env.float("TIMEOUT", 30.0)

# Булевы значения
debug = env.bool("DEBUG", False)       # "true", "1", "yes", "on" → True

# Списки
hosts = env.list("ALLOWED_HOSTS", []) # "a,b,c" → ["a", "b", "c"]

Обязательные и необязательные переменные

# Обязательная — бросит EnvError если не установлена:
api_key = env.str("ANTHROPIC_API_KEY")

# Необязательная — вернёт дефолт:
model = env.str("MODEL", "claude-sonnet-4-6")
max_tokens = env.int("MAX_TOKENS", 2048)

Всегда делай переменную обязательной если без неё программа не может работать. Лучше явная ошибка при старте чем загадочный сбой в середине работы.

.env файл

ANTHROPIC_API_KEY=sk-ant-api03-...
MODEL=claude-sonnet-4-6
MAX_TOKENS=2048
DEBUG=false

Правила .env:
- Один ключ = одна строка
- Нет пробелов вокруг =
- Строки без кавычек (можно с, но не нужно)
- Комментарии через #

.env в .gitignore — обязательно

Файл .env содержит секреты — его нельзя коммитить ни при каких обстоятельствах.

# .gitignore
.env
.env.local
.env.*.local

Для команды создай .env.example с пустыми значениями и закоммить его:

# .env.example — можно коммитить
ANTHROPIC_API_KEY=
MODEL=claude-sonnet-4-6
MAX_TOKENS=2048
DEBUG=false

config.py — единое место для конфигурации

Лучшая практика — вынести всю конфигурацию в отдельный файл:

# config.py
from environs import Env

env = Env()
env.read_env()

API_KEY = env.str("ANTHROPIC_API_KEY")
MODEL = env.str("MODEL", "claude-sonnet-4-6")
MAX_TOKENS = env.int("MAX_TOKENS", 2048)
DEBUG = env.bool("DEBUG", False)

Все остальные файлы импортируют из config.py — никакого дублирования загрузки env.

# main.py
from config import API_KEY, MODEL, MAX_TOKENS