bundle.core.logger ================== .. py:module:: bundle.core.logger Attributes ---------- .. autoapisummary:: bundle.core.logger.BASE_STACKLEVEL bundle.core.logger.DEFAULT_LOGGING bundle.core.logger.logger Classes ------- .. autoapisummary:: bundle.core.logger.Emoji bundle.core.logger.Level bundle.core.logger.BundleLogger bundle.core.logger.JsonFormatter Functions --------- .. autoapisummary:: bundle.core.logger.get_logger bundle.core.logger.setup_file_handler bundle.core.logger.setup_console_handler bundle.core.logger.setup_root_logger Module Contents --------------- .. py:data:: BASE_STACKLEVEL :value: 1 .. py:class:: Emoji Emojis for logging status representation. .. py:attribute:: start :value: '🔵' .. py:attribute:: end :value: '🟣' .. py:attribute:: success :value: '🟢' .. py:attribute:: failed :value: '🔴' .. py:attribute:: warning :value: '🟡' .. py:method:: status(val: bool) -> str :classmethod: Return the success or failed emoji based on a boolean value. .. py:class:: Level Bases: :py:obj:`enum.IntEnum` Enum where members are also (and must be) ints .. py:attribute:: NOTSET :value: 0 .. py:attribute:: EXPECTED_EXCEPTION :value: 3 .. py:attribute:: TESTING :value: 5 .. py:attribute:: VERBOSE :value: 7 .. py:attribute:: DEBUG :value: 10 .. py:attribute:: INFO :value: 20 .. py:attribute:: WARNING :value: 30 .. py:attribute:: ERROR :value: 40 .. py:attribute:: CRITICAL :value: 50 .. py:attribute:: FATAL .. py:data:: DEFAULT_LOGGING :value: 10 .. py:class:: BundleLogger(name, level=NOTSET) Bases: :py:obj:`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. .. py:attribute:: Emoji Custom Logger with a verbose method. .. py:method:: get_callable_name(callable_obj) :staticmethod: Helper function to retrieve the name of a callable for logging purposes. :param callable_obj: The callable object whose name is to be retrieved. :returns: The qualified name of the callable. :rtype: str .. py:method:: verbose(msg: str, *args, stacklevel=BASE_STACKLEVEL, **kwargs) -> None .. py:method:: testing(msg: str, *args, stacklevel=BASE_STACKLEVEL, **kwargs) -> None .. py:method:: pretty_repr(obj: Any) -> None .. py:method:: 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. :param func: The callable that was executed. :param args: Positional arguments passed to the callable. :param kwargs: Keyword arguments passed to the callable. :param result: The result returned by the callable. :param stacklevel: The stack level for the log record. :param level: The logging level to use (default: DEBUG). .. py:method:: 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. :param func: The callable that raised the exception. :param args: Positional arguments passed to the callable. :param kwargs: Keyword arguments passed to the callable. :param exception: The exception that was raised. :param stacklevel: The stack level for the log record. :param level: The logging level to use (default: ERROR). .. py:method:: 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. :param func: The callable that was cancelled. :param args: Positional arguments passed to the callable. :param kwargs: Keyword arguments passed to the callable. :param exception: The async cancel exception. :param stacklevel: The stack level for the log record. :param level: The logging level to use (default: WARNING). .. py:function:: get_logger(name: str) -> BundleLogger Retrieve a logger with the correct type hint. .. py:class:: JsonFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None) Bases: :py:obj:`logging.Formatter` Formatter for JSON-style log output. .. py:method:: 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. .. py:function:: setup_file_handler(log_path: pathlib.Path, to_json: bool) -> logging.FileHandler Set up a file handler for logging. .. py:function:: 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. .. py:function:: 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. :param name: Logger name. Defaults to "bundle". :type name: str | None :param level: Logging level. Defaults to DEFAULT_LOGGING. :type level: int :param log_path: Path for log files. If None, skips file logging. :type log_path: Path | None :param colored_output: Enable colored console output. Defaults to True. :type colored_output: bool :param to_json: Format log files as JSON if True. Defaults to False. :type to_json: bool :returns: Configured logger instance. :rtype: logging.Logger .. py:data:: logger