Logging configuration for the AITune package.

Module Contents

Classes

Name	Description
`_TeeFile`	File-like object that writes to multiple destinations (tee functionality).

Functions

Name	Description
`_redirect_logging_handlers`	Redirect all logging StreamHandlers to target file.
`_redirect_low_level_output`	Redirect low-level file descriptors to target and return cleanup info.
`_restore_logging_handlers`	Restore logging StreamHandlers to their original streams.
`_restore_low_level_output`	Restore low-level file descriptors.
`_try_redirect_handler`	Try to redirect a single handler to target file.
`control_output`	Silences or redirects stdout, stderr, and logs within the invoked context.
`libraries_logging`	Suppress logging for all packages except the specified ones.
`log`	Log a message with indentation.
`log_exception_details`	Log detailed exception information in a standardized format.
`log_to_file`	Append a message and optional exception details to a log file.
`set_module_level`	Set logging level for a specific module.
`setup_logging`	Configure logging for the AITune package.
`write_exception_log`	Write an exception traceback to a cache directory.

API

class aitune.utils.logging._TeeFile(
    files = ()
)

File-like object that writes to multiple destinations (tee functionality).

aitune.utils.logging._TeeFile.fileno() -> int

Return file descriptor of first file.

aitune.utils.logging._TeeFile.flush() -> None

Flush all file objects.

aitune.utils.logging._TeeFile.isatty() -> bool

Return whether this is an interactive stream.

aitune.utils.logging._TeeFile.readable() -> bool

Return whether object supports reading.

aitune.utils.logging._TeeFile.writable() -> bool

Return whether object supports writing.

aitune.utils.logging._TeeFile.write(
    data: str
) -> int

Write data to all file objects.

aitune.utils.logging._redirect_logging_handlers(
    target_file,
    original_stdout,
    original_stderr
)

Redirect all logging StreamHandlers to target file.

Parameters:

target_file

File object to redirect to

original_stdout

Original sys.stdout reference

original_stderr

Original sys.stderr reference

Returns:

List of (handler, original_stream) tuples for restoration

aitune.utils.logging._redirect_low_level_output(
    target_fd
)

Redirect low-level file descriptors to target and return cleanup info.

aitune.utils.logging._restore_logging_handlers(
    saved_handler_streams
)

Restore logging StreamHandlers to their original streams.

Parameters:

saved_handler_streams

List of (handler, original_stream) tuples

aitune.utils.logging._restore_low_level_output(
    save_fds
)

Restore low-level file descriptors.

aitune.utils.logging._try_redirect_handler(
    handler,
    target_file,
    original_stdout,
    original_stderr
)

Try to redirect a single handler to target file.

Parameters:

handler

The logging handler to redirect

target_file

File object to redirect to

original_stdout

Original sys.stdout reference

original_stderr

Original sys.stderr reference

Returns:

Tuple of (handler, original_stream) if successful, None otherwise

aitune.utils.logging.control_output(
    log_file: str | pathlib.Path | None = None
)

Silences or redirects stdout, stderr, and logs within the invoked context.

Parameters:

log_file

str | Path | NoneDefaults to None

Optional file path to log output to

aitune.utils.logging.libraries_logging(
    disabled: bool,
    exceptions: list[str] | None = None
)

Suppress logging for all packages except the specified ones.

Parameters:

disabled

bool

If False, libraries logs will be suppressed.

exceptions

list[str] | NoneDefaults to None

List of package names to exclude from suppression

aitune.utils.logging.log(
    msg: str,
    args = (),
    sink: collections.abc.Callable = logging.info,
    depth: int = 0
)

Log a message with indentation.

Parameters:

depth

intDefaults to 0

Number of levels to indent

*args

Defaults to ()

Arguments to pass to the sink function

msg

str

Message to log

sink

CallableDefaults to logging.info

Function to use for logging

aitune.utils.logging.log_exception_details(
    logger: logging.Logger,
    exception: Exception,
    message: str,
    level: int = logging.ERROR,
    reraise: bool = False,
    reraise_as: Exception | None = None
)

Log detailed exception information in a standardized format.

This function provides consistent and comprehensive exception logging across the AITune codebase, including exception type, message, and full traceback information.

Parameters:

logger

logging.Logger

Logger instance to use for logging

exception

Exception

The exception that was caught

message

str

Custom error message describing the context

level

intDefaults to logging.ERROR

Logging level to use (default: ERROR)

reraise

boolDefaults to False

Whether to re-raise the exception after logging (default: False)

reraise_as

Exception | NoneDefaults to None

Optional exception to raise instead of the original (default: None)

Raises:

Exception: Re-raises the original exception or the specified reraise_as exception

aitune.utils.logging.log_to_file(
    log_file: str | pathlib.Path | None,
    message: str,
    exception: Exception | None = None
) -> None

Append a message and optional exception details to a log file.

aitune.utils.logging.set_module_level(
    module_name: str,
    level: int | str
)

Set logging level for a specific module.

Parameters:

module_name

str

Name of the module (e.g., ‘aitune.torch.backend’)

level

int | str

Logging level (e.g., ‘DEBUG’, ‘INFO’, ‘WARNING’)

aitune.utils.logging.setup_logging(
    level: int | str | None = None,
    format_string: str = '%(asctime)s - %(name)s - %...,
    log_file: str | pathlib.Path | None = None,
    capture_warnings: bool = True
)

Configure logging for the AITune package.

This function sets up the root logger with appropriate handlers and formatting. Call this at the start of your application to ensure all logs are displayed.

Example usage: from aitune import setup_logging, set_module_level import logging

Configure with a log file and custom format

setup_logging( level=logging.DEBUG, format_string=”%(asctime)s - %(name)s - %(filename)s:%(lineno)d - %(levelname)s - %(message)s”, log_file=“aitune.log”, )

Set specific modules to different levels

set_module_level(“aitune.torch.backend.tensorrt”, logging.DEBUG) # Verbose TensorRT logs

Parameters:

level

int | str | NoneDefaults to None

Logging level (default: None, uses current root logger level)

format_string

strDefaults to '%(asctime)s - %(name)s - %(filename)s:%(lineno)d - %(levelname)s - %(message)s'

Format for log messages

log_file

str | Path | NoneDefaults to None

Optional file path to write logs to

capture_warnings

boolDefaults to True

If True, warnings will be captured and displayed

aitune.utils.logging.write_exception_log(
    cache_dir: pathlib.Path,
    exception: BaseException
) -> pathlib.Path

Write an exception traceback to a cache directory.