log
===

.. py:module:: log

.. autoapi-nested-parse::

   Extensions to the standard Python logging system.



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


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


Module Contents
---------------

.. py:data:: T

.. py:data:: LEVELS

.. py:data:: NO_DEBUG_LOGGING_MODULES
   :value: ['boto3', 'botocore', 'requests', 'urllib3']


.. py:data:: default_output_stream
   :type:  TextIO | IO[str]

.. py:data:: pretty_cli

.. py:data:: console_logs
   :type:  str | None
   :value: None


.. py:class:: JSONFormatter(date_fmt: str | None = None, context: 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
      :value: ['asctime', 'levelname', 'name', 'message', 'module', 'exc_text']



   .. py:attribute:: _extra_attr
      :type:  list[str]
      :value: ['anod_uui']



   .. py:attribute:: context
      :value: None



   .. py:method:: format(record: logging.LogRecord) -> str

      convert record into JSON.



.. py:class:: E3LoggerAdapter(logger, extra=None, merge_extra=False)

   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



   .. 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 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



   .. 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



   .. 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



   .. 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



   .. 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



   .. 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



.. py:function:: progress_bar(it: collections.abc.Iterator[T] | collections.abc.Sequence[T], **kwargs: Any) -> collections.abc.Iterator[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


   .. py:method:: emit(record: logging.LogRecord) -> None

      Emit a record.

      If a formatter is specified, it is used to format the record.
      The record is then written to the stream with a trailing newline.  If
      exception information is present, it is formatted using
      traceback.print_exception and appended to the stream.  If the stream
      has an 'encoding' attribute, it is used to determine how to do the
      output to the stream.



.. 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.


.. 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

