Tutorial Python: Python-dotenv y variables de entorno

Configuración mediante variables de entorno

Las variables de entorno son una forma eficiente y segura de configurar aplicaciones sin codificar valores sensibles directamente en el código fuente. En el desarrollo de aplicaciones Python, estas variables permiten separar la configuración del código, facilitando el despliegue en diferentes entornos (desarrollo, pruebas, producción) sin necesidad de modificar el código.

Las variables de entorno funcionan como un conjunto de valores dinámicos que pueden afectar el comportamiento de los procesos en ejecución en un sistema operativo. En Python, podemos acceder a estas variables a través del módulo os de la biblioteca estándar.

Acceso a variables de entorno en Python

El módulo os proporciona la funcionalidad necesaria para interactuar con el sistema operativo, incluyendo el acceso a las variables de entorno:

import os

# Obtener el valor de una variable de entorno
database_url = os.environ.get('DATABASE_URL')

# Usar un valor predeterminado si la variable no existe
api_key = os.environ.get('API_KEY', 'clave_predeterminada')

# Acceso directo (lanza KeyError si no existe)
debug_mode = os.environ['DEBUG_MODE']

El método os.environ.get() es la forma recomendada para acceder a variables de entorno, ya que permite especificar un valor predeterminado si la variable no está definida, evitando errores en tiempo de ejecución.

Establecer variables de entorno

Existen varias formas de establecer variables de entorno para tu aplicación Python:

• Temporalmente en la línea de comandos (antes de ejecutar el script):

# En Linux/macOS
export DATABASE_URL="postgresql://user:password@localhost/mydb"
python app.py

# En Windows (CMD)
set DATABASE_URL=postgresql://user:password@localhost/mydb
python app.py

# En Windows (PowerShell)
$env:DATABASE_URL="postgresql://user:password@localhost/mydb"
python app.py

• Programáticamente (dentro del script Python):

import os

# Establecer una variable de entorno
os.environ['LOG_LEVEL'] = 'DEBUG'

# Modificar una variable existente
os.environ['PATH'] = f"{os.environ['PATH']}:/nueva/ruta"

Es importante destacar que las variables establecidas programáticamente solo están disponibles durante la ejecución del proceso actual y no afectan a otros procesos o sesiones.

Casos de uso comunes

Las variables de entorno son especialmente útiles para gestionar:

• Credenciales de bases de datos:

import os
import psycopg2

# Conexión segura a base de datos usando variables de entorno
connection = psycopg2.connect(
    host=os.environ.get('DB_HOST', 'localhost'),
    database=os.environ.get('DB_NAME', 'app_db'),
    user=os.environ.get('DB_USER', 'postgres'),
    password=os.environ.get('DB_PASSWORD', '')
)

• Claves API y tokens:

import os
import requests

api_key = os.environ.get('WEATHER_API_KEY')
if not api_key:
    raise ValueError("La clave API del clima no está configurada")

response = requests.get(
    f"https://api.weatherservice.com/forecast?key={api_key}&city=Madrid"
)

• Configuración específica del entorno:

import os

# Determinar el entorno de ejecución
environment = os.environ.get('ENVIRONMENT', 'development')

# Configurar la aplicación según el entorno
if environment == 'production':
    debug = False
    log_level = 'ERROR'
    server_url = 'https://api.miapp.com'
else:
    debug = True
    log_level = 'DEBUG'
    server_url = 'http://localhost:8000'

Mejores prácticas

Al trabajar con variables de entorno en Python, es recomendable seguir estas prácticas:

• Validar variables críticas al inicio de la aplicación:

import os
import sys

required_vars = ['DATABASE_URL', 'SECRET_KEY', 'API_TOKEN']
missing_vars = [var for var in required_vars if var not in os.environ]

if missing_vars:
    print(f"Error: Faltan variables de entorno requeridas: {', '.join(missing_vars)}")
    sys.exit(1)

• Centralizar la configuración en un módulo dedicado:

# config.py
import os

class Config:
    DEBUG = os.environ.get('DEBUG', 'False').lower() in ('true', '1', 't')
    SECRET_KEY = os.environ.get('SECRET_KEY', 'clave-desarrollo-insegura')
    DATABASE_URL = os.environ.get('DATABASE_URL', 'sqlite:///app.db')
    
    # Convertir tipos según sea necesario
    MAX_CONNECTIONS = int(os.environ.get('MAX_CONNECTIONS', '5'))
    TIMEOUT_SECONDS = float(os.environ.get('TIMEOUT_SECONDS', '30.0'))

• Documentar las variables de entorno requeridas:

"""
Módulo principal de la aplicación.

Variables de entorno requeridas:
- DATABASE_URL: URL de conexión a la base de datos
- SECRET_KEY: Clave secreta para cifrado
- API_KEY: Clave para acceder a servicios externos

Variables de entorno opcionales:
- DEBUG: Activa el modo de depuración (default: False)
- LOG_LEVEL: Nivel de registro (default: INFO)
"""

Consideraciones de seguridad

Al trabajar con variables de entorno para almacenar información sensible, es importante tener en cuenta:

• No registrar valores sensibles en logs o salidas de depuración:

import os
import logging

# Configuración segura de logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# Incorrecto - expone información sensible
logger.debug(f"Conectando a la base de datos con contraseña: {os.environ.get('DB_PASSWORD')}")

# Correcto - no expone información sensible
logger.info("Conectando a la base de datos...")

• Evitar incluir variables de entorno en respuestas de error o páginas de depuración:

import os
from flask import Flask, jsonify

app = Flask(__name__)
app.config['DEBUG'] = os.environ.get('DEBUG', 'False').lower() == 'true'

@app.errorhandler(500)
def handle_error(error):
    # No incluir variables de entorno o configuración sensible en respuestas de error
    return jsonify({"error": "Error interno del servidor"}), 500

Las variables de entorno proporcionan una forma flexible y segura de configurar aplicaciones Python, permitiendo adaptar el comportamiento de la aplicación a diferentes entornos sin modificar el código fuente. Esta separación entre código y configuración es un principio fundamental en el desarrollo de aplicaciones modernas y escalables.

Archivos .env

Los archivos .env son una solución elegante para gestionar variables de entorno en proyectos Python. Estos archivos de texto plano permiten almacenar configuraciones en pares clave-valor que pueden cargarse automáticamente en el entorno de ejecución de la aplicación, facilitando el desarrollo y la portabilidad del código.

Un archivo .env típico tiene una estructura muy simple, donde cada línea representa una variable de entorno en formato NOMBRE=VALOR:

# Configuración de base de datos
DATABASE_URL=postgresql://usuario:contraseña@localhost/midb
DB_PORT=5432

# Claves API (no incluir en control de versiones)
OPENAI_API_KEY=sk-abc123def456
STRIPE_SECRET_KEY=sk_test_abcdefghijklmnopqrstuvwxyz

# Configuración de la aplicación
DEBUG=True
LOG_LEVEL=INFO
MAX_WORKERS=4

Ventajas de los archivos .env

Los archivos .env ofrecen varias ventajas significativas:

• Portabilidad: Facilitan la ejecución del código en diferentes entornos sin modificar el código fuente.
• Seguridad: Permiten mantener información sensible fuera del código y del sistema de control de versiones.
• Desarrollo colaborativo: Cada desarrollador puede tener su propia configuración local sin afectar a otros.
• Simplicidad: Son archivos de texto plano fáciles de editar y entender.
• Consistencia: Centralizan todas las variables de configuración en un solo lugar.

Creación y estructura

Para implementar archivos .env en tu proyecto Python, sigue estos pasos:

1. Crea un archivo llamado .env en la raíz de tu proyecto:

touch .env  # En sistemas Unix/Linux/macOS
# O simplemente crea un nuevo archivo de texto en Windows

2. Añade tus variables de entorno siguiendo estas convenciones:

# Las variables suelen escribirse en MAYÚSCULAS
VARIABLE_NAME=value

# Los valores no necesitan comillas (aunque se pueden usar)
MESSAGE=Hello World
MESSAGE_WITH_QUOTES="Hello World"

# Puedes incluir espacios sin comillas
GREETING=Hello there user

# Puedes usar variables dentro de otras variables
BASE_DIR=/app
MEDIA_DIR=${BASE_DIR}/media

# Los comentarios comienzan con #
# Esta es una configuración importante
SECRET_KEY=my_secret_key

Buenas prácticas con archivos .env

Para aprovechar al máximo los archivos .env, considera estas prácticas recomendadas:

1. Excluir del control de versiones: Siempre añade .env a tu archivo .gitignore para evitar compartir información sensible:

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

2. Proporcionar plantillas: Incluye un archivo .env.example en tu repositorio como referencia:

# .env.example
DATABASE_URL=postgresql://user:password@localhost/dbname
API_KEY=your_api_key_here
DEBUG=False

3. Validar variables requeridas: Verifica que todas las variables necesarias estén definidas:

import os
from dotenv import load_dotenv

load_dotenv()

required_vars = ['DATABASE_URL', 'SECRET_KEY']
missing = [var for var in required_vars if os.environ.get(var) is None]
if missing:
    raise EnvironmentError(f"Faltan variables de entorno requeridas: {', '.join(missing)}")

4. Organizar por entornos: Puedes tener múltiples archivos para diferentes entornos:

.env                # Variables compartidas/predeterminadas
.env.development    # Variables específicas de desarrollo
.env.test           # Variables para pruebas
.env.production     # Variables para producción

5. Documentar las variables: Incluye comentarios explicativos en tus archivos .env:

# Puerto en el que se ejecutará el servidor web
# Valores válidos: 1024-65535
PORT=8000

# Nivel de registro (DEBUG, INFO, WARNING, ERROR, CRITICAL)
LOG_LEVEL=INFO

Estructura de directorios recomendada

Una estructura de proyecto que incorpora archivos .env podría verse así:

mi_proyecto/
├── .env                # Variables de entorno locales (no en control de versiones)
├── .env.example        # Plantilla de variables (sí en control de versiones)
├── .gitignore          # Incluye .env pero no .env.example
├── config.py           # Módulo para cargar la configuración
├── app/
│   ├── __init__.py
│   ├── models.py
│   └── views.py
└── tests/
    ├── __init__.py
    └── test_config.py

Ejemplo de archivo .env completo

Un archivo .env para una aplicación web típica podría contener:

# Configuración de la aplicación
APP_NAME=Mi Aplicación Genial
DEBUG=True
SECRET_KEY=clave_super_secreta_y_larga_para_produccion
PORT=8000

# Base de datos
DB_ENGINE=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_NAME=miapp_db
DB_USER=postgres
DB_PASSWORD=contraseña_segura

# Servicios externos
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=notificaciones@miapp.com
SMTP_PASSWORD=contraseña_email_segura

# APIs de terceros
GOOGLE_MAPS_API_KEY=AIzaSyA1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6
WEATHER_API_KEY=abcdef123456789

# Configuración de caché
REDIS_URL=redis://localhost:6379/0
CACHE_TIMEOUT=3600

# Límites y cuotas
MAX_UPLOAD_SIZE=10485760  # 10MB en bytes
RATE_LIMIT=100  # Peticiones por minuto

Limitaciones y consideraciones

A pesar de sus ventajas, los archivos .env tienen algunas limitaciones:

• No son adecuados para secretos en producción en entornos empresariales (para eso existen soluciones como AWS Secrets Manager, HashiCorp Vault, etc.)
• No ofrecen validación de tipos por sí mismos (los valores son siempre cadenas de texto)
• Pueden generar inconsistencias si no se mantienen actualizados entre diferentes entornos
• No son apropiados para configuraciones complejas o anidadas (para eso son mejores los archivos YAML o JSON)

Para superar estas limitaciones, muchos proyectos combinan archivos .env con módulos de configuración más sofisticados:

# config.py
import os
from typing import cast
from dotenv import load_dotenv

# Cargar variables desde .env
load_dotenv()

class Config:
    # Convertir tipos según sea necesario
    DEBUG = os.environ.get('DEBUG', 'False').lower() in ('true', 'yes', '1', 't')
    PORT = int(os.environ.get('PORT', '8000'))
    
    # Valores con defaults seguros
    SECRET_KEY = os.environ.get('SECRET_KEY', os.urandom(24).hex())
    
    # Configuración de base de datos
    DATABASE_URL = os.environ.get('DATABASE_URL')
    
    # Configuración condicional basada en el entorno
    if os.environ.get('ENVIRONMENT') == 'testing':
        DATABASE_URL = 'sqlite:///:memory:'
        DEBUG = True

Los archivos .env son una herramienta fundamental en el desarrollo moderno de aplicaciones Python, permitiendo una gestión de configuración flexible y segura. Combinados con bibliotecas como python-dotenv, proporcionan una solución robusta para manejar variables de entorno en diferentes contextos de desarrollo.

Carga automática de variables

La carga automática de variables de entorno desde archivos .env es una práctica esencial en el desarrollo moderno de aplicaciones Python. Esta técnica permite que nuestras aplicaciones accedan a la configuración almacenada en archivos .env sin necesidad de cargar manualmente cada variable, simplificando enormemente el proceso de desarrollo y despliegue.

La biblioteca más utilizada para esta tarea es python-dotenv, que proporciona una forma sencilla y eficiente de cargar variables de entorno desde archivos .env directamente en el entorno de ejecución de Python.

Instalación de python-dotenv

Antes de utilizar esta biblioteca, necesitamos instalarla mediante pip:

pip install python-dotenv

Para proyectos que utilizan gestión de dependencias, también podemos añadirla a nuestro archivo requirements.txt o pyproject.toml:

# En requirements.txt
python-dotenv==1.0.0

Carga básica de variables

La forma más simple de cargar variables desde un archivo .env es utilizando la función load_dotenv():

from dotenv import load_dotenv
import os

# Carga las variables del archivo .env en os.environ
load_dotenv()

# Ahora podemos acceder a las variables como lo haríamos normalmente
database_url = os.environ.get("DATABASE_URL")
api_key = os.environ.get("API_KEY")

Por defecto, load_dotenv() busca un archivo llamado .env en el directorio actual. La función devuelve True si encuentra y carga el archivo, y False en caso contrario.

Opciones de carga avanzadas

La función load_dotenv() acepta varios parámetros que nos permiten personalizar su comportamiento:

from dotenv import load_dotenv
import os
from pathlib import Path

# Especificar una ruta personalizada para el archivo .env
dotenv_path = Path("ruta/a/mi/.env")
load_dotenv(dotenv_path=dotenv_path)

# Forzar la sobrescritura de variables existentes
load_dotenv(override=True)

# Cargar solo variables específicas
load_dotenv(dotenv_path=".env.development", encoding="utf-8")

Los parámetros más útiles incluyen:

• dotenv_path: Ruta al archivo .env (por defecto busca .env en el directorio actual)
• override: Si es True, sobrescribe las variables existentes en el entorno (por defecto es False)
• encoding: Especifica la codificación del archivo (por defecto es utf-8)

Carga en el punto de entrada de la aplicación

La práctica recomendada es cargar las variables de entorno lo antes posible en el ciclo de vida de la aplicación, típicamente en el punto de entrada principal:

# app.py (archivo principal de la aplicación)
from dotenv import load_dotenv
import os

# Cargar variables al inicio
load_dotenv()

# Resto de importaciones
from flask import Flask
from config import Config

app = Flask(__name__)
app.config.from_object(Config)

# ...resto del código

Carga automática en diferentes entornos

Una técnica muy útil es cargar diferentes archivos .env según el entorno de ejecución:

import os
from dotenv import load_dotenv

# Determinar qué archivo .env cargar según la variable ENVIRONMENT
env_name = os.environ.get("ENVIRONMENT", "development")
env_file = f".env.{env_name}"

# Cargar primero el .env común y luego el específico del entorno
load_dotenv(".env")  # Variables comunes a todos los entornos
load_dotenv(env_file, override=True)  # Variables específicas del entorno

Esto permite tener una configuración base en .env y configuraciones específicas en archivos como .env.development, .env.testing o .env.production.

Integración con find_dotenv()

La función find_dotenv() es útil para localizar automáticamente el archivo .env incluso cuando el script se ejecuta desde diferentes directorios:

from dotenv import load_dotenv, find_dotenv
import os

# Busca el archivo .env navegando hacia arriba en el árbol de directorios
dotenv_path = find_dotenv()
load_dotenv(dotenv_path)

# También podemos buscar un archivo específico
config_path = find_dotenv(filename=".env.test")
load_dotenv(config_path)

Esta función es especialmente útil en proyectos con estructuras de directorios complejas o cuando ejecutamos scripts desde diferentes ubicaciones.

Carga programática de variables

A veces necesitamos cargar variables de forma programática, sin depender de archivos físicos:

from dotenv import load_dotenv
import io

# Crear un archivo .env virtual
env_content = """
DEBUG=True
API_URL=https://api.example.com
MAX_CONNECTIONS=5
"""

# Cargar desde un objeto StringIO
load_dotenv(stream=io.StringIO(env_content))

Esta técnica es útil para pruebas automatizadas o cuando necesitamos generar configuraciones dinámicamente.

Integración con frameworks web

Muchos frameworks web de Python tienen integración directa o indirecta con python-dotenv. Por ejemplo, en Flask:

# Con Flask
from flask import Flask
from dotenv import load_dotenv

load_dotenv()  # Cargar variables antes de crear la aplicación
app = Flask(__name__)

En Django, podemos añadir la carga en el archivo settings.py:

# En settings.py de Django
import os
from dotenv import load_dotenv

# Cargar variables de entorno al inicio
load_dotenv()

# Configuración de Django
SECRET_KEY = os.environ.get('SECRET_KEY')
DEBUG = os.environ.get('DEBUG', 'False').lower() == 'true'

Carga automática en scripts de línea de comandos

Para scripts que se ejecutan desde la línea de comandos, podemos usar el módulo dotenv.cli:

# Ejecutar un script con variables de .env cargadas automáticamente
python -m dotenv run -- python mi_script.py

También podemos crear nuestros propios scripts con carga automática:

#!/usr/bin/env python
# mi_script.py

import sys
from dotenv import load_dotenv

# Cargar variables al inicio
load_dotenv()

# Resto del script
import os
print(f"Conectando a: {os.environ.get('DATABASE_URL')}")

Validación de variables cargadas

Una buena práctica es validar que todas las variables necesarias se hayan cargado correctamente:

from dotenv import load_dotenv
import os
import sys

# Cargar variables
load_dotenv()

# Lista de variables requeridas
required_vars = ["DATABASE_URL", "SECRET_KEY", "API_TOKEN"]

# Verificar que todas existan
missing = [var for var in required_vars if os.environ.get(var) is None]
if missing:
    print(f"Error: Faltan las siguientes variables de entorno: {', '.join(missing)}")
    print("Por favor, verifica tu archivo .env")
    sys.exit(1)

# Continuar con la ejecución normal si todas las variables están presentes
print("Configuración cargada correctamente")

Carga automática con tipado

Para aplicaciones que requieren un tipado más estricto, podemos combinar python-dotenv con pydantic:

from dotenv import load_dotenv
from pydantic import BaseSettings, Field

# Cargar variables primero
load_dotenv()

class Settings(BaseSettings):
    # Definir variables con tipos y valores predeterminados
    debug: bool = Field(False, env="DEBUG")
    port: int = Field(8000, env="PORT")
    database_url: str = Field(..., env="DATABASE_URL")  # ... indica que es obligatorio
    
    class Config:
        # Configuración adicional de pydantic
        env_file = ".env"
        env_file_encoding = "utf-8"

# Crear una instancia de configuración
settings = Settings()

# Usar la configuración tipada
print(f"Modo debug: {settings.debug}")
print(f"Puerto: {settings.port}")

Esta aproximación proporciona validación de tipos, valores predeterminados y documentación integrada para nuestras variables de entorno.

Rendimiento y consideraciones

La carga de variables desde archivos .env tiene un impacto mínimo en el rendimiento, pero hay algunas consideraciones a tener en cuenta:

• La carga debe realizarse solo una vez al inicio de la aplicación
• En entornos de producción, es preferible usar variables de entorno nativas del sistema
• Para aplicaciones con alta concurrencia, considera cargar la configuración en un objeto compartido

# Patrón singleton para configuración
class Config:
    _instance = None
    
    @classmethod
    def get_instance(cls):
        if cls._instance is None:
            from dotenv import load_dotenv
            load_dotenv()
            cls._instance = cls()
        return cls._instance
    
    def __init__(self):
        import os
        self.debug = os.environ.get("DEBUG", "False").lower() == "true"
        self.database_url = os.environ.get("DATABASE_URL")
        # Más variables...

# Uso
config = Config.get_instance()
print(config.debug)

La carga automática de variables de entorno con python-dotenv simplifica enormemente la gestión de configuración en aplicaciones Python, permitiendo un desarrollo más ágil y seguro. Al separar la configuración del código, nuestras aplicaciones se vuelven más mantenibles, portables y fáciles de desplegar en diferentes entornos.