# `warnings` — Warning control

Código fuente: Lib/warnings.py

Los mensajes de advertencia suelen emitirse en situaciones en las que es útil alertar al usuario de alguna condición en un programa, cuando esa condición (normalmente) no justifica que se haga una excepción y se termine el programa. Por ejemplo, se puede emitir una advertencia cuando un programa utiliza un módulo obsoleto.

Los programadores de Python emiten advertencias llamando a la función `warn()` definida en este módulo. (Los programadores de C usan `PyErr_WarnEx()`; ver Manejo de excepciones para más detalles)

Los mensajes de advertencia se escriben normalmente en `sys.stderr`, pero su disposición puede cambiarse de manera flexible, desde ignorar todas las advertencias hasta convertirlas en excepciones. La disposición de las advertencias puede variar en función de la warning category, el texto del mensaje de advertencia y la ubicación de la fuente donde se emite. Las repeticiones de una advertencia particular para la misma ubicación de la fuente son típicamente suprimidas.

El control de las advertencias consta de dos etapas: en primer lugar, cada vez que se emite una advertencia, se determina si se debe emitir un mensaje o no; en segundo lugar, si se debe emitir un mensaje, se le da formato y se imprime utilizando un gancho establecido por el usuario.

La determinación de si se debe emitir un mensaje de advertencia está controlada por el warning filter, que es una secuencia de reglas y acciones que coinciden. Se pueden añadir reglas al filtro llamando a `filterwarnings()` y restablecer su estado por defecto llamando a `resetwarnings()`.

La impresión de los mensajes de advertencia se realiza llamando a `showwarning()`, que puede ser anulado; la implementación por defecto de esta función da formato al mensaje llamando a `formatwarning()`, que también está disponible para su uso en implementaciones personalizadas.

Ver también

`logging.captureWarnings()` permite manejar todas las advertencias con la infraestructura de registro estándar.

## Categorías de advertencia

Hay una serie de excepciones incorporadas que representan categorías de advertencia. Esta categorización es útil para poder filtrar grupos de advertencias.

Aunque técnicamente se trata de built-in exceptions, están documentadas aquí, porque pertenecen al mecanismo de advertencias.

El código de usuario puede definir categorías de advertencia adicionales mediante la subclasificación de una de las categorías de advertencia estándar. Una categoría de advertencia siempre debe ser una subclase de la clase `Warning` class.

Actualmente están definidas las siguientes clases de categorías de advertencias:

Clase | Descripción
--- | ---
`Warning` | Esta es la clase principal para todas las clases que pertenecen a la categoría de advertencia. Es una subclase de `Exception`.
`UserWarning` | La categoría por defecto para `warn()`.
`DeprecationWarning` | Categoría principal para advertencias sobre características obsoletas cuando esas advertencias están destinadas a otros desarrolladores de Python (ignoradas por defecto, a menos que sean activadas por el código en `__main__`).
`SyntaxWarning` | Categoría principal para las advertencias sobre características sintácticas dudosas.
`RuntimeWarning` | Categoría principal para las advertencias sobre características dudosas de tiempo de ejecución.
`FutureWarning` | Categoría principal para las advertencias sobre características obsoletas cuando esas advertencias están destinadas a los usuarios finales de aplicaciones escritas en Python.
`PendingDeprecationWarning` | Categoría principal para las advertencias sobre las características que serán desaprobadas en el futuro (ignoradas por defecto).
`ImportWarning` | Categoría principal para las advertencias que se activan durante el proceso de importación de un módulo (se ignoran por defecto).
`UnicodeWarning` | Categoría principal para las advertencias relacionadas con Unicode.
`BytesWarning` | Categoría principal para las advertencias relacionadas con `bytes` y `bytearray`.
`ResourceWarning` | Categoría base para las advertencias relacionadas con el uso de los recursos (ignorada por defecto).

Distinto en la versión 3.7: Anteriormente `DeprecationWarning` y `FutureWarning` se distinguían en función de si una característica se eliminaba por completo o se cambiaba su comportamiento. Ahora se distinguen en función de su público objetivo y de la forma en que son manejados por los filtros de advertencia predeterminados.

## El filtro de advertencias

El filtro de advertencias controla si las advertencias se ignoran, se muestran o se convierten en errores (planteando una excepción).

Conceptualmente, el filtro de advertencias mantiene una lista ordenada de especificaciones de filtros; cualquier advertencia específica se compara con cada especificación de filtro de la lista por turno hasta que se encuentra una coincidencia; el filtro determina la disposición de la coincidencia. Cada entrada es una tupla de la forma (action, message, category, module, lineno), donde:

- action es una de las siguientes cadenas:

  Valor | Disposición
  --- | ---
  `"default"` | imprime la primera ocurrencia de advertencias coincidentes para cada lugar (módulo + número de línea) donde se emite la advertencia
  `"error"` | convertir las advertencias de coincidencia en excepciones
  `"ignore"` | nunca imprime advertencias que coincidan
  `"always"` | siempre imprime advertencias que coinciden
  `"module"` | imprime la primera ocurrencia de advertencias coincidentes para cada módulo en el que se emite la advertencia (independientemente del número de línea)
  `"once"` | imprime sólo la primera aparición de advertencias coincidentes, independientemente de la ubicación

- message esa cadena de caracteres que contiene una expresión regular que debería coincidir con el inicio del mensaje de advertencia, sin discriminar mayúsculas ni minúsculas. En `-W` y `PYTHONWARNINGS`, message es una cadena de caracteres literal que debería coincidir con el inicio del mensaje de advertencia discriminando mayúsculas y/o minúsculas, pero ignorando cualquier espacio en blanco al inicio de message.

- category es una clase (una subclase de `Warning`) de la cual la categoría de advertencia debe ser una subclase para poder coincidir.

- module es un cadena de caracteres que contiene una expresión regular, la cual debe coincidir exactamente (con mayúsculas y minúsculas) al nombre completo del módulo. En `-W` y `PYTHONWARNINGS`, module es string literal que debe ser igual (con mayúsculas y minúsculas) al nombre completo del módulo, ignorando cualquier espacio en blanco al inicio o final de module.

- lineno es un número entero que el número de línea donde ocurrió la advertencia debe coincidir, o `0` para coincidir con todos los números de línea.

Como la clase `Warning` se deriva de la clase `Excepción` incorporada, para convertir una advertencia en un error simplemente lanzamos `category(message)`.

Si se informa de una advertencia y no coincide con ningún filtro registrado, se aplica la acción «por defecto» (de ahí su nombre).

### Repeated Warning Suppression Criteria

The filters that suppress repeated warnings apply the following criteria to determine if a warning is considered a repeat:

- `"default"`: A warning is considered a repeat only if the (message, category, module, lineno) are all the same.

- `"module"`: A warning is considered a repeat if the (message, category, module) are the same, ignoring the line number.

- `"once"`: A warning is considered a repeat if the (message, category) are the same, ignoring the module and line number.

### Descripción de los filtros de advertencia

El filtro de advertencias se inicializa con `-W` options pasado a la línea de comandos del intérprete de Python y la variable de entorno `PYTHONWARNINGS`. El intérprete guarda los argumentos de todas las entradas suministradas sin interpretación en `sys.warnoptions`; el módulo `warnings` los analiza cuando se importa por primera vez (las opciones no válidas se ignoran, después de imprimir un mensaje a `sys.stderr`).

Los filtros de advertencia individuales se especifican como una secuencia de campos separados por dos puntos:

    action:message:category:module:line

El significado de cada uno de estos campos es como se describe en El filtro de advertencias. Cuando se enumeran varios filtros en una sola línea (como en `PYTHONWARNINGS`), los filtros individuales se separan por comas y los filtros que se enumeran más tarde tienen prioridad sobre los que se enumeran antes de ellos (ya que se aplican de izquierda a derecha, y los filtros aplicados más recientemente tienen prioridad sobre los anteriores).

Los filtros de advertencia comúnmente utilizados se aplican a todas las advertencias, a las advertencias de una categoría particular o a las advertencias planteadas por módulos o paquetes particulares. Algunos ejemplos:

    default                      # Show all warnings (even those ignored by default)
    ignore                       # Ignore all warnings
    error                        # Convert all warnings to errors
    error::ResourceWarning       # Treat ResourceWarning messages as errors
    default::DeprecationWarning  # Show DeprecationWarning messages
    ignore,default:::mymodule    # Only report warnings triggered by "mymodule"
    error:::mymodule             # Convert warnings to errors in "mymodule"

### Filtro de advertencia predeterminado

Por defecto, Python instala varios filtros de advertencia, que pueden ser anulados por la opción de línea de comandos `-W`, la variable de entorno `PYTHONWARNINGS` y llamadas a `filterwarnings()`.

En versiones regulares, el filtro de advertencia por defecto tiene las siguientes entradas (en orden de precedencia):

    default::DeprecationWarning:__main__
    ignore::DeprecationWarning
    ignore::PendingDeprecationWarning
    ignore::ImportWarning
    ignore::ResourceWarning

En una compilación de depuración, la lista de filtros de advertencia predeterminados está vacía.

Distinto en la versión 3.2: `DeprecationWarning` es ahora ignorado por defecto además de `PendingDeprecationWarning`.

Distinto en la versión 3.7: `DeprecationWarning` se muestra de nuevo por defecto cuando se activa directamente por código en `__main__`.

Distinto en la versión 3.7: `BytesWarning` ya no aparece en la lista de filtros por defecto y en su lugar se configura a través de `sys.warnoptions` cuando `-b` se especifica dos veces.

### Anulando el filtro por defecto

Los desarrolladores de aplicaciones escritas en Python pueden desear ocultar todas las advertencias de nivel de Python a sus usuarios por defecto, y sólo mostrarlas cuando se realizan pruebas o se trabaja de otra manera en la aplicación. El atributo `sys.warnoptions` utilizado para pasar las configuraciones de los filtros al intérprete puede utilizarse como marcador para indicar si las advertencias deben ser desactivadas o no:

    import sys

    if not sys.warnoptions:
        import warnings
        warnings.simplefilter("ignore")

Se aconseja a los desarrolladores de pruebas de código Python que se aseguren de que todas las advertencias se muestren por defecto para el código que se está probando, usando un código como:

    import sys

    if not sys.warnoptions:
        import os, warnings
        warnings.simplefilter("default") # Change the filter in this process
        os.environ["PYTHONWARNINGS"] = "default" # Also affect subprocesses

Por último, se aconseja a los desarrolladores de shells interactivos que ejecuten el código de usuario en un espacio de nombres distinto de `__main__` que se aseguren de que los mensajes `DeprecationWarning` se hagan visibles por defecto, utilizando un código como el siguiente (donde `user_ns` es el módulo utilizado para ejecutar el código introducido interactivamente):

    import warnings
    warnings.filterwarnings("default", category=DeprecationWarning,
                                       module=user_ns.get("__name__"))

## Eliminación temporal de las advertencias

Si está utilizando un código que sabe que va a provocar una advertencia, como una función obsoleta, pero no quiere ver la advertencia (incluso cuando las advertencias se han configurado explícitamente a través de la línea de comandos), entonces es posible suprimir la advertencia utilizando el gestor de contexto `catch_warnings`:

    import warnings

    def fxn():
        warnings.warn("deprecated", DeprecationWarning)

    with warnings.catch_warnings():
        warnings.simplefilter("ignore")
        fxn()

Mientras que dentro del gestor de contexto todas las advertencias serán simplemente ignoradas. Esto le permite utilizar el código conocido como obsoleto sin tener que ver la advertencia, mientras que no suprime la advertencia para otro código que podría no ser consciente de su uso de código obsoleto. Nota: esto sólo puede garantizarse en una aplicación de un solo hilo. Si dos o más hilos utilizan el gestor de contexto `catch_warnings` al mismo tiempo, el comportamiento es indefinido.

## Advertencias de prueba

Para probar las advertencias planteadas por el código, use el administrador de contexto `catch_warnings`. Con él puedes mutar temporalmente el filtro de advertencias para facilitar tus pruebas. Por ejemplo, haz lo siguiente para capturar todas las advertencias levantadas para comprobar:

    import warnings

    def fxn():
        warnings.warn("deprecated", DeprecationWarning)

    with warnings.catch_warnings(record=True) as w:
        # Cause all warnings to always be triggered.
        warnings.simplefilter("always")
        # Trigger a warning.
        fxn()
        # Verify some things
        assert len(w) == 1
        assert issubclass(w[-1].category, DeprecationWarning)
        assert "deprecated" in str(w[-1].message)

También se puede hacer que todas las advertencias sean excepciones usando `error` en lugar de `always`. Una cosa que hay que tener en cuenta es que si una advertencia ya se ha planteado debido a una regla de `once` o `default`, entonces no importa qué filtros estén establecidos, la advertencia no se verá de nuevo a menos que el registro de advertencias relacionadas con la advertencia se haya borrado.

Una vez que se cierra el gestor de contexto, el filtro de advertencias se restablece al estado en que se encontraba al entrar en el contexto. Esto evita que las pruebas cambien el filtro de advertencias de forma inesperada entre una prueba y otra, y que se produzcan resultados indeterminados en las pruebas. La función `showwarning()` del módulo también se restaura a su valor original. Nota: esto sólo puede garantizarse en una aplicación de un solo hilo. Si dos o más hilos utilizan el gestor de contexto `catch_warnings` al mismo tiempo, el comportamiento es indefinido.

Cuando se prueban múltiples operaciones que plantean el mismo tipo de advertencia, es importante probarlas de manera que se confirme que cada operación plantea una nueva advertencia (por ejemplo, establecer advertencias que se planteen como excepciones y comprobar que las operaciones plantean excepciones, comprobar que la longitud de la lista de advertencias siga aumentando después de cada operación, o bien suprimir las entradas anteriores de la lista de advertencias antes de cada nueva operación).

## Actualización del código para las nuevas versiones de las dependencias

Las categorías de advertencia que interesan principalmente a los desarrolladores de Python (más que a los usuarios finales de aplicaciones escritas en Python) se ignoran por defecto.

En particular, esta lista de «ignorados por defecto» incluye `DeprecationWarning` (para cada módulo excepto `__main__`), lo que significa que los desarrolladores deben asegurarse de probar su código con advertencias típicamente ignoradas hechas visibles para recibir notificaciones oportunas de futuros cambios del API a última hora(ya sea en la biblioteca estándar o en paquetes de terceros).

En el caso ideal, el código tendrá un conjunto de pruebas adecuado, y el corredor de pruebas se encargará de habilitar implícitamente todas las advertencias cuando se ejecuten las pruebas (el corredor de pruebas proporcionado por el módulo `unittest` hace esto).

En casos menos ideales, las aplicaciones pueden ser revisadas por el uso de interfaces desaprobadas pasando `-Wd` al intérprete de Python (esto es la abreviatura de `-W default`) o ajustando `PYTHONWARNINGS=default` en el entorno. Esto permite el manejo por defecto de todas las advertencias, incluyendo aquellas que son ignoradas por defecto. Para cambiar la acción que se lleva a cabo para las advertencias encontradas puede cambiar el argumento que se pasa a `-W` (por ejemplo `-W error`). Consulte el indicador `-W` para obtener más detalles sobre lo que es posible.

## Funciones disponibles

warnings.warn(message, category=None, stacklevel=1, source=None, *, skip_file_prefixes=())

  Emite una advertencia, o tal vez la ignorar o lanza una excepción. El argumento category, si se da, debe ser un warning category class; por defecto es `UserWarning`. Alternativamente, message puede ser una instancia `Warning`, en cuyo caso category será ignorada y se usará `message.__class__`. En este caso, el texto del mensaje será `str(message)`. Esta función hace una excepción si la advertencia particular emitida es convertida en un error por el warnings filter. El argumento stacklevel puede ser usado por funciones de envoltura escritas en Python, como esta:

      def deprecated_api(message):
          warnings.warn(message, DeprecationWarning, stacklevel=2)

  Esto hace que la advertencia se refiera al invocador de `deprecated_api`, en lugar de a la fuente de `deprecated_api` en sí (ya que esta última perdería el propósito del mensaje de advertencia).

  El parámetro de palabra clave skip_file_prefixes se puede utilizar para indicar qué frames de pila se ignoran al contar los niveles de pila. Esto puede ser útil cuando desea que la advertencia aparezca siempre en los sitios de llamadas fuera de un paquete cuando una constante stacklevel no se ajusta a todas las rutas de llamadas o en otro caso es difícil de mantener. Si se proporciona, debe ser una tupla de cadenas de caracteres. Cuando se proporcionan prefijos, el stacklevel se sobreescribe implícitamente con `max(2, stacklevel)`. Para hacer que se atribuya una advertencia al invocador desde afuera del paquete actual, puede escribir:

      # example/lower.py
      _warn_skips = (os.path.dirname(__file__),)

      def one_way(r_luxury_yacht=None, t_wobbler_mangrove=None):
          if r_luxury_yacht:
              warnings.warn("Please migrate to t_wobbler_mangrove=.",
                            skip_file_prefixes=_warn_skips)

      # example/higher.py
      from . import lower

      def another_way(**kw):
          lower.one_way(**kw)

  Esto hace que la advertencia se refiera a ambos lugares de llamada `example.lower.one_way()` y `package.higher.another_way()` únicamente desde el código de llamada que se encuentra fuera del paquete `example`.

  source, si se suministra, es el objeto destruido que emitió un `ResourceWarning`.

  Distinto en la versión 3.6: Añadido parámetro source.

  Distinto en la versión 3.12: Añadido skip_file_prefixes.

warnings.warn_explicit(message, category, filename, lineno, module=None, registry=None, module_globals=None, source=None)

  Se trata de una interfaz de bajo nivel para la funcionalidad de `warn()`, pasando explícitamente el mensaje, la categoría, el nombre de archivo y el número de línea, y opcionalmente el nombre del módulo y el registro (que debería ser el diccionario `__warningregistry__` del módulo). El nombre del módulo por defecto es el nombre de archivo con .py desmembrado; si no se pasa el registro, la advertencia nunca se suprime. message debe ser una cadena y category una subclase de `Warning` o message puede ser una instancia `Warning`, en cuyo caso category será ignorada.

  module_globals, si se suministra, debe ser el espacio de nombres global en uso por el código para el que se emite la advertencia. (Este argumento se utiliza para apoyar la visualización de la fuente de los módulos que se encuentran en los archivos zip o en otras fuentes de importación que no son del sistema de archivos).

  source, si se suministra, es el objeto destruido que emitió un `ResourceWarning`.

  Distinto en la versión 3.6: Añade el parámetro source.

warnings.showwarning(message, category, filename, lineno, file=None, line=None)

  Escriba una advertencia en un archivo. La implementación por defecto llama `formatwarning(message, category, filename, lineno, line)` y escribe la cadena resultante a file, que por defecto es `sys.stderr`. Puede reemplazar esta función con cualquier interlocutor asignando a `warnings.showwarning`. line es una línea de código fuente que se incluirá en el mensaje de advertencia; si no se proporciona line, `showwarning()` intentará leer la línea especificada por nombre de archivo y lineno.

warnings.formatwarning(message, category, filename, lineno, line=None)

  Formatea una advertencia de la manera estándar. Esto retorna una cadena que puede contener nuevas líneas incrustadas y termina en una nueva línea. line es una línea de código fuente a incluir en el mensaje de advertencia; si line no se suministra, `formatwarning()` intentará leer la línea especificada por el nombre de fichero filename y lineno.

warnings.filterwarnings(action, message='', category=Warning, module='', lineno=0, append=False)

  Inserta una entrada en la lista de warnings filter specifications. La entrada se inserta por defecto en el frente; si append es verdadero, se inserta al final. Esto comprueba los tipos de los argumentos, compila las expresiones regulares message y module, y las inserta como una tupla en la lista de filtros de aviso. Las entradas más cercanas al principio de la lista anulan las entradas posteriores de la lista, si ambas coinciden con una advertencia en particular. Los argumentos omitidos predeterminan un valor que coincide con todo.

warnings.simplefilter(action, category=Warning, lineno=0, append=False)

  Inserte una simple entrada en la lista de warnings filter specifications. El significado de los parámetros de la función es el mismo que el de `filterwarnings()`, pero no se necesitan expresiones regulares ya que el filtro insertado siempre coincide con cualquier mensaje de cualquier módulo siempre que la categoría y el número de línea coincidan.

warnings.resetwarnings()

  Reajusta el filtro de advertencias. Esto descarta el efecto de todas las llamadas previas a `filterwarnings()`, incluyendo la de las opciones de línea de comandos de `-W` y las llamadas a `simplefilter()`.

## Gestores de contexto disponibles

class warnings.catch_warnings(*, record=False, module=None, action=None, category=Warning, lineno=0, append=False)

  Un gestor de contexto que copia y, al salir, restaura el filtro de advertencias y la función `showwarning()`. Si el argumento record es `False` (por defecto) el gestor de contextos retorna `None` al entrar. Si record es `True`, se retorna una lista que se va poblando progresivamente de objetos como se ve por una función personalizada de `showwarning()` (que también suprime la salida a `sys.stdout`). Cada objeto de la lista tiene atributos con los mismos nombres que los argumentos de `showwarning()`.

  El argumento module toma un módulo que será usado en lugar del módulo retornado cuando se importa `warnings` cuyo filtro será protegido. Este argumento existe principalmente para probar el propio módulo `warnings`.

  Si el argumento action es diferente a `None`, los demás argumentos serán enviados a la función `simplefilter()` como si fueran invocados inmediatamente al entrar al contexto.

  See El filtro de advertencias for the meaning of the category and lineno parameters.

  Nota

  El gestor `catch_warnings` funciona reemplazando y luego restaurando la función `showwarning()` del módulo y la lista interna de especificaciones del filtro. Esto significa que el gestor de contexto está modificando el estado global y por lo tanto no es seguro para los hilos.

  Distinto en la versión 3.11: Agrega los parámetros action, category, lineno y append.