unravel.core.utils module#

Utility functions and decorators for handling configurations, processing files and directories, and enhancing command-line scripts with progress bars and detailed function execution info.

Classes:

CustomMofNCompleteColumn: Progress bar column for completed/total items.
CustomTimeElapsedColumn: Progress bar column for elapsed time in green.
CustomTimeRemainingColumn: Progress bar column for remaining time in dark orange.
AverageTimePerIterationColumn: Progress bar column for average time per iteration.

Functions:

load_config: Load settings from a config file.
get_samples: Get a list of sample directories based on provided parameters.
initialize_progress_bar: Initialize a Rich progress bar.
verbose_start_msg: Print the start command and time if verbose mode is enabled.
verbose_end_msg: Print the end time if verbose mode is enabled.
log_command: Decorator to log the command and execution times to a hidden file.
print_func_name_args_times: Decorator to print function execution details.
load_text_from_file: Load text content from a file.
copy_files: Copy specified files from source to target directory.
process_files_with_glob: Process files matching a glob pattern using a processing function.

Usage:

Import the functions and decorators to enhance your scripts.

Examples

>>> # Import the functions and decorators
>>> from unravel.core.utils import load_config, get_samples, initialize_progress_bar, print_func_name_args_times, load_text_from_file, copy_files

>>> # Load the configuration from a file
>>> config = load_config("path/to/config.ini")

>>> # Get a list of sample directories
>>> samples = get_samples(["path/to/dir1", "path/to/dir2"], dir_pattern="sample??", verbose=True)

>>> # Initialize a progress bar
>>> progress, task_id = initialize_progress_bar(len(samples), task_message="[red]Processing samples...")

unravel.core.utils.load_config(config_path)[source]#: Load settings from the config file and return a Config object.

unravel.core.utils.get_samples(dir_list=None, dir_pattern='sample??', verbose=False)[source]#

Finds and returns paths to directories matching a specified pattern within given directories or, if none are provided, the current working directory.

Parameters:

dir_list (list of Path or str, or Path or str, optional) – A list of paths (as Path objects or strings) to sample?? directories or directories that may contain subdirectories matching the dir_pattern.
dir_pattern (str, optional) – A pattern to match directory names, default is “sample??”, where “?” is a wildcard matching a single character. This pattern is used to identify directories of interest.
dir_pattern – A Unix shell-style wildcard pattern used by fnmatch to match directory names. Default is “sample??”, where each “?” matches a single character.
verbose (bool, optional) – If True, prints the found directories, grouped by their parent directories. Default is False.

Returns:

samples – A list of resolved Path objects pointing to directories that match the dir_pattern.

Return type:

list of Path

Notes

If no directories are provided via dir_list, the function searches the current working directory.
If a directory (e.g., the current dir) matches the dir_pattern, it is included in the results and not searched for subdirectories.

Examples

>>> sample_paths = get_samples()  # Search the current working directory for sample?? directories
>>> sample_paths = get_samples([path1, path2], dir_pattern="sample???")  # Search path1 and path2 for sample??? directories

class unravel.core.utils.CustomMofNCompleteColumn(separator='/', table_column=None)[source]#

Bases: MofNCompleteColumn

Parameters:

separator (str)
table_column (Column | None)

render(task)[source]#

Show completed/total.

Return type:: Text

class unravel.core.utils.CustomTimeElapsedColumn(table_column=None)[source]#

Bases: TimeElapsedColumn

Parameters:: table_column (Column | None)

render(task)[source]#

Show time elapsed.

Return type:: Text

class unravel.core.utils.CustomTimeRemainingColumn(compact=False, elapsed_when_finished=False, table_column=None)[source]#

Bases: TimeRemainingColumn

Parameters:

compact (bool)
elapsed_when_finished (bool)
table_column (Column | None)

render(task)[source]#

Show time remaining.

Return type:: Text

class unravel.core.utils.AverageTimePerIterationColumn(table_column=None)[source]#

Bases: ProgressColumn

Parameters:: table_column (Column | None)

render(task)[source]#

Render the average time per iteration.

Parameters:: task – An object representing a task, which should have a speed attribute.
Returns:: A Text object displaying the average time per iteration.
Return type:: Text

unravel.core.utils.initialize_progress_bar(num_of_items_to_iterate, task_message='[red]Processing...')[source]#

unravel.core.utils.verbose_start_msg()[source]#: Print the start command and time if verbose mode is enabled.

unravel.core.utils.verbose_end_msg()[source]#: Print the end time if verbose mode is enabled.

unravel.core.utils.log_command(func)[source]#: A decorator for main() to log the command and execution times to a hidden file (.command_log.txt).

unravel.core.utils.get_dir_name_from_args(args, kwargs)[source]#: This function checks args and kwargs for a file or directory path and returns a string based on the name of the file or directory.

unravel.core.utils.print_func_name_args_times(print_dir=True)[source]#: A decorator that prints the function name, arguments, duration, and memory usage of the function it decorates.

unravel.core.utils.load_text_from_file(file_path)[source]#

unravel.core.utils.copy_files(source_dir, target_dir, filename, sample_path=None, verbose=False)[source]#

Copy the specified slices to the target directory.

Parameters:

source_dir (-) – Path to the source directory containing the .tif files.
target_dir (-) – Path to the target directory where the selected slices will be copied.
filename (-) – Name of the file to copy.
sample_path (-) – Path to the sample directory (provide to prepend to the filename).
verbose (-) – Increase verbosity.

unravel.core.utils.process_files_with_glob(glob_pattern, processing_func, *args, **kwargs)[source]#

Process all files matching a glob pattern using the provided processing function.

Parameters:#

glob_patternstr: The glob pattern to match files.
processing_funcfunction: The function to process each file. Should accept a file path as the first argument.
*args, **kwargs :: Additional arguments and keyword arguments to pass to the processing function.