xai4tsc.logging_config
======================

.. py:module:: xai4tsc.logging_config

.. autoapi-nested-parse::

   Public logging controls for the xai4tsc package.

   By default the package is silent: :mod:`xai4tsc` installs only a
   :class:`logging.NullHandler` on the ``'xai4tsc'`` logger. Call
   :func:`enable_logging` to attach a console handler (and, optionally, a file
   handler) and :func:`disable_logging` to return the package to its silent
   default. Additional file sinks can be attached and detached independently with
   :func:`add_file_log` / :func:`remove_file_log` (or the :func:`file_log` context
   manager) without disturbing the console or other file sinks. All functions
   target the ``'xai4tsc'`` named logger only and never touch the root logger, so
   enabling logging here does not affect the host application's own logging
   configuration.



Functions
---------

.. autoapisummary::

   xai4tsc.logging_config.enable_logging
   xai4tsc.logging_config.add_file_log
   xai4tsc.logging_config.remove_file_log
   xai4tsc.logging_config.file_log
   xai4tsc.logging_config.disable_logging


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

.. py:function:: enable_logging(destination: str | pathlib.Path | None = None, level: int | str = 'INFO') -> logging.Logger

   Enable logging for the xai4tsc package.

   Ensures a single console (stdout) handler on the ``'xai4tsc'`` logger and,
   when ``destination`` is given, also attaches a file handler via
   :func:`add_file_log`. This is additive and idempotent: calling it repeatedly
   updates the existing console handler in place rather than duplicating it, and
   it never removes file sinks attached by :func:`add_file_log`. Only the
   ``'xai4tsc'`` logger is configured; the root logger is left untouched.

   :param destination: If provided, also log to a file. When it names an existing directory or
                       has no file suffix, logs are written to ``<destination>/xai4tsc.log``;
                       otherwise it is used as the log file path directly. Missing parent
                       directories are created. If ``None`` (default), only console logging is
                       enabled.
   :type destination: str or pathlib.Path, optional
   :param level: Logging level as a name (e.g. ``"DEBUG"``) or a numeric value (e.g.
                 :data:`logging.WARNING`). At ``DEBUG`` the logger name is included in
                 the log format.
   :type level: int or str, default="INFO"

   :returns: The configured ``'xai4tsc'`` logger.
   :rtype: logging.Logger


.. py:function:: add_file_log(destination: str | pathlib.Path, level: int | str | None = None) -> logging.Handler

   Attach a file handler to the xai4tsc logger without disturbing others.

   Unlike :func:`enable_logging`, this is purely additive: multiple file sinks
   can coexist (e.g. a global log plus one per model). Attaching the same
   resolved path twice returns the existing handler rather than duplicating it.

   :param destination: Where to write. When it names an existing directory or has no file
                       suffix, logs go to ``<destination>/xai4tsc.log``; otherwise it is used
                       as the log file path directly. Missing parent directories are created.
   :type destination: str or pathlib.Path
   :param level: Logging level for this sink as a name or numeric value. If ``None``
                 (default), the logger's current level is inherited.
   :type level: int or str, optional

   :returns: The attached (or already-existing) file handler. Pass it to
             :func:`remove_file_log` to detach this sink.
   :rtype: logging.Handler


.. py:function:: remove_file_log(target: logging.Handler | str | pathlib.Path | None) -> None

   Detach a file sink previously attached by :func:`add_file_log`.

   :param target: The handler returned by :func:`add_file_log`, or the path it was
                  attached for (resolved the same directory-aware way). ``None`` is a
                  no-op, so a ``finally`` block can call this unconditionally.
   :type target: logging.Handler or str or pathlib.Path or None


.. py:function:: file_log(destination: str | pathlib.Path, level: int | str | None = None) -> collections.abc.Iterator[logging.Handler]

   Context manager that attaches a file sink for the duration of a block.

   Attaches via :func:`add_file_log` on entry and detaches via
   :func:`remove_file_log` on exit, even if the block raises.

   :param destination: File or directory to log to (see :func:`add_file_log`).
   :type destination: str or pathlib.Path
   :param level: Level for this sink; inherits the logger's level when ``None``.
   :type level: int or str, optional

   :Yields: *logging.Handler* -- The attached file handler.


.. py:function:: disable_logging() -> None

   Disable xai4tsc logging and restore the silent-by-default state.

   Removes every handler installed by :func:`enable_logging` and
   :func:`add_file_log` (leaving the library's :class:`logging.NullHandler` in
   place) and resets the ``'xai4tsc'`` logger's level and propagation to their
   defaults.