:py:mod:`log` ============= .. py:module:: log .. autoapi-nested-parse:: Extensions to the standard Python logging system. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: log.JSONFormatter log.E3LoggerAdapter log.TqdmHandler Functions ~~~~~~~~~ .. autoapisummary:: log.progress_bar log.getLogger log.add_log_handlers log.add_logging_argument_group log.activate_with_args log.activate Attributes ~~~~~~~~~~ .. autoapisummary:: log.T log.LEVELS log.NO_DEBUG_LOGGING_MODULES log.default_output_stream log.pretty_cli log.console_logs log.__null_handler_set log.e3_debug_logger log.debug .. py:data:: T .. py:data:: LEVELS .. py:data:: NO_DEBUG_LOGGING_MODULES :value: ['boto3', 'botocore', 'requests', 'requests_cache', 'urllib3'] .. py:data:: default_output_stream :type: TextIO | IO[str] .. py:data:: pretty_cli .. py:data:: console_logs :type: str | None .. py:class:: JSONFormatter(date_fmt: str | None = None, context: collections.abc.Mapping[str, Any] | None = None) Bases: :py:obj:`logging.Formatter` Logging formatter for creating JSON logs. It will print some standard attributes defined in STD_ATTR plus application extra attributes defined in _extra_attr .. py:attribute:: STD_ATTR :type: ClassVar[list[str]] :value: ['asctime', 'levelname', 'name', 'message', 'module', 'exc_text'] .. py:attribute:: _extra_attr :type: ClassVar[list[str]] :value: ['anod_uui'] .. py:method:: format(record: logging.LogRecord) -> str Convert record into JSON. :param record: logging record .. py:class:: E3LoggerAdapter(logger, extra=None) Bases: :py:obj:`logging.LoggerAdapter` LoggerAdapter to add custom keywords. .. py:method:: process(msg: Any, kwargs: Any) -> tuple[Any, Any] Allow to handle extra parameter. It is called by super method log. It is overwritten here because the standard process method will get rid of extra attribute :param msg: log message :param kwargs: keyword arguments .. py:method:: log(level: int, msg: Any, *args: Any, anod_uui: int = 0, **kwargs: Any) -> None Integrate additional keywords using standard interface. :param level: see logging module :param msg: log message :param args: see logging module :param anod_uui: Anod UUI :param kwargs: other parameter supported by std logger._log method .. py:method:: info(msg: Any, *args: Any, anod_uui: int = 0, **kwargs: Any) -> None Wrap standard logger.info method. It allows adding extra keyword parameters :param msg: log message :param args: see logging module :param anod_uui: Anod UUI :param kwargs: other parameters supported by std logger._log method .. py:method:: debug(msg: Any, *args: Any, anod_uui: int = 0, **kwargs: Any) -> None Wrap standard logger.debug method. It allows adding extra keyword parameters :param msg: log message :param args: see logging module :param anod_uui: Anod UUI :param kwargs: other parameters supported by std logger._log method .. py:method:: warning(msg: Any, *args: Any, anod_uui: int = 0, **kwargs: Any) -> None Wrap standard logger.warning method. It allows adding extra keyword parameters :param msg: log message :param args: see logging module :param anod_uui: Anod UUI :param kwargs: other parameters supported by std logger._log method .. py:method:: error(msg: Any, *args: Any, anod_uui: int = 0, **kwargs: Any) -> None Wrap standard logger.error method. It allows adding extra keyword parameters :param msg: log message :param args: see logging module :param anod_uui: Anod UUI :param kwargs: other parameters supported by std logger._log method .. py:method:: critical(msg: Any, *args: Any, anod_uui: int = 0, **kwargs: Any) -> None Wrap of standard logger.critical method. It allows adding extra keyword parameters :param msg: log message :param args: see logging module :param anod_uui: Anod UUI :param kwargs: other parameters supported by std logger._log method .. py:method:: exception(msg: Any, *args: Any, exc_info: logging._ExcInfoType = True, anod_uui: int = 0, **kwargs: Any) -> None Wrap standard logger.exception method. It allows adding extra keyword parameters :param msg: log message :param args: see logging module :param exc_info: exception info (default: True) :param anod_uui: Anod UUI :param kwargs: other parameters supported by std logger._log method .. py:function:: progress_bar(it: collections.abc.Iterator[T] | collections.abc.Sequence[T], **kwargs: Any) -> tqdm.tqdm[T] Create a tqdm progress bar. :param it: an interator :param kwargs: see tqdm documentation :return: a tqdm progress bar iterator .. py:data:: __null_handler_set .. py:class:: TqdmHandler Bases: :py:obj:`logging.StreamHandler` Logging handler when used when progress bars are enabled. .. py:attribute:: color_subst :value: ((), (), (), (), ()) .. py:method:: emit(record: logging.LogRecord) -> None Emit a record with colors. :param record: logging record .. py:function:: getLogger(name: str | None = None, prefix: str = 'e3') -> E3LoggerAdapter Get a logger with a default handler doing nothing. Calling this function instead of logging.getLogger will avoid warnings such as:: 'No handler could be found for logger...' :param name: logger name, if not specified return the root logger :param prefix: application prefix, will be prepended to the name .. py:function:: add_log_handlers(level: int, log_format: str, datefmt: str | None = None, filename: str | None = None, set_default_output: bool = True, json_format: bool = False) -> None Add log handlers using GMT. :param level: set the root logger level to the specified level :param log_format: format stream for the log handler :param datefmt: date/time format for the log handler :param filename: use of a FileHandler, using the specified filename, instead of a StreamHandler. Set default_output_stream to write in this file. :param set_default_output: if True, set default_output_stream to the file handler stream when filename is not None :param json_format: if True, use JSON formatter for log output .. py:function:: add_logging_argument_group(argument_parser: argparse.ArgumentParser, default_level: int = logging.WARNING) -> argparse._ArgumentGroup Add an argument group with logging options to the argument parser. To be used with `e3.log.activate_with_args`. :param argument_parser: the parser in which the group will be created :param default_level: the logging level that will be used by default .. py:function:: activate_with_args(args: argparse.Namespace, default_level: int = logging.WARNING) -> None Activate the e3 log using argument parsed. To be used with `e3.log.add_logging_argument_group`. :param args: the result of parsing arguments :param default_level: the logging level assumed by default .. py:function:: activate(stream_format: str = '%(levelname)-8s %(message)s', file_format: str = '%(asctime)s: %(name)-24s: %(levelname)-8s %(message)s', datefmt: str | None = None, level: int = logging.INFO, filename: str | None = None, e3_debug: bool = False, json_format: bool = False) -> None Activate default E3 logging. This function should be called only once. Subsequent calls will result in a no-op. :param level: set the root logger level to the specified level :param datefmt: date/time format for the log handler :param stream_format: format string for the stream handler :param file_format: format string for the file handler :param filename: redirect logs to a file in addition to the StreamHandler :param e3_debug: activate full debug of the e3 library .. py:data:: e3_debug_logger .. py:data:: debug