xai4tsc.logging_config

Public logging controls for the xai4tsc package.

By default the package is silent: xai4tsc installs only a logging.NullHandler on the 'xai4tsc' logger. Call enable_logging() to attach a console handler (and, optionally, a file handler) and disable_logging() to return the package to its silent default. Additional file sinks can be attached and detached independently with add_file_log() / remove_file_log() (or the 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

enable_logging(→ logging.Logger)	Enable logging for the xai4tsc package.
add_file_log(→ logging.Handler)	Attach a file handler to the xai4tsc logger without disturbing others.
remove_file_log(→ None)	Detach a file sink previously attached by add_file_log().
file_log(→ collections.abc.Iterator[logging.Handler])	Context manager that attaches a file sink for the duration of a block.
disable_logging(→ None)	Disable xai4tsc logging and restore the silent-by-default state.

Module Contents

xai4tsc.logging_config.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 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 add_file_log(). Only the 'xai4tsc' logger is configured; the root logger is left untouched.

Parameters:

• destination (str or pathlib.Path, optional) – 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.

• level (int or str, default="INFO") – Logging level as a name (e.g. "DEBUG") or a numeric value (e.g. logging.WARNING). At DEBUG the logger name is included in the log format.

Returns:

The configured 'xai4tsc' logger.

Return type:

logging.Logger

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

Parameters:

• destination (str or pathlib.Path) – 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.

• level (int or str, optional) – Logging level for this sink as a name or numeric value. If None (default), the logger’s current level is inherited.

Returns:

The attached (or already-existing) file handler. Pass it to remove_file_log() to detach this sink.

Return type:

logging.Handler

xai4tsc.logging_config.remove_file_log(target: logging.Handler | str | pathlib.Path | None) → None

Detach a file sink previously attached by add_file_log().

Parameters:

target (logging.Handler or str or pathlib.Path or None) – The handler returned by 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.

xai4tsc.logging_config.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 add_file_log() on entry and detaches via remove_file_log() on exit, even if the block raises.

Parameters:

• destination (str or pathlib.Path) – File or directory to log to (see add_file_log()).

• level (int or str, optional) – Level for this sink; inherits the logger’s level when None.

Yields:

logging.Handler – The attached file handler.

xai4tsc.logging_config.disable_logging() → None

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

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