bundle.core.logger

Attributes

BASE_STACKLEVEL
DEFAULT_LOGGING
logger

Classes

Emoji	Emojis for logging status representation.
Level	Enum where members are also (and must be) ints
BundleLogger	Instances of the Logger class represent a single logging channel. A
JsonFormatter	Formatter for JSON-style log output.

Functions

get_logger(→ BundleLogger)	Retrieve a logger with the correct type hint.
setup_file_handler(→ logging.FileHandler)	Set up a file handler for logging.
setup_console_handler(→ logging.Handler)	Set up a console handler for logging.
setup_root_logger(→ BundleLogger)	Configure logging with optional file and console handlers.

Module Contents

bundle.core.logger.BASE_STACKLEVEL = 1

class bundle.core.logger.Emoji

Emojis for logging status representation.

start = '🔵'

end = '🟣'

success = '🟢'

failed = '🔴'

warning = '🟡'

classmethod status(val: bool) → str

Return the success or failed emoji based on a boolean value.

class bundle.core.logger.Level

Bases: enum.IntEnum

Enum where members are also (and must be) ints

NOTSET = 0

EXPECTED_EXCEPTION = 3

TESTING = 5

VERBOSE = 7

DEBUG = 10

INFO = 20

WARNING = 30

ERROR = 40

CRITICAL = 50

FATAL

bundle.core.logger.DEFAULT_LOGGING = 10

class bundle.core.logger.BundleLogger(name, level=NOTSET)

Bases: logging.getLoggerClass()

Instances of the Logger class represent a single logging channel. A “logging channel” indicates an area of an application. Exactly how an “area” is defined is up to the application developer. Since an application can have any number of areas, logging channels are identified by a unique string. Application areas can be nested (e.g. an area of “input processing” might include sub-areas “read CSV files”, “read XLS files” and “read Gnumeric files”). To cater for this natural nesting, channel names are organized into a namespace hierarchy where levels are separated by periods, much like the Java or Python package namespace. So in the instance given above, channel names might be “input” for the upper level, and “input.csv”, “input.xls” and “input.gnu” for the sub-levels. There is no arbitrary limit to the depth of nesting.

Emoji

Custom Logger with a verbose method.

static get_callable_name(callable_obj)

Helper function to retrieve the name of a callable for logging purposes.

Parameters:

callable_obj – The callable object whose name is to be retrieved.

Returns:

The qualified name of the callable.

Return type:

str

verbose(msg: str, *args, stacklevel=BASE_STACKLEVEL, **kwargs) → None

testing(msg: str, *args, stacklevel=BASE_STACKLEVEL, **kwargs) → None

pretty_repr(obj: Any) → None

callable_success(func: collections.abc.Callable[Ellipsis, Any], args: Any, kwargs: collections.abc.Mapping[str, Any], result: Any, stacklevel: int = 2, level: Level = Level.DEBUG) → None

Log a successful call at the given logging level.

Parameters:

• func – The callable that was executed.

• args – Positional arguments passed to the callable.

• kwargs – Keyword arguments passed to the callable.

• result – The result returned by the callable.

• stacklevel – The stack level for the log record.

• level – The logging level to use (default: DEBUG).

callable_exception(func: collections.abc.Callable[Ellipsis, Any], args: Any, kwargs: collections.abc.Mapping[str, Any], exception: BaseException, stacklevel: int = 2, level: Level = Level.ERROR) → None

Log an exception raised during a call at the given logging level.

Parameters:

• func – The callable that raised the exception.

• args – Positional arguments passed to the callable.

• kwargs – Keyword arguments passed to the callable.

• exception – The exception that was raised.

• stacklevel – The stack level for the log record.

• level – The logging level to use (default: ERROR).

callable_cancel(func: collections.abc.Callable[Ellipsis, Any], args: Any, kwargs: collections.abc.Mapping[str, Any], exception: BaseException, stacklevel: int = 2, level: Level = Level.WARNING) → None

Log a cancelled asynchronous call at the given logging level.

Parameters:

• func – The callable that was cancelled.

• args – Positional arguments passed to the callable.

• kwargs – Keyword arguments passed to the callable.

• exception – The async cancel exception.

• stacklevel – The stack level for the log record.

• level – The logging level to use (default: WARNING).

bundle.core.logger.get_logger(name: str) → BundleLogger

Retrieve a logger with the correct type hint.

class bundle.core.logger.JsonFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Bases: logging.Formatter

Formatter for JSON-style log output.

format(record: logging.LogRecord) → str

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

bundle.core.logger.setup_file_handler(log_path: pathlib.Path, to_json: bool) → logging.FileHandler

Set up a file handler for logging.

bundle.core.logger.setup_console_handler(colored_output: bool) → logging.Handler

Set up a console handler for logging.

When colored_output is True, uses RichHandler with a custom Console that employs a custom Theme to style the custom TESTING and VERBOSE levels.

bundle.core.logger.setup_root_logger(name: str | None = None, level: int = DEFAULT_LOGGING, log_path: pathlib.Path | None = None, colored_output: bool = True, to_json: bool = False) → BundleLogger

Configure logging with optional file and console handlers.

Parameters:

• name (str | None) – Logger name. Defaults to “bundle”.

• level (int) – Logging level. Defaults to DEFAULT_LOGGING.

• log_path (Path | None) – Path for log files. If None, skips file logging.

• colored_output (bool) – Enable colored console output. Defaults to True.

• to_json (bool) – Format log files as JSON if True. Defaults to False.

Returns:

Configured logger instance.

Return type:

logging.Logger

bundle.core.logger.logger