"""
.. _utils-logging:
Logging Utilities
-----------------
.. versionadded:: 1.0.0
The `loguru` package is used for logging throughout `pyhdtoolkit`, and this module provides utilities to easily set up a logger configuration.
Different pre-defined formats are provided to choose from:
- ``FORMAT1``: will display the full time of the log message, its level, the calling line and the message itself. This is the default format.
- ``FORMAT2``: similar to ``FORMAT1``, but the caller information is displayed at the end of the log line.
- ``SIMPLE_FORMAT``: minimal, displays the local time, the level and the message.
"""
import sys
from typing import Union
from loguru import logger
FORMAT1 = (
"<green>{time:YYYY-MM-DD HH:mm:ss}</green> | "
"<level>{level: <8}</level> | "
"<cyan>{name}</cyan>:<cyan>{line}</cyan> - "
"<level>{message}</level>"
)
FORMAT2 = (
"<green>{time:YYYY-MM-DD HH:mm:ss}</green> | "
"<level>{level: <8}</level> | "
"<level>{message}</level> | "
"<cyan>{name}</cyan>:<cyan>{line}</cyan>"
)
SIMPLE_FORMAT = "<green>{time:HH:mm:ss}</green> | <level>{level: <8}</level> | <level>{message}</level>"
[docs]def config_logger(level: Union[str, int] = "INFO", format: str = FORMAT1, **kwargs) -> None:
"""
.. versionadded:: 0.8.2
Resets the logger object from `loguru`, with `sys.stdout` as a sink and the
provided *format*.
Args:
level (Union[str, int]): the logging level to set. Case-insensitive if a
string is given. Can be any of the
`loguru levels <https://loguru.readthedocs.io/en/stable/api/logger.html#levels>`_
or their integer values equivalents. Defaults to ``INFO``.
format (str): the format to use for the logger to display messages. Defaults
to a pre-defined format in this module.
**kwargs: any keyword argument is transmitted to the `~loguru._logger.Logger.add` call.
Example:
Using the defaults and setting the logging level:
.. code-block:: python
config_logger(level="DEBUG")
Specifying a custom format and setting the logging level:
.. code-block:: python
from pyhdtoolkit.utils.logging import config_logger, SIMPLE_FORMAT
config_logger(level="DEBUG", format=SIMPLE_FORMAT)
"""
logger.remove()
level = level.upper() if isinstance(level, str) else level
logger.add(sys.stdout, level=level, format=format, **kwargs)