adc_toolkit.logger

 10class Logger:
 11    """
 12    Log messages using a logger object.
 13
 14    Parameters
 15    ----------
 16    name: Optional[str]
 17        Name of the logger. Required if using Python logger.
 18        Unused if using Loguru logger.
 19
 20    Examples
 21    ----------
 22    >>> from adc_toolkit.logger import Logger
 23    >>> logger = Logger()
 24    >>> logger.info("This is an info message")
 25    """
 26
 27    _config: LoggerConfig = get_logger_config()
 28
 29    def __init__(self, name: str | None = None) -> None:
 30        """Initialize the logger.
 31
 32        Parameters
 33        ----------
 34        name: Optional[str]
 35            Name of the logger. Required if using Python logger.
 36            Unused if using Loguru logger.
 37        """
 38        self.name = name
 39        self._logger: BaseLogger | None = None
 40
 41    @property
 42    def logger(self) -> BaseLogger:
 43        """Get the logger object.
 44
 45        Returns
 46        ----------
 47        BaseLogger
 48            The logger object used for logging messages.
 49        """
 50        if self._logger is None:
 51            self._logger = find_logger(self.name, self._config)
 52        return self._logger
 53
 54    @classmethod
 55    def set_level(cls, level: str) -> None:
 56        """Set the logging level for the logger.
 57
 58        Parameters
 59        ----------
 60        level: str
 61            The logging level to use for all instances of the logger.
 62            Must be one of 'debug', 'info'.
 63        """
 64        cls._config.set_option("level", LogLevel(level))
 65
 66    @classmethod
 67    def set_options(cls, **kwargs: str | bool) -> None:
 68        """Set options in the logger configuration by supplying kwargs.
 69
 70        Available options:
 71            - format_time: str
 72            How to format time in log messages. See relevant logging library docs for details.
 73
 74            - format_level: str
 75            How to format log level in log messages. See relevant logging library docs for details.
 76
 77            - format_name: str
 78            How to format logger name in log messages. See relevant logging library docs for details.
 79
 80            - format_message: str
 81            How to format log message in log messages. See relevant logging library docs for details.
 82
 83            - use_log_filepath: bool
 84            Whether to log to a file.
 85
 86            - log_filepath: str
 87            The path to the log file, if logging to a file.
 88
 89        Parameters
 90        ----------
 91        name: str
 92            The name of the option to set.
 93        value: Union[str, bool]
 94            The value to set the option to.
 95        """
 96        for name, value in kwargs.items():
 97            cls._config.set_option(name, value)
 98
 99    @classmethod
100    def reset_options(cls) -> None:
101        """Reset the logger configuration to the default values."""
102        cls._config = get_logger_config()
103
104    def debug(self, message: str) -> None:
105        """Log a debug-level message.
106
107        To use only in development or debugging for detailed information on code execution.
108
109        Parameters
110        ----------
111        message: str
112            The message to log.
113
114        Examples
115        ----------
116        >>> logger.debug("Function X called with arguments Y and Z")
117        """
118        self.logger.debug(message)
119
120    def info(self, message: str) -> None:
121        """Log an info-level message.
122
123        General, high-level information on status of operation. Should not be verbose.
124
125        Parameters
126        ----------
127        message: str
128            The message to log.
129
130        Examples
131        ----------
132        >>> logger.info("Reading table X from catalog")
133        """
134        self.logger.info(message)
135
136    def warning(self, message: str) -> None:
137        """Log a warning-level message.
138
139        For potential future problems that are not errors. Use rarely.
140
141        Parameters
142        ----------
143        message: str
144            The message to log.
145
146        Examples
147        ----------
148        >>> logger.warning("Config not found. Using default config.")
149        """
150        self.logger.warning(message)
151
152    def error(self, message: str) -> None:
153        """Log an error-level message.
154
155        For logging exceptions and errors in code execution. Use together with exceptions.
156
157        Parameters
158        ----------
159        message: str
160            The exception to log.
161
162        Examples
163        ----------
164        >>> logger.error("Failed to read table X from catalog")
165        """
166        self.logger.error(message)