Skip to main content

performance - API Specification

Version: v1.0.0 | Status: Active | Last Updated: February 2026

Introduction​

This document provides the complete API specification for the performance module.

Module Overview​

The performance module provides utilities for optimizing application execution, including lazy loading, intelligent caching, and comprehensive performance monitoring.

Functions​

Function: lazy_import(module_name: str, **kwargs) -> LazyLoader​

  • Description: Creates a lazy loader for importing modules on-demand to improve startup performance.
  • Parameters:
    • module_name: Name of the module to lazy load.
    • **kwargs: Additional configuration options.
  • Return Value: LazyLoader object that imports the module when first accessed.
  • Errors: Raises ImportError if the module cannot be found when accessed.

Function: cached_function(ttl_seconds: int = 300, max_size: int = 128, **kwargs) -> Callable​

  • Description: Decorator that adds caching to functions to improve performance for expensive operations.
  • Parameters:
    • ttl_seconds: Time-to-live for cached results (default: 300 seconds).
    • max_size: Maximum number of cached results (default: 128).
    • **kwargs: Additional cache configuration options.
  • Return Value: Decorated function with caching capability.
  • Errors: Raises CacheError for cache configuration issues.

Classes​

CacheManager​

Description: Manages multiple cache instances with intelligent invalidation and memory management.

Methods​

__init__(default_ttl: int = 300, max_memory_mb: int = 100, **kwargs)

  • Initialize cache manager with default settings.
  • Parameters: default_ttl, max_memory_mb, cache configuration options.
  • Errors: Raises CacheError for invalid configuration.

get_cache(name: str) -> Cache

  • Retrieve or create a named cache instance.
  • Parameters: name, cache identifier.
  • Return Value: Cache instance for the given name.

clear_cache(name: str = None)

  • Clear specific cache or all caches.
  • Parameters: name, optional cache name (clears all if None).

get_stats() -> Dict

  • Get cache performance statistics.
  • Return Value: Dictionary with hit rates, memory usage, and performance metrics.

LazyLoader​

Description: Provides on-demand loading of modules and resources to improve application startup time.

Methods​

__init__(loader: Callable, **kwargs)

  • Initialize lazy loader with loading function.
  • Parameters: loader, function that performs the actual loading.

load() -> Any

  • Perform the actual loading operation.
  • Return Value: Loaded resource or module.

is_loaded() -> bool

  • Check if the resource has been loaded.
  • Return Value: True if loaded, False otherwise.

PerformanceMonitor (Optional)​

Description: Monitors application performance metrics (requires psutil).

Methods​

start_monitoring(interval_seconds: float = 1.0)

  • Start performance monitoring with specified interval.
  • Parameters: interval_seconds, monitoring frequency.

stop_monitoring()

  • Stop performance monitoring.

get_metrics() -> Dict

  • Get current performance metrics.
  • Return Value: Dictionary with CPU, memory, disk, and network metrics.

get_report() -> str

  • Generate performance report.
  • Return Value: Formatted performance report string.

Data Structures​

CacheConfig​

Configuration for cache instances:

{
    "ttl_seconds": <int>,
    "max_size": <int>,
    "eviction_policy": "lru|lfu|random",
    "compression": <bool>,
    "persistent": <bool>
}

PerformanceMetrics​

Performance monitoring data:

{
    "timestamp": <datetime>,
    "cpu_percent": <float>,
    "memory_percent": <float>,
    "memory_mb": <float>,
    "disk_read_mb": <float>,
    "disk_write_mb": <float>,
    "network_rx_mb": <float>,
    "network_tx_mb": <float>
}

Integration Examples​

Lazy Loading for Heavy Imports​

from codomyrmex.performance import lazy_import

# Lazy load heavy ML libraries
torch = lazy_import("torch")
transformers = lazy_import("transformers")

# Libraries are only imported when first accessed
model = torch.load("model.pth")  # Imports torch here

Function Caching​

from codomyrmex.performance import cached_function

@cached_function(ttl_seconds=600, max_size=50)
def expensive_api_call(user_id: str) -> Dict:
    # Expensive database or API operation
    return get_user_data(user_id)

# First call performs operation and caches result
data1 = expensive_api_call("user123")

# Subsequent calls return cached result
data2 = expensive_api_call("user123")  # Returns cached data

Performance Monitoring​

from codomyrmex.performance import PerformanceMonitor

monitor = PerformanceMonitor()
monitor.start_monitoring(interval_seconds=5.0)

# Run performance-critical code
perform_expensive_operation()

# Get performance report
report = monitor.get_report()
print(report)

monitor.stop_monitoring()