API Reference

adafruit_logging

Logging module for CircuitPython

  • Author(s): Dave Astels, Alec Delaney

Implementation Notes

Hardware:

Software and Dependencies:

Note

This module has a few key differences compared to its CPython counterpart, notably that loggers do not form a hierarchy that allows record propagation. Additionally, the default formatting for handlers is different.

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 can be used to indicate that a Logger should process any logging messages, regardless of how severe those messages are.

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, which is the default 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.

class adafruit_logging.FileHandler(filename: str, mode: str = 'a')

File handler for working with log files off of the microcontroller (like an SD card)

Parameters:

  • filename (str) – The filename of the log file

  • mode (str) – Whether to write (‘w’) or append (‘a’); default is to append

close() → None

Closes the file

emit(record: _LogRecord) → None

Generate the message and write it to the file.

Parameters:

record – The record (message object) to be logged

class adafruit_logging.Handler(level: int = 0)

Base logging message handler.

emit(record: _LogRecord) → None

Send a message where it should go. Placeholder for subclass implementations.

Parameters:

record – The record (message object) to be logged

flush() → None

Placeholder for flush function in subclasses.

format(record: _LogRecord) → str

Generate a timestamped message.

Parameters:

record – The record (message object) to be logged

setFormatter(formatter: Formatter) → None

Set the Formatter to be used by this Handler.

setLevel(level: int) → None

Set the logging level of this handler.

adafruit_logging.LogRecord

An object used to hold the contents of a log record. The following attributes can be retrieved from it:

  • name - The name of the logger

  • levelno - The log level number

  • levelname - The log level name

  • msg - The log message

  • created - When the log record was created

  • args - The additional positional arguments provided

class adafruit_logging.Logger(name: Hashable, level: int = 30)

The actual logger that will provide the logging API.

Parameters:

  • name (Hashable) – The name of the logger, typically assigned by the value from getLogger; this is typically a str

  • level (int) – (optional) The log level, default is WARNING

addHandler(hdlr: Handler) → None

Adds the handler to this logger.

Parameters:

hdlr (Handler) – The handler to add

critical(msg: str, *args) → None

Log a critical message.

Parameters:

  • msg (str) – the core message string with embedded formatting directives

  • args – arguments to msg % args; can be empty

debug(msg: str, *args) → None

Log a debug message.

Parameters:

  • msg (str) – the core message string with embedded formatting directives

  • args – arguments to msg % args; can be empty

error(msg: str, *args) → None

Log a error message.

Parameters:

  • msg (str) – the core message string with embedded formatting directives

  • args – arguments to msg % args; can be empty

exception(err: Exception) → None

Convenience method for logging an ERROR with exception information.

Parameters:

err (Exception) – the exception to be logged

getEffectiveLevel() → int

Get the effective level for this logger.

Returns:

the lowest level to output

handle(record: _LogRecord) → None

Pass the record to all handlers registered with this logger.

Parameters:

record (LogRecord) – log record

hasHandlers() → bool

Whether any handlers have been set for this logger

info(msg: str, *args) → None

Log a info message.

Parameters:

  • msg (str) – the core message string with embedded formatting directives

  • args – arguments to msg % args; can be empty

log(level: int, msg: str, *args) → None

Log a message.

Parameters:

  • level (int) – the priority level at which to log

  • msg (str) – the core message string with embedded formatting directives

  • args – arguments to msg % args; can be empty

name

The name of the logger, this should be unique for proper functionality of getLogger()

removeHandler(hdlr: Handler) → None

Remove handler from this logger.

Parameters:

hdlr (Handler) – The handler to remove

setLevel(log_level: int) → None

Set the logging cutoff level.

Parameters:

log_level (int) – the lowest level to output

warning(msg: str, *args) → None

Log a warning message.

Parameters:

  • msg (str) – the core message string with embedded formatting directives

  • args – arguments to msg % args; can be empty

class adafruit_logging.NullHandler(level: int = 0)

Provide an empty log handler.

This can be used in place of a real log handler to more efficiently disable logging.

emit(record: _LogRecord) → None

Dummy implementation

class adafruit_logging.StreamHandler(stream: WriteableStream | None = None)

Send logging messages to a stream, sys.stderr (typically the serial console) by default.

Parameters:

stream – The stream to log to, default is sys.stderr; can accept any stream that implements stream.write() with string inputs

emit(record: _LogRecord) → None

Send a message to the console.

Parameters:

record – The record (message object) to be logged

flush() → None

flush the stream. You might need to call this if your messages are not appearing in the log file.

format(record: _LogRecord) → str

Generate a string to log

Parameters:

record – The record (message object) to be logged

stream

The stream to log to

adafruit_logging.getLogger(logger_name: Hashable = '') → Logger

Create or retrieve a logger by name; only retrieves loggers made using this function; if a Logger with this name does not exist it is created

Parameters:

logger_name (Hashable) – The name of the Logger to create/retrieve, this is typically a str. If none is provided, the single root logger will be created/retrieved. Note that unlike CPython, a blank string will also access the root logger.