Arquivos .env e python-dotenv

O problema das exportações do shell

O formato do arquivo .env

# .env file (NEVER commit this file to git)

# Required API keys
OPENAI_API_KEY=sk-proj-your-real-key-here
SEARCH_API_KEY=tvly-your-tavily-key-here

# Optional settings with defaults
AGENT_MODEL=gpt-4o-mini
AGENT_MAX_STEPS=20
LOG_LEVEL=DEBUG

# Database (optional — disables memory storage if not set)
# DATABASE_URL=postgresql://user:pass@localhost/agentdb

# Environment identifier
ENV=development

Carregando .env com python-dotenv

# pip install python-dotenv
from dotenv import load_dotenv
import os

# Load .env file — call this BEFORE reading any env vars
load_dotenv()

# Now all variables from .env are available via os.environ
openai_key = os.environ['OPENAI_API_KEY']
model = os.getenv('AGENT_MODEL', 'gpt-4o-mini')
max_steps = int(os.getenv('AGENT_MAX_STEPS', '20'))

print(f'Model: {model}, Max steps: {max_steps}')

Opções de load_dotenv()

from dotenv import load_dotenv
import os

# Load from a specific path
load_dotenv(dotenv_path='/path/to/custom/.env')

# Override existing environment variables
# (by default, existing vars are NOT overridden)
load_dotenv(override=True)

# Load a specific environment file
env_file = os.getenv('ENV_FILE', '.env')
load_dotenv(dotenv_path=env_file, verbose=True)

# Find .env automatically (searches up the directory tree)
from dotenv import find_dotenv
load_dotenv(find_dotenv())

dotenv_values() para dicionários de configuração explícitos

from dotenv import dotenv_values

# Read .env into a dict without touching os.environ
config = dotenv_values('.env')

print(config.get('AGENT_MODEL'))   # 'gpt-4o-mini'
print(config.get('LOG_LEVEL'))     # 'DEBUG'

# Merge .env with actual environment (env vars take priority)
import os
combined = {**dotenv_values('.env'), **os.environ}

# This means actual environment variables override .env values
# Useful for CI where env vars are injected by the pipeline

O arquivo .env.example

# .env.example — commit this file to git
# Copy to .env and fill in real values:
# cp .env.example .env

# Required API keys (get from respective providers)
OPENAI_API_KEY=sk-proj-your-openai-key-here
SEARCH_API_KEY=tvly-your-tavily-key-here

# Optional settings
AGENT_MODEL=gpt-4o-mini
AGENT_MAX_STEPS=20
LOG_LEVEL=INFO
ENV=development

# Database (optional)
# DATABASE_URL=postgresql://user:password@localhost:5432/agentdb

Adicionando .env ao .gitignore

# .gitignore — add these lines

# Environment files with real secrets
.env
.env.local
.env.production
.env.staging

# But DO commit these:
# .env.example  (placeholder values, safe to share)

# Verify .env is ignored before committing:
# git check-ignore -v .env
# .gitignore:1:.env   .env    <-- means it IS ignored (good)

# If .env was already tracked:
# git rm --cached .env
# git commit -m 'Remove .env from tracking'
# echo '.env' >> .gitignore

Gancho de pré-confirmação para bloquear confirmações de .env

# .git/hooks/pre-commit (make executable: chmod +x .git/hooks/pre-commit)

#!/bin/sh
# Block commits that include .env files with real content
if git diff --cached --name-only | grep -qE '^\.env$';
then
  echo 'ERROR: .env file is staged for commit!'
  echo 'This file contains secrets and must NOT be committed.'
  echo 'Run: git reset HEAD .env'
  exit 1
fi

# Also check for common secret patterns in any staged file
if git diff --cached | grep -qE '(sk-proj-|tvly-|xai-)';
then
  echo 'WARNING: Possible API key detected in staged changes!'
  echo 'Review carefully before committing.'
fi

exit 0

Carregando .env em diferentes estruturas

# FastAPI with pydantic-settings (auto-loads .env):
# pip install pydantic-settings
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    openai_api_key: str
    agent_model: str = 'gpt-4o-mini'
    log_level: str = 'INFO'

    class Config:
        env_file = '.env'

# settings = Settings()  # auto-reads .env and validates types
# print(settings.agent_model)  # 'gpt-4o-mini'

# FastAPI is also fine with plain load_dotenv() at the top of main.py
# No need to use pydantic-settings for simple agents

Vários arquivos .env para diferentes ambientes

import os
from dotenv import load_dotenv

# Determine which environment to load
env = os.getenv('ENV', 'development')

# Try environment-specific file first, fall back to base .env
env_file = f'.env.{env}'
if os.path.exists(env_file):
    load_dotenv(env_file)
    print(f'Loaded {env_file}')
else:
    load_dotenv('.env')
    print('Loaded .env')

# Usage:
# ENV=staging python agent.py     -> loads .env.staging
# ENV=production python agent.py  -> loads .env.production
# python agent.py                 -> loads .env (default development)

Lista de verificação completa da configuração

Verificação de conhecimento: arquivos .env e python-dotenv

Recapitulação: arquivos .env e python-dotenv