Advertencias y Deprecaciones

El módulo warnings señala problemas recuperables y deprecaciones de API sin lanzar excepciones. Configure filtros para mostrar, ignorar o escalar advertencias; las bibliotecas usan DeprecationWarning para eliminaciones programadas.

Receta

import warnings
 
warnings.warn("old_api está obsoleto; use new_api", DeprecationWarning, stacklevel=2)

Cuándo usar esto:

• Para marcar funciones/clases como obsoletas antes de su eliminación.
• Notificaciones en tiempo de ejecución sobre usos subóptimos (no errores).
• Los mantenedores de bibliotecas advierten sin romper inmediatamente a los llamadores.
• CI -W error convierte las advertencias en fallos de prueba.
• Distinguir el código del usuario (UserWarning) del interno (DeprecationWarning).

Ejemplo Funcional

import warnings
 
warnings.simplefilter("default", DeprecationWarning)
 
def old_price(amount: float) -> float:
    warnings.warn(
        "old_price está obsoleto; use compute_price",
        DeprecationWarning,
        stacklevel=2,
    )
    return amount * 1.1
 
def compute_price(amount: float) -> float:
    return amount * 1.1
 
warnings.filterwarnings("once", category=UserWarning, module=__name__)
 
def maybe_risky(flag: bool) -> None:
    if flag:
        warnings.warn("ruta experimental habilitada", UserWarning, stacklevel=2)
 
old_price(10)
maybe_risky(True)
maybe_risky(True)  # el filtro "once" suprime duplicados

Lo que esto demuestra:

• stacklevel=2 apunta la advertencia al llamador, no al envoltorio.
• Categoría DeprecationWarning para el fin de vida de la API.
• filterwarnings("once") evita el spam en el registro.
• Filtros con alcance por categoría y módulo.

Profundización

Cómo Funciona

• warnings.warn(message, category, stacklevel) emite WarningMessage.
• Por defecto: muestra cada advertencia una vez por ubicación a stderr.
• warnings.filterwarnings(action, category, ...) controla el comportamiento.
• pytest.warns afirma advertencias en las pruebas.
• Decorador @warnings.deprecated (3.13+) para funciones.

Categorías Comunes

Errores Comunes

• stacklevel incorrecto: la advertencia culpa a la línea de la biblioteca. Solución: incrementar stacklevel por cada capa de envoltorio.
• DeprecationWarning invisible en REPL: los filtros por defecto lo ocultan de lo que no es __main__. Solución: documentar warnings.simplefilter para la entrada de la aplicación o ejecutar pruebas con -W default::DeprecationWarning.
• Usar advertencias para flujo de control: no son excepciones, fáciles de pasar por alto. Solución: usar advertencias solo para deprecaciones, no para lógica de negocio.
• Romper CI sin política: -W error falla ante cualquier advertencia. Solución: tratar las deprecaciones como errores, permitir temporalmente el ruido de terceros.
• Sin línea de tiempo de eliminación en el mensaje: los usuarios no pueden planificar. Solución: incluir la versión de eliminación objetivo en el texto de la advertencia.

Alternativas

Preguntas Frecuentes

Relacionado

• El Módulo Logging - integración de captureWarnings
• Jerarquías de Excepciones Personalizadas - cambios disruptivos vs advertencias suaves
• Mejores Prácticas de Errores y Registro - política de deprecación
• Lanzamiento y Encadenamiento - cuándo lanzar en su lugar

Versiones de Pila: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.