tit

tit

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_path_manager

get_path_manager(project_dir: str | None = None) -> PathManager

Return the global PathManager singleton.

Source code in tit/paths.py

def get_path_manager(project_dir: str | None = None) -> PathManager:
    """Return the global PathManager singleton."""
    global _path_manager_instance
    if _path_manager_instance is None:
        _path_manager_instance = PathManager()
    if project_dir is not None:
        _path_manager_instance.project_dir = project_dir
    return _path_manager_instance

init

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

One-call setup for scripts: configure logging and enable terminal output.

Equivalent to::

setup_logging(level)
add_stream_handler("tit", level)

Call this at the top of any script that uses the tit package to get sensible defaults with no extra boilerplate.

Source code in tit/__init__.py

def init(level: str = "INFO") -> None:
    """One-call setup for scripts: configure logging and enable terminal output.

    Equivalent to::

        setup_logging(level)
        add_stream_handler("tit", level)

    Call this at the top of any script that uses the ``tit`` package
    to get sensible defaults with no extra boilerplate.
    """
    setup_logging(level)
    add_stream_handler("tit", level)