Utils Module

The utils module contains utility functions and helpers for Dashboard Lego.

Formatting Utilities

This module provides utility functions for formatting values.

class dashboard_lego.utils.formatting.NumpyEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: JSONEncoder

Custom JSON encoder for NumPy types. This encoder handles the serialization of common NumPy data types that are not natively supported by the standard json library. It converts NumPy integers, floats, booleans, and arrays into their standard Python equivalents.

hierarchy:

[Utils | Formatting | NumpyEncoder]

relates-to:

• motivated_by: “Bug: TypeError during cache key generation for NumPy types.”

• implements: “utility: ‘NumpyEncoder’”

contract:

• pre: “Input object obj can be a standard type or a NumPy type.”

• post: “Returns a JSON-serializable representation of the object.”

default(obj: Any) → Any

Overrides the default JSON encoding behavior to handle NumPy types.

Parameters:

obj – The object to encode.

Returns:

A serializable representation of the object.

dashboard_lego.utils.formatting.format_number(value: Any) → str

Formats a number into a string with appropriate separators.

• Floats are formatted to two decimal places.

• Integers are formatted with thousand separators.

• Other types are converted to strings.

  hierarchy:

  [Utils | Formatting | format_number]

  relates-to:

  • motivated_by: “Architectural Conclusion: Consistent number formatting improves user experience across all dashboard components”

  • implements: “utility: ‘format_number’”

  rationale:

  “A simple function was chosen for direct extraction of formatting logic from KPIBlock, avoiding over-engineering.”

  contract:

  • pre: “Input value can be of any type.”

  • post: “Returns a formatted string representation of the value.”

Parameters:

value – The number or value to format.

Returns:

A formatted string.

Logging Utilities

Async-compatible logging configuration for dashboard_lego using Loguru.

This module provides a modern, async-compatible logging system with automatic hierarchy extraction from docstrings and dual output (console + rotating file).

hierarchy:

[Core | Logging | Async Logger]

class dashboard_lego.utils.logger.HierarchyLoggerAdapter(name: str, hierarchy: str | None = None)

Bases: object

Logger adapter that prepends hierarchy to DEBUG logs.

Wraps loguru logger with hierarchy support from docstrings.

Hierarchy:

[Core | Logging | HierarchyLoggerAdapter]

__init__(name: str, hierarchy: str | None = None)

Initialize logger adapter with hierarchy context.

Parameters:

• name – Logger name (typically __name__)

• hierarchy – Hierarchy string extracted from docstrings

debug(message: str, **kwargs)

Log debug message with hierarchy prefix.

info(message: str, **kwargs)

Log info message.

warning(message: str, **kwargs)

Log warning message.

error(message: str, **kwargs)

Log error message.

critical(message: str, **kwargs)

Log critical message.

exception(message: str, exc_info=True, **kwargs)

Log exception with traceback.

isEnabledFor(level: int) → bool

Check if logger is enabled for given level.

dashboard_lego.utils.logger.get_logger(name: str, obj: Any | None = None) → HierarchyLoggerAdapter

Factory function to create a logger with automatic hierarchy extraction.

Hierarchy:

[Core | Logging | Logger Factory]

Parameters:

• name – The name for the logger (typically __name__).

• obj – Optional object (class, function) to extract hierarchy from.

Returns:

A configured HierarchyLoggerAdapter instance.

Example

>>> logger = get_logger(__name__, MyClass)
>>> logger.debug("This will include hierarchy")
>>> logger.info("This is for users")

dashboard_lego.utils.logger.setup_logging(level: str | None = None, log_dir: str | None = None) → None

Configure async-compatible logging with Loguru.

Hierarchy:

[Core | Logging | Setup]

Parameters:

• level – Log level as string (DEBUG, INFO, WARNING, ERROR, CRITICAL). Defaults to environment variable or INFO.

• log_dir – Directory for log files. Defaults to ./logs.

dashboard_lego.utils.logger.update_log_level(level: str | None = None) → None

Update log level for existing loggers.

Useful when environment variable is changed after module import.

Parameters:

level – Log level as string (DEBUG, INFO, WARNING, ERROR, CRITICAL). If None, reads from DASHBOARD_LEGO_LOG_LEVEL environment variable.

Data Utilities

Validation Utilities