niamoto.common.utils package

Submodules

niamoto.common.utils.data_access module

Data access utilities for widgets and exporters.

This module provides generic data access and conversion utilities. Widget-specific transformations have been moved to their respective widget classes.

niamoto.common.utils.data_access.get_nested_data(data, key_path)

Access nested dictionary data using dot notation.

Parameters:

  • data (Dict) – The dictionary to access

  • key_path (str) – Path to the data using dot notation (e.g., ‘meff.value’)

Returns:

The value at the specified path or None if not found

Return type:

Any

niamoto.common.utils.data_access.convert_to_dataframe(data, x_field, y_field, color_field=None, mapping=None)

Convert various data structures to a DataFrame suitable for plotting.

Parameters:

  • data (Any) – Input data (dictionary, list, etc.)

  • x_field (str) – Field name for x-axis values

  • y_field (str) – Field name for y-axis values

  • color_field (str | None) – Optional field name for color/category

  • mapping (Dict[str, str] | None) – Optional mapping of input field names to output column names

Returns:

Pandas DataFrame or None if conversion fails

Return type:

DataFrame | None

niamoto.common.utils.dict_utils module

niamoto.common.utils.dict_utils.get_nested_value(data_dict, key_path, default=None)

Retrieves a value from a nested dictionary using a dot-separated key path.

Parameters:

  • data_dict (Dict[str, Any]) – The dictionary to search within.

  • key_path (str) – The dot-separated path to the desired value (e.g., ‘level1.level2.key’).

  • default (Any | None) – The value to return if the key path is not found or invalid.

Returns:

The found value, or the default value if not found.

Return type:

Any | None

niamoto.common.utils.error_handler module

Error handling utilities for Niamoto.

niamoto.common.utils.error_handler.get_error_details(error)

Extract error details from an exception.

Parameters:

error (Exception) – The exception to process

Returns:

Dictionary containing error details

Return type:

dict

niamoto.common.utils.error_handler.format_error_message(error)

Format an error message for display.

Parameters:

error (Exception) – The exception to format

Returns:

Formatted error message

Return type:

str

niamoto.common.utils.error_handler.handle_error(error, log=True, raise_error=True, console_output=True)

Central error handler for standardized error processing.

Parameters:

  • error (Exception) – The exception to handle

  • log (bool) – Whether to log the error

  • raise_error (bool) – Whether to re-raise the error

  • console_output (bool) – Whether to output to console

Return type:

None

niamoto.common.utils.error_handler.error_handler(*, log=True, raise_error=True, console_output=True)

Decorator for standardized error handling.

Keyword Arguments:

  • log (bool) – Whether to log errors. Defaults to True.

  • raise_error (bool) – Whether to re-raise errors. Defaults to True.

  • console_output (bool) – Whether to output to console. Defaults to True.

Returns:

Decorator function that wraps the target function with error handling.

Return type:

Callable

Parameters:

  • log (bool)

  • raise_error (bool)

  • console_output (bool)

niamoto.common.utils.error_handler.setup_global_exception_handler()

Set up global exception handler for unhandled exceptions.

Return type:

None

niamoto.common.utils.logging_utils module

Logging utilities for Niamoto application.

class niamoto.common.utils.logging_utils.JsonFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Bases: Formatter

Formats log records as JSON strings with support for NiamotoError details.

format(record)

Format the log record as a JSON string.

Parameters:

record (LogRecord) – The log record to format

Returns:

Formatted JSON string

Return type:

str

niamoto.common.utils.logging_utils.setup_logging(component_name=None, log_directory=None, log_level=20, enable_console=True, enable_file=True, console_format=None)

Set up logging configuration for a component.

Parameters:

  • component_name (str | None) – Name of the component (affects log file name)

  • log_directory (str | None) – Directory for log files (defaults to NIAMOTO_LOGS or ‘logs’)

  • log_level (int) – Logging level to use

  • enable_console (bool) – Whether to enable console output

  • enable_file (bool) – Whether to enable file logging

  • console_format (str | None) – Optional format for console output

Returns:

Configured logger instance

Raises:

LoggingError – If there’s an error setting up logging

Return type:

Logger

niamoto.common.utils.logging_utils.log_error(logger, error, additional_info=None)

Log an error with additional context information.

Parameters:

  • logger (Logger) – Logger instance to use

  • error (Exception | NiamotoError) – Exception to log

  • additional_info (Dict[str, Any] | None) – Additional context information

Return type:

None

This method ensures proper handling of NiamotoError details and additional context information.

class niamoto.common.utils.logging_utils.LoggerAdapter(logger, extra=None)

Bases: LoggerAdapter

Custom logger adapter that adds context information to log records.

process(msg, kwargs)

Process the logging message and keywords arguments.

Parameters:

  • msg (str) – Log message

  • kwargs (Dict[str, Any]) – Keyword arguments

Returns:

Tuple of processed message and kwargs

Return type:

tuple[str, dict[str, Any]]

niamoto.common.utils.logging_utils.get_component_logger(component_name, context=None)

Get a logger for a specific component with optional context information.

Parameters:

  • component_name (str) – Name of the component

  • context (Dict[str, Any] | None) – Optional context information to add to all log messages

Returns:

Logger adapter instance

Return type:

LoggerAdapter

This is the recommended way to get a logger for a component as it ensures proper context information is added to all log messages.

Module contents

Common utilities for Niamoto.

niamoto.common.utils.error_handler(*, log=True, raise_error=True, console_output=True)

Decorator for standardized error handling.

Keyword Arguments:

  • log (bool) – Whether to log errors. Defaults to True.

  • raise_error (bool) – Whether to re-raise errors. Defaults to True.

  • console_output (bool) – Whether to output to console. Defaults to True.

Returns:

Decorator function that wraps the target function with error handling.

Return type:

Callable

Parameters:

  • log (bool)

  • raise_error (bool)

  • console_output (bool)

niamoto.common.utils.handle_error(error, log=True, raise_error=True, console_output=True)

Central error handler for standardized error processing.

Parameters:

  • error (Exception) – The exception to handle

  • log (bool) – Whether to log the error

  • raise_error (bool) – Whether to re-raise the error

  • console_output (bool) – Whether to output to console

Return type:

None

niamoto.common.utils.setup_global_exception_handler()

Set up global exception handler for unhandled exceptions.

Return type:

None

niamoto.common.utils.get_error_details(error)

Extract error details from an exception.

Parameters:

error (Exception) – The exception to process

Returns:

Dictionary containing error details

Return type:

dict

niamoto.common.utils.format_error_message(error)

Format an error message for display.

Parameters:

error (Exception) – The exception to format

Returns:

Formatted error message

Return type:

str