bluemira.base.logs
==================

.. py:module:: bluemira.base.logs

.. autoapi-nested-parse::

   Logging system setup and control.



Classes
-------

.. autoapisummary::

   bluemira.base.logs.LogLevel
   bluemira.base.logs.LoggerAdapter
   bluemira.base.logs.BluemiraRichHandler
   bluemira.base.logs.BluemiraRichFileHandler
   bluemira.base.logs.ConsoleFlush
   bluemira.base.logs.LoggingContext


Functions
---------

.. autoapisummary::

   bluemira.base.logs.stop_progress
   bluemira.base.logs.logger_setup
   bluemira.base.logs.set_log_level
   bluemira.base.logs.get_log_level
   bluemira.base.logs._modify_handler


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

.. py:class:: LogLevel(_, colour: str | None = '')

   Bases: :py:obj:`enum.Enum`

   .. autoapi-inheritance-diagram:: bluemira.base.logs.LogLevel
      :parts: 1
      :private-bases:


   Linking level names and corresponding numbers.


   .. py:attribute:: CRITICAL
      :value: (5, 'darkred')



   .. py:attribute:: ERROR
      :value: (4, 'red')



   .. py:attribute:: WARNING
      :value: (3, 'orange')



   .. py:attribute:: INFO
      :value: (2, 'blue')



   .. py:attribute:: DEBUG
      :value: (1, 'green')



   .. py:attribute:: NOTSET
      :value: (0, None)



   .. py:attribute:: colour
      :value: ''



   .. py:method:: _missing_(value: int | str) -> LogLevel
      :classmethod:



   .. py:method:: value_for_logging() -> int

      Return builtin logging level value



.. py:function:: stop_progress(logger: LoggerAdapter, stop: threading.Event, wait: float = 4)

   Kill progress bar as soon as possible

   :param logger: Logger instance
   :param stop: Kill signal event
   :param wait: time (s) to wait before killing progress bar


.. py:class:: LoggerAdapter(name, level=NOTSET)

   Bases: :py:obj:`logging.Logger`

   .. autoapi-inheritance-diagram:: bluemira.base.logs.LoggerAdapter
      :parts: 1
      :private-bases:


   Adapt the base logging class for our uses


   .. py:attribute:: progress
      :type:  rich.progress.Progress | None
      :value: None



   .. py:attribute:: _stop_p
      :type:  threading.Event


   .. py:method:: _base(func: collections.abc.Callable[[str], None], msg: str, *args, flush: bool = False, progress_timeout: float = 4, _clean: bool = False, **kwargs)


   .. py:method:: makeRecord(*args, **kwargs) -> logging.LogRecord

      Overridden makeRecord to pass variables to handler



   .. py:method:: debug(msg: str, *args, flush: bool = False, **kwargs)

      Debug



   .. py:method:: info(msg: str, *args, flush: bool = False, **kwargs)

      Info



   .. py:method:: warning(msg: str, *args, flush: bool = False, **kwargs)

      Warning



   .. py:method:: error(msg: str, *args, flush: bool = False, **kwargs)

      Error



   .. py:method:: critical(msg: str, *args, flush: bool = False, **kwargs)

      Critical



   .. py:method:: clean(msg: str, loglevel: str | LogLevel = LogLevel.INFO, *args, flush: bool = False, **kwargs)

      Unmodified logging



.. py:class:: BluemiraRichHandler(level: Union[int, str] = logging.NOTSET, console: Optional[rich.console.Console] = None, *, show_time: bool = True, omit_repeated_times: bool = True, show_level: bool = True, show_path: bool = True, enable_link_path: bool = True, highlighter: Optional[rich.highlighter.Highlighter] = None, markup: bool = False, rich_tracebacks: bool = False, tracebacks_width: Optional[int] = None, tracebacks_code_width: Optional[int] = 88, tracebacks_extra_lines: int = 3, tracebacks_theme: Optional[str] = None, tracebacks_word_wrap: bool = True, tracebacks_show_locals: bool = False, tracebacks_suppress: Iterable[Union[str, types.ModuleType]] = (), tracebacks_max_frames: int = 100, locals_max_length: int = 10, locals_max_string: int = 80, log_time_format: Union[str, rich._log_render.FormatTimeCallable] = '[%x %X]', keywords: Optional[List[str]] = None)

   Bases: :py:obj:`rich.logging.RichHandler`

   .. autoapi-inheritance-diagram:: bluemira.base.logs.BluemiraRichHandler
      :parts: 1
      :private-bases:


   Rich handler modified for different output types


   .. py:method:: render(*, record: logging.LogRecord, traceback: rich.traceback.Traceback | None, message_renderable: rich.console.ConsoleRenderable) -> rich.console.ConsoleRenderable

      Rich handler rendering in a panel under as requested

      :returns: The text to be rendered by the logger



.. py:class:: BluemiraRichFileHandler(level: Union[int, str] = logging.NOTSET, console: Optional[rich.console.Console] = None, *, show_time: bool = True, omit_repeated_times: bool = True, show_level: bool = True, show_path: bool = True, enable_link_path: bool = True, highlighter: Optional[rich.highlighter.Highlighter] = None, markup: bool = False, rich_tracebacks: bool = False, tracebacks_width: Optional[int] = None, tracebacks_code_width: Optional[int] = 88, tracebacks_extra_lines: int = 3, tracebacks_theme: Optional[str] = None, tracebacks_word_wrap: bool = True, tracebacks_show_locals: bool = False, tracebacks_suppress: Iterable[Union[str, types.ModuleType]] = (), tracebacks_max_frames: int = 100, locals_max_length: int = 10, locals_max_string: int = 80, log_time_format: Union[str, rich._log_render.FormatTimeCallable] = '[%x %X]', keywords: Optional[List[str]] = None)

   Bases: :py:obj:`BluemiraRichHandler`

   .. autoapi-inheritance-diagram:: bluemira.base.logs.BluemiraRichFileHandler
      :parts: 1
      :private-bases:


   Allow some filtering on file log handlers


.. py:class:: ConsoleFlush(*, color_system: Optional[Literal['auto', 'standard', '256', 'truecolor', 'windows']] = 'auto', force_terminal: Optional[bool] = None, force_jupyter: Optional[bool] = None, force_interactive: Optional[bool] = None, soft_wrap: bool = False, theme: Optional[rich.theme.Theme] = None, stderr: bool = False, file: Optional[IO[str]] = None, quiet: bool = False, width: Optional[int] = None, height: Optional[int] = None, style: Optional[rich.style.StyleType] = None, no_color: Optional[bool] = None, tab_size: int = 8, record: bool = False, markup: bool = True, emoji: bool = True, emoji_variant: Optional[rich.emoji.EmojiVariant] = None, highlight: bool = True, log_time: bool = True, log_path: bool = True, log_time_format: Union[str, rich._log_render.FormatTimeCallable] = '[%X]', highlighter: Optional[HighlighterType] = ReprHighlighter(), legacy_windows: Optional[bool] = None, safe_box: bool = True, get_datetime: Optional[Callable[[], datetime.datetime]] = None, get_time: Optional[Callable[[], float]] = None, _environ: Optional[Mapping[str, str]] = None)

   Bases: :py:obj:`rich.console.Console`

   .. autoapi-inheritance-diagram:: bluemira.base.logs.ConsoleFlush
      :parts: 1
      :private-bases:


   Rich console modified for progress bar use


   .. py:attribute:: _flushing
      :value: False



   .. py:method:: print(*args, **kwargs)

      Console output function customised for progress bar.



.. py:function:: logger_setup(logfilename: str = 'bluemira.log', *, level: str | int = 'INFO') -> logging.Logger

   Create logger with two handlers.

   :param logfilename: Name of file to write logs to, default = bluemira.log
   :param level: The initial logging level to be printed to the console, default = INFO.

   :returns: The logger object.

   .. rubric:: Notes

   set to debug initially.


.. py:function:: set_log_level(verbose: int | str = 1, *, increase: bool = False, logger_names: collections.abc.Iterable[str] = ('bluemira', ))

   Get new log level and check if it is possible.

   :param verbose: Amount the severity level of the logger should be changed by or to
   :param increase: Whether level should be increased by specified amount or changed to it
   :param logger_names: The loggers for which to set the level, default = ("bluemira")


.. py:function:: get_log_level(logger_name: str = 'bluemira', *, as_str: bool = True) -> str | int

   Return the current logging level.

   :param logger_name: The named logger to get the level for.
   :param as_str: If True then return the logging level as a string, else as an int.

   :returns: The logging level.


.. py:function:: _modify_handler(new_level: LogLevel, logger: logging.Logger)

   Change level of the logger from user's input.

   :param new_level: Severity level for handler to be changed to, from set_log_level
   :param logger: Logger to be used


.. py:class:: LoggingContext(level: str | int)

   A context manager for temporarily adjusting the logging level

   :param level: The bluemira logging level to set within the context.


   .. py:attribute:: level


   .. py:attribute:: original_level
      :value: ''



   .. py:method:: __enter__()

      Set the logging level to the new level when we enter the context.



   .. py:method:: __exit__(type, value, traceback)

      Set the logging level to the original level when we exit the context.