Utilities Module

The utils module contains general utilities and helper functions.

Logger

Logging configuration for RegressionLab.

This module provides centralized logging configuration and utilities. It supports both file and console logging with customizable log levels.

utils.logger.setup_logging(log_file=None, level=None, console=None, log_format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', date_format='%Y-%m-%d %H:%M:%S')

Configure application-wide logging.

This function sets up logging to both file and console (optional). If no parameters are provided, it uses environment variables or defaults.

Parameters:

• log_file – Path to log file. If None, uses LOG_FILE env var or default

• level – Logging level. If None, uses LOG_LEVEL env var or INFO

• console – Enable console logging. If None, uses LOG_CONSOLE env var or True

• log_format – Format string for log messages

• date_format – Format string for timestamps

Examples

>>> setup_logging()  # Use defaults and env vars
>>> setup_logging(log_file='my_app.log', level=logging.DEBUG)

utils.logger.get_logger(name)

Get a logger instance for a specific module.

Parameters:

name – Name of the logger (typically __name__ of the module)

Returns:

Logger instance

Examples

>>> logger = get_logger(__name__)
>>> logger.info("Processing data...")
>>> logger.error("Failed to load file", exc_info=True)

utils.logger.log_exception(logger, exception, context=None)

Log an exception with context.

Parameters:

• logger – Logger instance to use.

• exception – Exception that occurred.

• context – Optional context description.

Examples

>>> try:
...     risky_operation()
... except Exception as e:
...     log_exception(logger, e, "Failed to load data")

Exceptions

Custom exceptions for the RegressionLab application.

This module defines specific exception types for different error scenarios, providing better error handling and debugging capabilities.

exception utils.exceptions.RegressionLabError

Bases: Exception

Base exception class for all RegressionLab-related errors.

exception utils.exceptions.DataLoadError

Bases: RegressionLabError

Exception raised when data loading fails.

exception utils.exceptions.DataValidationError

Bases: RegressionLabError

Exception raised when data validation fails.

exception utils.exceptions.FileNotFoundError

Bases: DataLoadError

Exception raised when a requested file or directory is not found.

Note: This is a RegressionLab-specific exception (subclass of DataLoadError). It is distinct from builtins.FileNotFoundError but serves the same semantic purpose.

exception utils.exceptions.InvalidFileTypeError

Bases: DataLoadError

Exception raised when file type is not supported.

exception utils.exceptions.FittingError

Bases: RegressionLabError

Exception raised when curve fitting fails.

exception utils.exceptions.EquationError

Bases: RegressionLabError

Exception raised when equation evaluation fails.

exception utils.exceptions.ValidationError

Bases: RegressionLabError

Exception raised when input validation fails.

Validators

Data validation utilities for the RegressionLab application.

This module provides functions to validate data integrity, file paths, and parameter values before processing.

utils.validators.validate_file_path(file_path)

Validate that a file path exists and is accessible.

Parameters:

file_path – Path to the file

Raises:

• FileNotFoundError – If file does not exist

• ValidationError – If path is not a file

utils.validators.validate_file_type(file_type, allowed_types=None)

Validate that a file type is supported.

Parameters:

• file_type – File extension (e.g., ‘csv’, ‘xlsx’).

• allowed_types – List of allowed file types. If None, uses the central list from config.DATA_FILE_TYPES.

Raises:

InvalidFileTypeError – If file type is not supported.

utils.validators.validate_dataframe(data, min_rows=2)

Validate that a DataFrame is suitable for fitting.

Parameters:

• data – DataFrame to validate

• min_rows – Minimum number of rows required

Raises:

DataValidationError – If DataFrame is invalid

utils.validators.validate_fitting_data(data, x_name, y_name)

Comprehensive validation for fitting data.

Validates:

• DataFrame is not empty

• Required columns exist

• Data is numeric

• Uncertainty columns exist and are valid

Parameters:

• data – DataFrame or dict with data to fit (dict is converted to DataFrame).

• x_name – Name of the independent variable column

• y_name – Name of the dependent variable column

Raises:

DataValidationError – If any validation fails

utils.validators.validate_parameter_names(param_names)

Validate parameter names for custom equations.

Parameters:

param_names – List of parameter names

Raises:

ValidationError – If parameter names are invalid

utils.validators.parse_optional_float(s)

Parse a string to float; empty or invalid input returns None.

Useful for optional numeric fields in dialogs (e.g. initial guess, bounds).

Parameters:

s – String to parse (e.g. from an Entry widget).

Returns:

The parsed float, or None if empty or invalid.

utils.validators.validate_data_format(data)

Comprehensive validation of data file format.

This function validates: - Column names are valid and not duplicated - All columns contain numeric data - No completely empty rows - Minimum requirements (rows and columns)

Parameters:

data – DataFrame to validate

Raises:

DataValidationError – If data format is invalid

Update Checker

Update checker for RegressionLab.

Checks weekly if a newer version is available in the repository. If so, shows a dialog (when enabled via env) and can perform git pull –ff-only without overwriting user data (input/, output/, .env, etc.).

utils.update_checker.should_run_check()

Return True if we should run the update check (once per week).

Returns:

True if enough time has passed since last check, or no previous check.

utils.update_checker.record_check_done()

Record that an update check was performed (touch the file).

utils.update_checker.is_update_available(current_version)

Check if a newer version is available.

Parameters:

current_version – Current application version.

Returns:

The latest version string if newer, else None.

utils.update_checker.perform_git_pull()

Perform git pull –ff-only in the project root.

Before pulling, this function stashes any local changes in input/ and output/ directories to prevent them from being overwritten. After the pull completes, the stashed changes are restored. Files in .env and other .gitignore entries are automatically protected by git.

Returns:

Tuple of (success, message). Message is user-friendly.