haive.core.utils.debugkit.fallbacks¶

Fallback implementations for development utilities when dependencies are missing.

This module provides minimal fallback implementations that allow the development utilities to function even when optional dependencies (like rich, icecream, etc.) are not available. The fallbacks maintain the same API but with reduced functionality.

Classes¶

`FallbackBenchmark`	Minimal benchmarking implementation when advanced benchmarking tools are unavailable.
`FallbackDebug`	Minimal debug implementation when icecream and other debuggers are unavailable.
`FallbackLog`	Minimal logging implementation when rich and loguru are unavailable.
`FallbackLogContext`	Context manager for fallback logging.
`FallbackProfile`	Minimal profiling implementation when advanced profilers are unavailable.
`FallbackTrace`	Minimal tracing implementation when advanced tracers are unavailable.

Module Contents¶

class haive.core.utils.debugkit.fallbacks.FallbackBenchmark[source]¶

Minimal benchmarking implementation when advanced benchmarking tools are unavailable.

Provides basic performance measurement and comparison capabilities using standard Python timing mechanisms.

Examples

Basic benchmarking:

benchmark = FallbackBenchmark()

def test_function():
    return sum(range(1000))

stats = benchmark.measure(test_function, iterations=100)
print(f"Average time: {stats['average']:.3f}s")

Initialize fallback benchmarker.

compare(functions, iterations=100)[source]¶

Compare performance of multiple functions.

Parameters:

functions (dict[str, collections.abc.Callable]) – Dictionary of name -> function pairs
iterations (int) – Number of iterations per function

Returns:

Comparison results dictionary

Return type:

dict[str, dict[str, Any]]

Examples

Compare implementations:

results = benchmark.compare({
    'list_comp': lambda: [x**2 for x in range(1000)],
    'map_pow': lambda: list(map(lambda x: x**2, range(1000)))
})

fastest = min(results.items(), key=lambda x: x[1]['average'])
print(f"Fastest: {fastest[0]}")

measure(func, iterations=100, warmup=10)[source]¶

Measure function performance over multiple iterations.

Parameters:

func (collections.abc.Callable) – Function to benchmark
iterations (int) – Number of measurement iterations
warmup (int) – Number of warmup iterations

Returns:

Performance statistics dictionary

Return type:

dict[str, Any]

Examples

Benchmark with custom iterations:

def computation():
    return [x**2 for x in range(1000)]

stats = benchmark.measure(computation, iterations=50)
print(f"Min: {stats['min']:.3f}s, Max: {stats['max']:.3f}s")

class haive.core.utils.debugkit.fallbacks.FallbackDebug[source]¶

Minimal debug implementation when icecream and other debuggers are unavailable.

Provides basic debugging functionality using standard print statements with enhanced formatting to approximate the full debug experience.

Examples

Basic debugging output:

debug = FallbackDebug()
debug.ice("Processing", count=10, status="active")
# Output: DEBUG: Processing | count=10, status=active

Initialize fallback debugger.

breakpoint_on_exception(func)[source]¶

Decorator to start debugger on exceptions.

Parameters:: func (collections.abc.Callable) – Function to wrap with exception debugging
Returns:: Wrapped function that debugs on exceptions
Return type:: collections.abc.Callable

ice(*args, **kwargs)[source]¶

Fallback implementation of icecream-style debugging.

Parameters:

*args (Any) – Positional arguments to debug
**kwargs (Any) – Named arguments to debug

Returns:

The first positional argument for chaining

Return type:

Any

Examples

Debug with return value:

result = debug.ice(expensive_computation())
debug.ice("Status", processing=True, count=len(items))

pdb()[source]¶

Start Python debugger.

Falls back to standard pdb when enhanced debuggers are unavailable.

Return type:: None

trace_calls(func)[source]¶

Decorator to trace function calls.

Parameters:: func (collections.abc.Callable) – Function to trace
Returns:: Wrapped function with call tracing
Return type:: collections.abc.Callable

class haive.core.utils.debugkit.fallbacks.FallbackLog[source]¶

Minimal logging implementation when rich and loguru are unavailable.

Provides structured logging functionality using standard Python logging with enhanced formatting and context management capabilities.

Examples

Basic logging:

log = FallbackLog()
log.info("Process started", user_id=123)
log.success("Operation completed successfully")
log.error("Failed to process", error="Connection timeout")

Initialize fallback logger.

context(name)[source]¶

Create logging context.

Parameters:: name (str) – Context name
Returns:: Context manager for structured logging
Return type:: FallbackLogContext

debug(message, **kwargs)[source]¶

Log debug message.

Parameters:

message (str) – Debug message
**kwargs (Any) – Additional context fields

Return type:

None

error(message, **kwargs)[source]¶

Log error message.

Parameters:

message (str) – Error message
**kwargs (Any) – Additional context fields

Return type:

None

info(message, **kwargs)[source]¶

Log info message.

Parameters:

message (str) – Info message
**kwargs (Any) – Additional context fields

Return type:

None

set_correlation_id(correlation_id)[source]¶

Set correlation ID for distributed tracing.

Parameters:: correlation_id (str) – Unique identifier for request correlation
Return type:: None

success(message, **kwargs)[source]¶

Log success message.

Parameters:

message (str) – Success message
**kwargs (Any) – Additional context fields

Return type:

None

warning(message, **kwargs)[source]¶

Log warning message.

Parameters:

message (str) – Warning message
**kwargs (Any) – Additional context fields

Return type:

None

class haive.core.utils.debugkit.fallbacks.FallbackLogContext(logger, name)[source]¶

Context manager for fallback logging.

Provides basic context management for logging operations, tracking timing and nested context levels.

Initialize log context.

Parameters:

logger (FallbackLog) – Parent logger instance
name (str) – Context name

debug(message, **kwargs)[source]¶

Log debug message within context.

Parameters:

message (str)
kwargs (Any)

Return type:

None

error(message, **kwargs)[source]¶

Log error message within context.

Parameters:

message (str)
kwargs (Any)

Return type:

None

info(message, **kwargs)[source]¶

Log info message within context.

Parameters:

message (str)
kwargs (Any)

Return type:

None

success(message, **kwargs)[source]¶

Log success message within context.

Parameters:

message (str)
kwargs (Any)

Return type:

None

class haive.core.utils.debugkit.fallbacks.FallbackProfile[source]¶

Minimal profiling implementation when advanced profilers are unavailable.

Provides basic timing and memory profiling using standard Python mechanisms without external dependencies.

Examples

Function timing:

profile = FallbackProfile()

@profile.time
def slow_function():
    time.sleep(1)
    return "done"

Initialize fallback profiler.

start_context(name)[source]¶

Start profiling context.

Parameters:: name (str) – Context name
Returns:: Context data for stopping profiler
Return type:: dict[str, Any]

stop_context(context)[source]¶

Stop profiling context and return statistics.

Parameters:: context (dict[str, Any]) – Context data from start_context
Returns:: Profiling statistics
Return type:: dict[str, Any]

time(func)[source]¶

Decorator to time function execution.

Parameters:: func (collections.abc.Callable) – Function to time
Returns:: Wrapped function with timing
Return type:: collections.abc.Callable

class haive.core.utils.debugkit.fallbacks.FallbackTrace[source]¶

Minimal tracing implementation when advanced tracers are unavailable.

Provides basic function call tracing and variable tracking using standard Python mechanisms without external dependencies.

Examples

Function call tracing:

trace = FallbackTrace()

@trace.calls
def my_function():
    return "result"

Initialize fallback tracer.

calls(func)[source]¶

Decorator to trace function calls.

Parameters:: func (collections.abc.Callable) – Function to trace
Returns:: Wrapped function with call tracing
Return type:: collections.abc.Callable

mark(name, value)[source]¶

Mark a trace point with a value.

Parameters:

name (str) – Trace point name
value (Any) – Value to record

Return type:

None

pop_context()[source]¶

Pop the current tracing context.

Return type:: None

push_context(name, correlation_id)[source]¶

Push a new tracing context.

Parameters:

name (str) – Context name
correlation_id (str) – Correlation identifier

Return type:

None

set_correlation_id(correlation_id)[source]¶

Set correlation ID for distributed tracing.

Parameters:: correlation_id (str) – Unique identifier for request correlation
Return type:: None