quirtylog.core

core.py

This module contains utility functions for logging and file management.

Note

The module includes functions for logging configuration, exception handling, variable name retrieval, path construction, path validation, and clearing old log files.

Ensure to review the individual docstrings for each function for detailed information and usage examples.

Functions

check_path(var[, name])

Validate and convert the input value to a Path object.

clear_old_logs([log_path, k_min])

Delete old log files in the specified folder.

configure_logger([log_path, config_file])

Configure an existing log

create_logger([log_path, config_file, name, ...])

Create a custom logger object with optional configuration parameters.

display_arguments(logger[, level])

Create a decorator for showing information about function signature with a specified logger.

measure_time(logger[, level])

Create a decorator for computing execution time and managing exceptions with a specified logger.

path_constructor(loader, node[, log_path])

YAML constructor function for expanding and replacing paths.

retrieve_name(var)

Retrieve the name of a variable as a string.
quirtylog.core.configure_logger(log_path=None, config_file='default')

Configure an existing log

Parameters:

  • log_path (str | Path | None) – The folder path for storing log files. Defaults to logs/.

  • config_file (str | Path | None) – The configuration file path. Defaults to default. If config_file is provided, the logger is configured using the YAML configuration file; otherwise, a basic configuration is applied.

Example:

import logging

my_logger = logging.getLogger(name='my-logger')

configure_logger(
    log_path='/path/to/logs',
    config_file='/path/to/config.yaml'
)
quirtylog.core.create_logger(log_path=None, config_file='default', name=None, db=None, remove_old_log=True, k_min=1)

Create a custom logger object with optional configuration parameters.

Parameters:

  • log_path (str | Path | None) – The folder path for storing log files. Defaults to logs/.

  • config_file (str | Path | None) – The configuration file path. Defaults to default. If config_file is provided, the logger is configured using the YAML configuration file; otherwise, a basic configuration is applied.

  • name (str | None) – The logger name. If None, it is automatically determined based on the calling module and function.

  • db (str | Path | None) – The name of the SQLite database. If provided, a SQLiteHandler will be added to the logger.

  • remove_old_log (bool) – A flag indicating whether to remove old log files from the specified log path.

  • k_min (int | str) – The minimum number of log files to keep in the history (default: 1). If k_min is a string, it will be converted to an integer.

Return type:

Logger

Returns:

The custom logger object.

Raises:

TypeError – If name is not a string.

Example:

path = '/path/to/logs'
config = 'logging_config.yml'
name = 'my_logger'
db = 'log.db'
custom_logger = create_logging(log_path=path, config_file=config, name=name, db=db)
custom_logger.info('Custom logger initialized successfully.')
quirtylog.core.measure_time(logger, level='info')

Create a decorator for computing execution time and managing exceptions with a specified logger.

This decorator wraps the provided function measuring time, logging any exceptions that occur during its execution.

Parameters:

  • logger (Logger) – The logging object to be used for logging exceptions.

  • level (str) – The logging level for info messages (default: ‘info’). Possible values: {‘info’, ‘debug’, ‘warning’, ‘error’}.

Returns:

The decorator function.

Usage:

@measure_time(logger=my_logger, level='error')
def my_function():
    # Function implementation

Note

  • The decorator logs the total execution time of the wrapped function and any exceptions that occur.

  • Exceptions are logged with their class name, error message, and stack trace.

  • The decorator re-raises the exception after logging.

Example:

@measure_time(logger=my_logger, level='error')
def divide(a, b):
    return a / b

result = divide(10, 0)  # Logs the exception and raises it
quirtylog.core.display_arguments(logger, level='info')

Create a decorator for showing information about function signature with a specified logger.

This decorator wraps the provided function measuring time, logging arguments.

Parameters:

  • logger (Logger) – The logging object to be used for logging exceptions.

  • level (str) – The logging level for info messages (default: ‘info’). Possible values: {‘info’, ‘debug’, ‘warning’, ‘error’}.

Returns:

The decorator function.

Usage:

@display_arguments(logger=my_logger, level='error')
def my_function():
    # Function implementation

Example:

@display_arguments(logger=my_logger, level='error')
def my_sum(a, b):
    return a + b

result = my_sum(10, b=0)  # Logs my_sum(a=10, b=0)
quirtylog.core.clear_old_logs(log_path=None, k_min=1)

Delete old log files in the specified folder.

This function removes log files with filenames in the format “<name>.log.<digit>”, keeping a minimum number of log files specified by the parameter k_min.

Parameters:

  • log_path (str | Path | None) – The folder path where log files are stored (default: ‘logs’).

  • k_min (str | int) – The minimum number of log files to keep in the history (default: 1). If k_min is a string, it will be converted to an integer.

Note

  • The function utilizes the check_path function to validate and convert the log_path parameter.

  • Log files with filenames in the format “<name>.log.<digit>” are considered for deletion.

  • The parameter k_min determines the minimum number of log files to retain; older files are deleted.

  • If the log folder does not exist, no files are removed.

Example:

# Remove log files in the '/path/to/logs' folder, keeping at least 2 files in the history
clear_old_logs(log_path='/path/to/logs', k_min=2)