Saltearse al contenido

Configuración tipada

La configuración es la frontera entre el código y el mundo. Todo lo que cambia entre entornos —URLs, credenciales, límites, niveles de log— entra por ahí, y casi todos los incidentes de despliegue empiezan con una configuración que estaba mal y nadie comprobó al arrancar.

La configuración se lee una vez, se valida al arrancar y se pasa como un objeto; nunca se consulta el entorno a mitad de una petición.

import os
from dataclasses import dataclass
@dataclass(frozen=True)
class Config:
base_datos: str
nivel_log: str = "INFO"
timeout: float = 5.0
debug: bool = False
@classmethod
def desde_entorno(cls, env: dict[str, str] | None = None) -> "Config":
env = os.environ if env is None else env
try:
return cls(
base_datos=env["DATABASE_URL"],
nivel_log=env.get("LOG_LEVEL", "INFO"),
timeout=float(env.get("TIMEOUT", "5")),
debug=env.get("DEBUG", "0").lower() in {"1", "true", "yes"},
)
except KeyError as e:
raise SystemExit(f"falta la variable {e.args[0]}") from None

Tres decisiones dentro de esas líneas:

  • frozen=True: la configuración no cambia en ejecución. Si algo necesita cambiar, es estado, no configuración.
  • El parámetro env: permite probar sin tocar el entorno del proceso. Es la diferencia entre un test de configuración y un test que depende de la máquina.
  • raise SystemExit: falla al arrancar, con un mensaje que dice qué falta. Un servicio que arranca con la URL de base de datos vacía es peor que uno que no arranca.

Cuando hay varias fuentes, el orden tiene que ser explícito y documentado:

argumentos de línea de comandos
> variables de entorno
> archivo de configuración
> valores por defecto del código

Es el orden de ChainMap (Parte II, capítulo 10): el primero que tenga el valor gana. Lo importante no es el orden elegido sino que sea el mismo en todos los componentes; dos servicios que leen la misma variable con prioridades distintas producen el incidente más difícil de explicar.

Una cadena de conexión mal formada no falla hasta la primera consulta, cinco minutos después del despliegue. Valida al construir:

if not config.base_datos.startswith(("postgresql://", "sqlite://")):
raise SystemExit("DATABASE_URL debe empezar por postgresql:// o sqlite://")

Y una comprobación que casi nadie hace: valores de producción en desarrollo. Un DEBUG=1 en producción filtra trazas con datos; un LOG_LEVEL=DEBUG multiplica el volumen y el coste. El código puede comprobar que la combinación es coherente con el entorno declarado.

  • Un script local: dos variables en sys.argv y ya.
  • Si el equipo despliega con el mismo entorno siempre: menos fuentes, menos confusión.
  • Sin validación: aceptable sólo si el fallo es inmediato y obvio.

Un servicio tiene DEBUG en una variable de entorno global de la máquina y LOG_LEVEL en el archivo de configuración del contenedor. En desarrollo funciona; en producción el log se llena de trazas y se ve lento. Explica qué pasó y cómo se arregla el diseño.

Solución

El servicio lee DEBUG del entorno de la máquina, que en producción está activado por otra aplicación, y LOG_LEVEL del archivo. La combinación da depuración activa con nivel alto: el peor de los dos mundos, porque el código cree estar en desarrollo.

Arreglo de diseño:

  1. Una sola fuente por entorno. El archivo del contenedor define todo lo que cambia; las variables de entorno sólo sobrescriben lo que debe cambiar en el despliegue.
  2. Prefijo por aplicación. MIAPP_DEBUG en lugar de DEBUG: dos servicios en la misma máquina no se pisan.
  3. Validación de coherencia al arrancar. Si DEBUG está activo y el entorno declarado es production, fallar con un mensaje claro.
  4. Registrar la configuración efectiva al arrancar, sin secretos: es lo que permite responder «¿por qué estaba en debug?» en treinta segundos.

La causa raíz no es la variable: es que el código consulta el entorno en varios sitios con prioridades distintas. Un objeto Config construido una vez y pasado explícitamente hace imposible ese desajuste.

  • Ramalho, L. Fluent Python, 2ª ed. Capítulo 5.
  • Lott, S. F. Modern Python Cookbook, 3ª ed. Capítulo 13: integración de aplicaciones.
  • 01 · Paquetes y entornos: de dónde se lee.
  • 04 · Logging: el nivel que la configuración controla.
  • 07 · Seguridad: los secretos que no deben estar en el código.