From 33fccae724090e65c6cfd784fc0cdedf594545ea Mon Sep 17 00:00:00 2001 From: Lysandre Debut Date: Thu, 12 Oct 2023 10:48:38 +0200 Subject: [PATCH] Warnings controlled by logger level (#26527) * Logger level Co-authored-by: Sahil Bhosale Co-authored-by: Adithya4720 Co-authored-by: Sachin Singh Co-authored-by: Riya Dhanduke <113622644+riiyaa24@users.noreply.github.com> * More comprehensive documentation --------- Co-authored-by: Sahil Bhosale Co-authored-by: Adithya4720 Co-authored-by: Sachin Singh Co-authored-by: Riya Dhanduke <113622644+riiyaa24@users.noreply.github.com> --- docs/source/en/main_classes/logging.md | 17 +++++++++++++++++ src/transformers/utils/logging.py | 26 ++++++++++++++++++++++++++ 2 files changed, 43 insertions(+) diff --git a/docs/source/en/main_classes/logging.md b/docs/source/en/main_classes/logging.md index d117281f650f82..6a77001608c914 100644 --- a/docs/source/en/main_classes/logging.md +++ b/docs/source/en/main_classes/logging.md @@ -71,6 +71,23 @@ verbose to the most verbose), those levels (with their corresponding int values By default, `tqdm` progress bars will be displayed during model download. [`logging.disable_progress_bar`] and [`logging.enable_progress_bar`] can be used to suppress or unsuppress this behavior. +## `logging` vs `warnings` + +Python has two logging systems that are often used in conjunction: `logging`, which is explained above, and `warnings`, +which allows further classification of warnings in specific buckets, e.g., `FutureWarning` for a feature or path +that has already been deprecated and `DeprecationWarning` to indicate an upcoming deprecation. + +We use both in the `transformers` library. We leverage and adapt `logging`'s `captureWarning` method to allow +management of these warning messages by the verbosity setters above. + +What does that mean for developers of the library? We should respect the following heuristic: +- `warnings` should be favored for developers of the library and libraries dependent on `transformers` +- `logging` should be used for end-users of the library using it in every-day projects + +See reference of the `captureWarnings` method below. + +[[autodoc]] logging.captureWarnings + ## Base setters [[autodoc]] logging.set_verbosity_error diff --git a/src/transformers/utils/logging.py b/src/transformers/utils/logging.py index 80d5b71f63e0e6..d732e5bd37a94a 100644 --- a/src/transformers/utils/logging.py +++ b/src/transformers/utils/logging.py @@ -30,6 +30,9 @@ WARN, # NOQA WARNING, # NOQA ) +from logging import ( + captureWarnings as _captureWarnings, +) from typing import Optional import huggingface_hub.utils as hf_hub_utils @@ -121,6 +124,29 @@ def get_log_levels_dict(): return log_levels +def captureWarnings(capture): + """ + Calls the `captureWarnings` method from the logging library to enable management of the warnings emitted by the + `warnings` library. + + Read more about this method here: + https://docs.python.org/3/library/logging.html#integration-with-the-warnings-module + + All warnings will be logged through the `py.warnings` logger. + + Careful: this method also adds a handler to this logger if it does not already have one, and updates the logging + level of that logger to the library's root logger. + """ + logger = get_logger("py.warnings") + + if not logger.handlers: + logger.addHandler(_default_handler) + + logger.setLevel(_get_library_root_logger().level) + + _captureWarnings(capture) + + def get_logger(name: Optional[str] = None) -> logging.Logger: """ Return a logger with the specified name.