From d5f1ffa0d897957e4ee3dfbb51da323143f8596f Mon Sep 17 00:00:00 2001 From: Sylvain Gugger <35901082+sgugger@users.noreply.github.com> Date: Tue, 1 Sep 2020 03:16:34 -0400 Subject: [PATCH] Logging doc (#6852) * Add logging doc * Foamtting * Update docs/source/main_classes/logging.rst * Update src/transformers/utils/logging.py Co-authored-by: Lysandre Debut --- docs/source/index.rst | 1 + docs/source/main_classes/logging.rst | 44 +++++++++++++++++++++++++++ src/transformers/utils/logging.py | 45 ++++++++++++++++++++-------- 3 files changed, 77 insertions(+), 13 deletions(-) create mode 100644 docs/source/main_classes/logging.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 9d0ea1fc5..33b549d17 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -185,6 +185,7 @@ conversion utilities for the following models: main_classes/trainer main_classes/optimizer_schedules main_classes/processors + main_classes/logging model_doc/auto model_doc/encoderdecoder model_doc/bert diff --git a/docs/source/main_classes/logging.rst b/docs/source/main_classes/logging.rst new file mode 100644 index 000000000..fba1edb08 --- /dev/null +++ b/docs/source/main_classes/logging.rst @@ -0,0 +1,44 @@ +Logging +------- + +🤗 Transformers has a centralized logging system, so that you can setup the verbosity of the library easily. To +change the level of verbosity, just use one of the direct setters. For instance, here is how to change the verbosity to +the INFO level. + +.. code-block:: python + + import transformers + transformers.logging.set_verbosity_info() + +All the methods of this logging module are documented below, the main ones are +:func:`transformers.logging.get_verbosity` to get the current level of verbosity in the logger and +:func:`transformers.logging.set_verbosity` to set the verbosity to the level of your choice. In order (from the least +verbose to the most verbose), those levels (with their corresponding int values in parenthesis) are: + +- :obj:`transformers.logging.CRITICAL` or :obj:`transformers.logging.FATAL` (int value, 50): only report the most + critical errors. +- :obj:`transformers.logging.ERROR` (int value, 40): only report errors. +- :obj:`transformers.logging.WARNING` or :obj:`transformers.logging.WARN` (int value, 30): only reports error and + warnings. This the default level used by the library. +- :obj:`transformers.logging.INFO` (int value, 20): reports error, warnings and basic information. +- :obj:`transformers.logging.DEBUG` (int value, 10): report all information. + +Base setters +~~~~~~~~~~~~ + +.. autofunction:: transformers.logging.set_verbosity_error + +.. autofunction:: transformers.logging.set_verbosity_warning + +.. autofunction:: transformers.logging.set_verbosity_info + +.. autofunction:: transformers.logging.set_verbosity_debug + +Other functions +~~~~~~~~~~~~~~~ + +.. autofunction:: transformers.logging.get_verbosity + +.. autofunction:: transformers.logging.set_verbosity + +.. autofunction:: transformers.logging.get_logger diff --git a/src/transformers/utils/logging.py b/src/transformers/utils/logging.py index d592d43ea..1987718dd 100644 --- a/src/transformers/utils/logging.py +++ b/src/transformers/utils/logging.py @@ -73,8 +73,10 @@ def _reset_library_root_logger() -> None: def get_logger(name: Optional[str] = None) -> logging.Logger: - """Return a logger with the specified name. - This function is not supposed to be directly accessed by library users. + """ + Return a logger with the specified name. + + This function is not supposed to be directly accessed unless you are writing a custom transformers module. """ if name is None: @@ -85,16 +87,21 @@ def get_logger(name: Optional[str] = None) -> logging.Logger: def get_verbosity() -> int: - """Return the current level for the HuggingFace Transformers's root logger. + """ + Return the current level for the 🤗 Transformers's root logger as an int. + Returns: - Logging level, e.g., ``transformers.logging.DEBUG`` and ``transformers.logging.INFO``. + :obj:`int`: The logging level. + .. note:: - HuggingFace Transformers has following logging levels: - - ``transformers.logging.CRITICAL``, ``transformers.logging.FATAL`` - - ``transformers.logging.ERROR`` - - ``transformers.logging.WARNING``, ``transformers.logging.WARN`` - - ``transformers.logging.INFO`` - - ``transformers.logging.DEBUG`` + + 🤗 Transformers has following logging levels: + + - 50: ``transformers.logging.CRITICAL`` or ``transformers.logging.FATAL`` + - 40: ``transformers.logging.ERROR`` + - 30: ``transformers.logging.WARNING`` or ``transformers.logging.WARN`` + - 20: ``transformers.logging.INFO`` + - 10: ``transformers.logging.DEBUG`` """ _configure_library_root_logger() @@ -102,10 +109,18 @@ def get_verbosity() -> int: def set_verbosity(verbosity: int) -> None: - """Set the level for the HuggingFace Transformers's root logger. + """ + Set the vebosity level for the 🤗 Transformers's root logger. + Args: - verbosity: - Logging level, e.g., ``transformers.logging.DEBUG`` and ``transformers.logging.INFO``. + verbosity (:obj:`int`): + Logging level, e.g., one of: + + - ``transformers.logging.CRITICAL`` or ``transformers.logging.FATAL`` + - ``transformers.logging.ERROR`` + - ``transformers.logging.WARNING`` or ``transformers.logging.WARN`` + - ``transformers.logging.INFO`` + - ``transformers.logging.DEBUG`` """ _configure_library_root_logger() @@ -113,18 +128,22 @@ def set_verbosity(verbosity: int) -> None: def set_verbosity_info(): + """Set the verbosity to the :obj:`INFO` level.""" return set_verbosity(INFO) def set_verbosity_warning(): + """Set the verbosity to the :obj:`WARNING` level.""" return set_verbosity(WARNING) def set_verbosity_debug(): + """Set the verbosity to the :obj:`DEBUG` level.""" return set_verbosity(DEBUG) def set_verbosity_error(): + """Set the verbosity to the :obj:`ERROR` level.""" return set_verbosity(ERROR)