deepgram.utils.verboselogs

  1# Copyright 2024 Deepgram SDK contributors. All Rights Reserved.
  2# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
  3# SPDX-License-Identifier: MIT
  4
  5"""
  6Custom log levels for Python's :mod:`logging` module.
  7
  8The :mod:`verboselogs` module defines the :data:`NOTICE`, :data:`SPAM`,
  9:data:`SUCCESS` and :data:`VERBOSE` constants, the :class:`VerboseLogger` class
 10and the :func:`add_log_level()` and :func:`install()` functions.
 11
 12At import time :func:`add_log_level()` is used to register the custom log
 13levels :data:`NOTICE`, :data:`SPAM`, :data:`SUCCESS` and :data:`VERBOSE` with
 14Python's :mod:`logging` module.
 15"""
 16
 17import logging
 18
 19__version__ = "1.8"
 20"""Semi-standard module versioning."""
 21
 22NOTICE = 25
 23"""
 24The numeric value of the 'notice' log level (a number).
 25
 26The value of :data:`NOTICE` positions the notice log level between the
 27:data:`~verboselogs.WARNING` and :data:`~verboselogs.INFO` levels.
 28
 29:see also: The :func:`~VerboseLogger.notice()` method of the
 30           :class:`VerboseLogger` class.
 31"""
 32
 33SPAM = 5
 34"""
 35The numeric value of the 'spam' log level (a number).
 36
 37The value of :data:`SPAM` positions the spam log level between the
 38:data:`~verboselogs.DEBUG` and :data:`~verboselogs.NOTSET` levels.
 39
 40:see also: The :func:`~VerboseLogger.spam()` method of the
 41           :class:`VerboseLogger` class.
 42"""
 43
 44SUCCESS = 35
 45"""
 46The numeric value of the 'success' log level (a number).
 47
 48The value of :data:`SUCCESS` positions the success log level between the
 49:data:`~verboselogs.WARNING` and :data:`~verboselogs.ERROR` levels.
 50
 51:see also: The :func:`~VerboseLogger.success()` method of the
 52           :class:`VerboseLogger` class.
 53"""
 54
 55VERBOSE = 15
 56"""
 57The numeric value of the 'verbose' log level (a number).
 58
 59The value of :data:`VERBOSE` positions the verbose log level between the
 60:data:`~verboselogs.INFO` and :data:`~verboselogs.DEBUG` levels.
 61
 62:see also: The :func:`~VerboseLogger.verbose()` method of the
 63           :class:`VerboseLogger` class.
 64"""
 65
 66
 67def install():
 68    """
 69    Make :class:`VerboseLogger` the default logger class.
 70
 71    The :func:`install()` function uses :func:`~logging.setLoggerClass()` to
 72    configure :class:`VerboseLogger` as the default class for all loggers
 73    created by :func:`logging.getLogger()` after :func:`install()` has been
 74    called. Here's how it works:
 75
 76    .. code-block:: python
 77
 78        import logging
 79        import verboselogs
 80
 81        verboselogs.install()
 82        logger = logging.getLogger(__name__) # will be a VerboseLogger instance
 83    """
 84    logging.setLoggerClass(VerboseLogger)
 85
 86
 87def add_log_level(value, name):
 88    """
 89    Add a new log level to the :mod:`logging` module.
 90
 91    :param value: The log level's number (an integer).
 92    :param name: The name for the log level (a string).
 93    """
 94    logging.addLevelName(value, name)
 95    setattr(logging, name, value)
 96
 97
 98WARNING = logging.WARNING
 99ERROR = logging.ERROR
100FATAL = logging.FATAL
101CRITICAL = logging.CRITICAL
102INFO = logging.INFO
103DEBUG = logging.DEBUG
104NOTSET = logging.NOTSET
105
106# Define the NOTICE log level.
107add_log_level(NOTICE, "NOTICE")
108
109# Define the SPAM log level.
110add_log_level(SPAM, "SPAM")
111
112# Define the SUCCESS log level.
113add_log_level(SUCCESS, "SUCCESS")
114
115# Define the VERBOSE log level.
116add_log_level(VERBOSE, "VERBOSE")
117
118
119class VerboseLogger(logging.Logger):
120    """
121    Custom logger class to support the additional logging levels.
122
123    This subclass of :class:`verboselogs.Logger` adds support for the additional
124    logging methods :func:`notice()`, :func:`spam()`, :func:`success()` and
125    :func:`verbose()`.
126
127    You can use :func:`verboselogs.install()` to make :class:`VerboseLogger`
128    the default logger class.
129    """
130
131    def __init__(self, *args, **kw):
132        """
133        Initialize a :class:`VerboseLogger` object.
134
135        :param args: Refer to the superclass (:class:`verboselogs.Logger`).
136        :param kw: Refer to the superclass (:class:`verboselogs.Logger`).
137
138        This method first initializes the superclass and then it sets the root
139        logger as the parent of this logger.
140
141        The function :func:`logging.getLogger()` is normally responsible for
142        defining the hierarchy of logger objects however because verbose
143        loggers can be created by calling the :class:`VerboseLogger`
144        constructor, we're responsible for defining the parent relationship
145        ourselves.
146        """
147        logging.Logger.__init__(self, *args, **kw)
148        self.parent = logging.getLogger()
149
150    def notice(self, msg, *args, **kw):
151        """Log a message with level :data:`NOTICE`. The arguments are interpreted as for :func:`logging.debug()`."""
152        if self.isEnabledFor(NOTICE):
153            self._log(NOTICE, msg, args, **kw)
154
155    def spam(self, msg, *args, **kw):
156        """Log a message with level :data:`SPAM`. The arguments are interpreted as for :func:`logging.debug()`."""
157        if self.isEnabledFor(SPAM):
158            self._log(SPAM, msg, args, **kw)
159
160    def success(self, msg, *args, **kw):
161        """Log a message with level :data:`SUCCESS`. The arguments are interpreted as for :func:`logging.debug()`."""
162        if self.isEnabledFor(SUCCESS):
163            self._log(SUCCESS, msg, args, **kw)
164
165    def verbose(self, msg, *args, **kw):
166        """Log a message with level :data:`VERBOSE`. The arguments are interpreted as for :func:`logging.debug()`."""
167        if self.isEnabledFor(VERBOSE):
168            self._log(VERBOSE, msg, args, **kw)