plesty.lib.utils.logger
=======================

.. py:module:: plesty.lib.utils.logger

.. autoapi-nested-parse::

   Logging setup utilities for Plesty.



Attributes
----------

.. autoapisummary::

   plesty.lib.utils.logger._FORMAT


Functions
---------

.. autoapisummary::

   plesty.lib.utils.logger._safe_filename_part
   plesty.lib.utils.logger._has_plesty_sink
   plesty.lib.utils.logger.ensure_logging
   plesty.lib.utils.logger.setup_logging


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

.. py:function:: _safe_filename_part(value: str) -> str

   Return a filesystem-safe token for log file names.


.. py:data:: _FORMAT
   :value: '%(asctime)s | %(levelname)s | %(name)s | %(message)s'


.. py:function:: _has_plesty_sink(root: logging.Logger, file: bool) -> bool

   Return True if a plesty-installed console (or file) handler is on *root*.


.. py:function:: ensure_logging(level: str = 'INFO', console_print: bool = True) -> None

   Make INFO-level records visible on the console; idempotent, no file sink.

   The lightweight bootstrap every plesty building block calls on
   construction (:class:`~plesty.lib.device.composite_device.CompositeDevice`,
   :class:`~plesty.lib.experiment.base_experiment.Experiment`): a rig that
   connects before the experiment exists must not be silent while a server
   is unreachable. Sets the root level and adds one console handler unless
   something (a host application, pytest's capture, an earlier call) already
   writes to the console. :func:`setup_logging` adds the per-run file on top.

   :param level: Root logger level name.
   :param console_print: Add the console handler when none exists.


.. py:function:: setup_logging(app_name: str, level: str = 'INFO', console_print: bool = True) -> None

   Configure console logging plus a ``logs/<app_name>_<timestamp>.log`` file.

   Builds on :func:`ensure_logging`; the file sink is added once per process
   — the first *app_name* names the file, later calls only re-assert the level.

   :param app_name: Application name used in the log file name.
   :param level: Root logger level name.
   :param console_print: Also print to the console when no console sink exists.