diff --git a/adafruit_logging/__init__.py b/adafruit_logging/__init__.py index 2a7ce59..33f8acf 100644 --- a/adafruit_logging/__init__.py +++ b/adafruit_logging/__init__.py @@ -22,6 +22,30 @@ * Adafruit CircuitPython firmware for the supported boards: https://github.com/adafruit/circuitpython/releases +Attributes +---------- + LEVELS : list + A list of tuples representing the valid logging levels used by + this module. Each tuple contains exactly two elements: one int and one + str. The int in each tuple represents the relative severity of that + level (00 to 50). The str in each tuple is the string representation of + that logging level ("NOTSET" to "CRITICAL"; see below). + NOTSET : int + The NOTSET logging level, which is a dummy logging level that can be + used to indicate that a `Logger` should not print any logging messages, + regardless of how severe those messages might be (including CRITICAL). + DEBUG : int + The DEBUG logging level, which is the lowest (least severe) real level. + INFO : int + The INFO logging level for informative/informational messages. + WARNING : int + The WARNING logging level for warnings that should be addressed/fixed. + ERROR : int + The ERROR logging level for Python exceptions that occur during runtime. + CRITICAL : int + The CRITICAL logging level, which is the highest (most severe) level for + unrecoverable errors that have caused the code to halt and exit. + """ # pylint:disable=redefined-outer-name,consider-using-enumerate,no-self-use # pylint:disable=invalid-name @@ -30,6 +54,24 @@ __version__ = "0.0.0-auto.0" __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_Logger.git" +# pylint:disable=undefined-all-variable +__all__ = [ + "LEVELS", + "NOTSET", + "DEBUG", + "INFO", + "WARNING", + "ERROR", + "CRITICAL", + "level_for", + "LoggingHandler", + "PrintHandler", + "logger_cache", + "null_logger", + "getLogger", + "Logger", + "NullLogger", +] LEVELS = [ @@ -41,14 +83,14 @@ (50, "CRITICAL"), ] -for value, name in LEVELS: - globals()[name] = value +for __value, __name in LEVELS: + globals()[__name] = __value def level_for(value: int) -> str: - """Convert a numberic level to the most appropriate name. + """Convert a numeric level to the most appropriate name. - :param value: a numeric level + :param int value: a numeric level """ for i in range(len(LEVELS)): @@ -62,18 +104,18 @@ def level_for(value: int) -> str: class LoggingHandler: """Abstract logging message handler.""" - def format(self, level: int, msg: str) -> str: + def format(self, log_level: int, message: str) -> str: """Generate a timestamped message. - :param level: the logging level - :param msg: the message to log + :param int log_level: the logging level + :param str message: the message to log """ - return "{0}: {1} - {2}".format(time.monotonic(), level_for(level), msg) + return "{0}: {1} - {2}".format(time.monotonic(), level_for(log_level), message) - def emit(self, level: int, msg: str): + def emit(self, log_level: int, message: str): """Send a message where it should go. - Place holder for subclass implementations. + Placeholder for subclass implementations. """ raise NotImplementedError() @@ -81,14 +123,14 @@ def emit(self, level: int, msg: str): class PrintHandler(LoggingHandler): """Send logging messages to the console by using print.""" - def emit(self, level: int, msg: str): + def emit(self, log_level: int, message: str): """Send a message to the console. - :param level: the logging level - :param msg: the message to log + :param int log_level: the logging level + :param str message: the message to log """ - print(self.format(level, msg)) + print(self.format(log_level, message)) # The level module-global variables get created when loaded @@ -98,22 +140,22 @@ def emit(self, level: int, msg: str): null_logger = None # pylint:disable=global-statement -def getLogger(name: str) -> "Logger": +def getLogger(logger_name: str) -> "Logger": """Create or retrieve a logger by name. - :param name: the name of the logger to create/retrieve None will cause the - NullLogger instance to be returned. + :param str logger_name: The name of the `Logger` to create/retrieve. `None` + will cause the `NullLogger` instance to be returned. """ global null_logger - if not name or name == "": + if not logger_name or logger_name == "": if not null_logger: null_logger = NullLogger() return null_logger - if name not in logger_cache: - logger_cache[name] = Logger() - return logger_cache[name] + if logger_name not in logger_cache: + logger_cache[logger_name] = Logger() + return logger_cache[logger_name] # pylint:enable=global-statement @@ -127,13 +169,13 @@ def __init__(self): self._level = NOTSET self._handler = PrintHandler() - def setLevel(self, value: int): - """Set the logging cuttoff level. + def setLevel(self, log_level: int): + """Set the logging cutoff level. - :param value: the lowest level to output + :param int log_level: the lowest level to output """ - self._level = value + self._level = log_level def getEffectiveLevel(self) -> int: """Get the effective level for this logger. @@ -143,32 +185,34 @@ def getEffectiveLevel(self) -> int: """ return self._level - def addHandler(self, hldr: LoggingHandler): + def addHandler(self, handler: LoggingHandler): """Sets the handler of this logger to the specified handler. *NOTE* this is slightly different from the CPython equivalent which adds - the handler rather than replaceing it. + the handler rather than replacing it. - :param hldr: the handler + :param LoggingHandler handler: the handler """ - self._handler = hldr + self._handler = handler - def log(self, level: int, format_string: str, *args): + def log(self, log_level: int, format_string: str, *args): """Log a message. - :param level: the priority level at which to log - :param format_string: the core message string with embedded formatting directives - :param args: arguments to ``format_string.format()``, can be empty + :param int log_level: the priority level at which to log + :param str format_string: the core message string with embedded + formatting directives + :param args: arguments to ``format_string.format()``; can be empty """ - if level >= self._level: - self._handler.emit(level, format_string % args) + if log_level >= self._level: + self._handler.emit(log_level, format_string % args) def debug(self, format_string: str, *args): """Log a debug message. - :param format_string: the core message string with embedded formatting directives - :param args: arguments to ``format_string.format()``, can be empty + :param str format_string: the core message string with embedded + formatting directives + :param args: arguments to ``format_string.format()``; can be empty """ self.log(DEBUG, format_string, *args) @@ -176,8 +220,9 @@ def debug(self, format_string: str, *args): def info(self, format_string: str, *args): """Log a info message. - :param format_string: the core message string with embedded formatting directives - :param args: arguments to ``format_string.format()``, can be empty + :param str format_string: the core message string with embedded + formatting directives + :param args: arguments to ``format_string.format()``; can be empty """ self.log(INFO, format_string, *args) @@ -185,8 +230,9 @@ def info(self, format_string: str, *args): def warning(self, format_string: str, *args): """Log a warning message. - :param format_string: the core message string with embedded formatting directives - :param args: arguments to ``format_string.format()``, can be empty + :param str format_string: the core message string with embedded + formatting directives + :param args: arguments to ``format_string.format()``; can be empty """ self.log(WARNING, format_string, *args) @@ -194,8 +240,9 @@ def warning(self, format_string: str, *args): def error(self, format_string: str, *args): """Log a error message. - :param format_string: the core message string with embedded formatting directives - :param args: arguments to ``format_string.format()``, can be empty + :param str format_string: the core message string with embedded + formatting directives + :param args: arguments to ``format_string.format()``; can be empty """ self.log(ERROR, format_string, *args) @@ -203,8 +250,9 @@ def error(self, format_string: str, *args): def critical(self, format_string: str, *args): """Log a critical message. - :param format_string: the core message string with embedded formatting directives - :param args: arguments to ``format_string.format()``, can be empty + :param str format_string: the core message string with embedded + formatting directives + :param args: arguments to ``format_string.format()``; can be empty """ self.log(CRITICAL, format_string, *args) @@ -212,22 +260,23 @@ def critical(self, format_string: str, *args): class NullLogger: """Provide an empty logger. - This can be used in place of a real logger to more efficiently disable logging.""" + This can be used in place of a real logger to more efficiently disable + logging.""" def __init__(self): """Dummy implementation.""" - def setLevel(self, value: int): + def setLevel(self, log_level: int): """Dummy implementation.""" def getEffectiveLevel(self) -> int: """Dummy implementation.""" return NOTSET - def addHandler(self, hldr: LoggingHandler): + def addHandler(self, handler: LoggingHandler): """Dummy implementation.""" - def log(self, level: int, format_string: str, *args): + def log(self, log_level: int, format_string: str, *args): """Dummy implementation.""" def debug(self, format_string: str, *args): diff --git a/adafruit_logging/extensions.py b/adafruit_logging/extensions.py index ee31804..0ea110a 100644 --- a/adafruit_logging/extensions.py +++ b/adafruit_logging/extensions.py @@ -34,18 +34,18 @@ def close(self): """Closes the file""" self.logfile.close() - def format(self, level: int, msg: str): + def format(self, log_level: int, message: str): """Generate a string to log :param level: The level of the message :param msg: The message to format """ - return super().format(level, msg) + "\r\n" + return super().format(log_level, message) + "\r\n" - def emit(self, level: int, msg: str): + def emit(self, log_level: int, message: str): """Generate the message and write it to the UART. :param level: The level of the message :param msg: The message to log """ - self.logfile.write(self.format(level, msg)) + self.logfile.write(self.format(log_level, message))