logger

tit.logger

Logging configuration for TI-Toolbox.

setup_logging

setup_logging(level: str = 'INFO') -> None

Configure the tit logger hierarchy.

Sets the log level but adds NO handlers — file handlers are attached later via add_file_handler() and GUI handlers via Qt signal bridges.

Parameters:

Name	Type	Description	Default
level	str	Log level string (DEBUG, INFO, WARNING, ERROR, CRITICAL). Defaults to INFO.	'INFO'

Source code in tit/logger.py

def setup_logging(level: str = "INFO") -> None:
    """Configure the ``tit`` logger hierarchy.

    Sets the log level but adds NO handlers — file handlers are attached
    later via ``add_file_handler()`` and GUI handlers via Qt signal bridges.

    Args:
        level: Log level string (DEBUG, INFO, WARNING, ERROR, CRITICAL).
               Defaults to INFO.
    """
    logger = logging.getLogger("tit")
    logger.handlers.clear()
    logger.setLevel(getattr(logging, level.upper(), logging.INFO))
    logger.propagate = False  # never bubble to root/terminal

    # Quiet noisy third-party loggers
    for name in ("matplotlib", "matplotlib.font_manager", "PIL"):
        logging.getLogger(name).setLevel(logging.ERROR)

add_file_handler

add_file_handler(log_file: str | Path, level: str = 'DEBUG', logger_name: str = 'tit') -> FileHandler

Attach a file handler to a named logger.

Creates the parent directory if it does not exist. Returns the handler so callers can remove it when the run completes.

Parameters:

Name	Type	Description	Default
log_file	str | Path	Path to the log file (opened in append mode).	required
level	str	Minimum log level for this handler. Defaults to DEBUG so the file captures everything.	'DEBUG'
logger_name	str	Logger to attach to. Defaults to the root "tit" logger.	'tit'

Returns:

Type	Description
FileHandler	The created FileHandler instance.

Source code in tit/logger.py

def add_file_handler(
    log_file: str | Path,
    level: str = "DEBUG",
    logger_name: str = "tit",
) -> logging.FileHandler:
    """Attach a file handler to a named logger.

    Creates the parent directory if it does not exist. Returns the handler
    so callers can remove it when the run completes.

    Args:
        log_file: Path to the log file (opened in append mode).
        level: Minimum log level for this handler. Defaults to DEBUG so the
               file captures everything.
        logger_name: Logger to attach to. Defaults to the root "tit" logger.

    Returns:
        The created FileHandler instance.
    """
    log_file = Path(log_file)
    log_file.parent.mkdir(parents=True, exist_ok=True)
    fh = logging.FileHandler(str(log_file), mode="a")
    fh.setLevel(getattr(logging, level.upper(), logging.DEBUG))
    fh.setFormatter(logging.Formatter(LOG_FORMAT, datefmt=DATE_FORMAT))
    logging.getLogger(logger_name).addHandler(fh)
    return fh

add_stream_handler

add_stream_handler(logger_name: str = 'tit', level: str = 'INFO') -> StreamHandler

Attach a stdout handler to a named logger.

Used by scripts for terminal output and by __main__ entry points so that BaseProcessThread can capture subprocess stdout for the GUI.

Parameters:

Name	Type	Description	Default
logger_name	str	Logger to attach to. Defaults to "tit".	'tit'
level	str	Minimum log level. Defaults to INFO.	'INFO'

Returns:

Type	Description
StreamHandler	The created StreamHandler instance.

Source code in tit/logger.py

def add_stream_handler(
    logger_name: str = "tit",
    level: str = "INFO",
) -> logging.StreamHandler:
    """Attach a stdout handler to a named logger.

    Used by scripts for terminal output and by ``__main__`` entry points
    so that ``BaseProcessThread`` can capture subprocess stdout for the GUI.

    Args:
        logger_name: Logger to attach to. Defaults to ``"tit"``.
        level: Minimum log level. Defaults to INFO.

    Returns:
        The created StreamHandler instance.
    """
    import sys

    handler = logging.StreamHandler(sys.stdout)
    handler.setLevel(getattr(logging, level.upper(), logging.INFO))
    handler.setFormatter(logging.Formatter("%(message)s"))
    logger = logging.getLogger(logger_name)
    logger.addHandler(handler)
    return handler

get_file_only_logger

get_file_only_logger(name: str, log_file: str | Path, level: str = 'DEBUG') -> Logger

Return a logger that writes ONLY to log_file — no console output.

If a logger with name already exists its handlers are replaced so that repeated calls (e.g. across ROIs) always point at the correct file.

Parameters:

Name	Type	Description	Default
name	str	Logger name (should be unique per use-case).	required
log_file	str | Path	Path to the log file.	required
level	str	Minimum log level. Defaults to DEBUG.	'DEBUG'

Returns:

Type	Description
Logger	A configured :class:logging.Logger.

Source code in tit/logger.py

def get_file_only_logger(
    name: str,
    log_file: str | Path,
    level: str = "DEBUG",
) -> logging.Logger:
    """Return a logger that writes ONLY to *log_file* — no console output.

    If a logger with *name* already exists its handlers are replaced so that
    repeated calls (e.g. across ROIs) always point at the correct file.

    Args:
        name: Logger name (should be unique per use-case).
        log_file: Path to the log file.
        level: Minimum log level. Defaults to DEBUG.

    Returns:
        A configured :class:`logging.Logger`.
    """
    logger = logging.getLogger(name)
    logger.handlers.clear()
    logger.setLevel(getattr(logging, level.upper(), logging.DEBUG))
    logger.propagate = False  # never bubble to root/terminal
    add_file_handler(log_file, level=level, logger_name=name)
    return logger