"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).


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=None)

   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.

   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*.
