Address PR review feedback - code quality improvements

- Use absolute imports in base.py (comment 2744902663)
- Move prometheus example instructions to module docstring (comment 2744908071)
- Use contextlib.suppress for exception handling (comments 2744912772, SIM105)
- Remove trailing commas for 120 line length (comments 2744919532, 2744929433)
- Add comment explaining yields in collector (comment 2744926357)
- Use single formatted string appends (comment 2744927877)
- Fix README prometheus_client mode documentation (comment 2744928794)
- Clarify cache size metrics backend support (comment 2744928804)
- Pass host parameter to start_http_server (comment 2744928825)
- Fix metric names consistency with _total suffix (comment 2744928839)
- Remove unused _last_seen dict (comment 2744928850)
- Use monotonic clock for windowed latency calculations (comment 2744928866)
- Record miss on stale hit for accurate hit rate (comment 2744928891)
- Add explanatory comment to except clause (comment 2744928901)
- Don't swallow exceptions in start() method (comment 2744928818)

All 21 tests passing

Co-authored-by: Borda <6035284+Borda@users.noreply.github.com>

Author: Copilot

examples/prometheus_exporter_example.py

@@ -1,144 +1,126 @@
-"""Demonstration of Prometheus metrics exporter for cachier.
+"""Prometheus Exporter Example for Cachier.
 
-This example shows how to export cachier metrics to Prometheus for monitoring. The exporter can work with or without the
-prometheus_client library.
+This example demonstrates using the PrometheusExporter to export cache metrics
+to Prometheus for monitoring and alerting.
 
-"""
-
-import time
-
-from cachier import cachier
-from cachier.exporters import PrometheusExporter
+Usage with Prometheus
+---------------------
 
-print("=" * 60)
-print("Cachier Prometheus Exporter Demo")
-print("=" * 60)
-
-
-# Define some cached functions with metrics enabled
-@cachier(backend="memory", enable_metrics=True)
-def calculate_square(x):
-    """Calculate square of a number."""
-    time.sleep(0.01)  # Simulate computation
-    return x**2
-
-
-@cachier(backend="memory", enable_metrics=True)
-def calculate_cube(x):
-    """Calculate cube of a number."""
-    time.sleep(0.01)  # Simulate computation
-    return x**3
-
-
-# Create a Prometheus exporter
-# Set use_prometheus_client=False to use built-in text format
-exporter = PrometheusExporter(port=9100, use_prometheus_client=False)
-
-# Register functions to export
-print("\nRegistering functions with exporter...")
-exporter.register_function(calculate_square)
-exporter.register_function(calculate_cube)
-print("✓ Functions registered")
-
-# Generate some cache activity
-print("\nGenerating cache activity...")
-calculate_square.clear_cache()
-calculate_cube.clear_cache()
-
-# Create some metrics
-for i in range(20):
-    calculate_square(i % 5)  # Will create hits and misses
-
-for i in range(15):
-    calculate_cube(i % 3)
-
-print("✓ Generated activity on both functions")
-
-# Display metrics for each function
-print("\n" + "=" * 60)
-print("Metrics Summary")
-print("=" * 60)
-
-square_stats = calculate_square.metrics.get_stats()
-print("\ncalculate_square:")
-print(f"  Hits: {square_stats.hits}")
-print(f"  Misses: {square_stats.misses}")
-print(f"  Hit rate: {square_stats.hit_rate:.1f}%")
-print(f"  Total calls: {square_stats.total_calls}")
-
-cube_stats = calculate_cube.metrics.get_stats()
-print("\ncalculate_cube:")
-print(f"  Hits: {cube_stats.hits}")
-print(f"  Misses: {cube_stats.misses}")
-print(f"  Hit rate: {cube_stats.hit_rate:.1f}%")
-print(f"  Total calls: {cube_stats.total_calls}")
-
-# Generate Prometheus text format
-print("\n" + "=" * 60)
-print("Prometheus Text Format Export")
-print("=" * 60)
-
-metrics_text = exporter._generate_text_metrics()
-print("\nSample of exported metrics:")
-print("-" * 60)
-# Print first 20 lines
-lines = metrics_text.split("\n")[:20]
-for line in lines:
-    print(line)
-print("...")
-print(f"\nTotal lines exported: {len(metrics_text.split(chr(10)))}")
-
-# Instructions for using with Prometheus
-print("\n" + "=" * 60)
-print("Usage with Prometheus")
-print("=" * 60)
-print("""
 To use this exporter with Prometheus:
 
 1. Start the exporter HTTP server:
    >>> exporter.start()
 
-2. Add to your prometheus.yml:
+2. Configure Prometheus to scrape the metrics endpoint.
+   Add this to your prometheus.yml:
+
    scrape_configs:
      - job_name: 'cachier'
        static_configs:
-         - targets: ['localhost:9100']
-
-3. Access metrics at http://localhost:9100/metrics
-
-4. Query in Prometheus:
-   - cachier_cache_hit_rate
-   - rate(cachier_cache_hits_total[5m])
-   - cachier_entry_count
-
-Alternative: Use with prometheus_client
----------------------------------------
-If you have prometheus_client installed:
-
->>> from prometheus_client import start_http_server
->>> exporter = PrometheusExporter(port=9100, use_prometheus_client=True)
->>> exporter.register_function(my_cached_func)
->>> exporter.start()
-
-This provides additional features like:
-- Automatic metric registration
-- Built-in histograms
-- Gauges and counters
-- Integration with Prometheus pushgateway
-""")
-
-print("\n" + "=" * 60)
-print("Demo Complete")
-print("=" * 60)
-print("""
-Key Benefits:
-  • Track cache performance in production
-  • Identify optimization opportunities
-  • Set up alerts for low hit rates
-  • Monitor cache effectiveness over time
-  • Integrate with existing monitoring infrastructure
-""")
-
-# Clean up
-calculate_square.clear_cache()
-calculate_cube.clear_cache()
+         - targets: ['localhost:9090']
+
+3. Access metrics at http://localhost:9090/metrics
+
+4. Create dashboards in Grafana or set up alerts based on:
+   - cachier_cache_hit_rate (target: > 80%)
+   - cachier_cache_misses_total (alert on spikes)
+   - cachier_avg_latency_ms (monitor performance)
+
+Available Metrics
+-----------------
+- cachier_cache_hits_total: Total number of cache hits
+- cachier_cache_misses_total: Total number of cache misses
+- cachier_cache_hit_rate: Cache hit rate percentage
+- cachier_avg_latency_ms: Average cache operation latency
+- cachier_stale_hits_total: Total stale cache hits
+- cachier_recalculations_total: Total cache recalculations
+- cachier_entry_count: Current number of cache entries
+- cachier_cache_size_bytes: Total cache size in bytes
+- cachier_size_limit_rejections_total: Entries rejected due to size limit
+
+"""
+
+import time
+
+from cachier import cachier
+from cachier.exporters import PrometheusExporter
+
+
+def demo_basic_metrics():
+    """Demonstrate basic metrics collection."""
+    print("\n=== Basic Metrics Collection ===")
+
+    @cachier(backend="memory", enable_metrics=True)
+    def compute(x):
+        time.sleep(0.1)  # Simulate work
+        return x * 2
+
+    compute.clear_cache()
+
+    # Generate some traffic
+    for i in range(5):
+        result = compute(i)
+        print(f"  compute({i}) = {result}")
+
+    # Access hits create cache hits
+    for i in range(3):
+        compute(i)
+
+    stats = compute.metrics.get_stats()
+    print("\nMetrics:")
+    print(f"  Hits: {stats.hits}")
+    print(f"  Misses: {stats.misses}")
+    print(f"  Hit Rate: {stats.hit_rate:.1f}%")
+    print(f"  Avg Latency: {stats.avg_latency_ms:.2f}ms")
+
+    compute.clear_cache()
+
+
+def demo_prometheus_export():
+    """Demonstrate exporting metrics to Prometheus."""
+    print("\n=== Prometheus Export ===")
+
+    @cachier(backend="memory", enable_metrics=True)
+    def calculate(x, y):
+        return x + y
+
+    calculate.clear_cache()
+
+    # Create exporter
+    exporter = PrometheusExporter(port=9090, use_prometheus_client=False)
+    exporter.register_function(calculate)
+
+    # Generate some metrics
+    calculate(1, 2)
+    calculate(1, 2)  # hit
+    calculate(3, 4)  # miss
+
+    # Show text format metrics
+    metrics_text = exporter._generate_text_metrics()
+    print("\nGenerated Prometheus metrics:")
+    print(metrics_text[:500] + "...")
+
+    print("\nNote: In production, call exporter.start() to serve metrics")
+    print("      Metrics would be available at http://localhost:9090/metrics")
+
+    calculate.clear_cache()
+
+
+def main():
+    """Run all demonstrations."""
+    print("Cachier Prometheus Exporter Demo")
+    print("=" * 60)
+
+    # Print usage instructions from module docstring
+    if __doc__:
+        print(__doc__)
+
+    demo_basic_metrics()
+    demo_prometheus_export()
+
+    print("\n" + "=" * 60)
+    print("✓ All demonstrations completed!")
+
+
+if __name__ == "__main__":
+    main()

src/cachier/core.py

@@ -302,7 +302,7 @@ def cachier(
             hash_func=hash_func,
             wait_for_calc_timeout=wait_for_calc_timeout,
             entry_size_limit=size_limit_bytes,
-            metrics=cache_metrics,
+            metrics=cache_metrics
         )
     elif backend == "sql":
         core = _SQLCore(

src/cachier/cores/base.py

@@ -16,11 +16,11 @@
 
 from pympler import asizeof  # type: ignore
 
-from .._types import HashFunc
-from ..config import CacheEntry, _update_with_defaults
+from cachier._types import HashFunc
+from cachier.config import CacheEntry, _update_with_defaults
 
 if TYPE_CHECKING:
-    from ..metrics import CacheMetrics
+    from cachier.metrics import CacheMetrics
 
 
 class RecalculationNeeded(Exception):
@@ -122,14 +122,14 @@ def _update_size_metrics(self) -> None:
         """
         if self.metrics is None:
             return
-        try:
-            # Get cache size - subclasses should override if they can provide this
+        from contextlib import suppress
+
+        # Get cache size - subclasses should override if they can provide this
+        # Suppress errors if subclass doesn't implement size tracking
+        with suppress(AttributeError, NotImplementedError):
             entry_count = self._get_entry_count()
             total_size = self._get_total_size()
             self.metrics.update_size_metrics(entry_count, total_size)
-        except (AttributeError, NotImplementedError):
-            # Silently skip if subclass doesn't implement size tracking
-            pass
 
     def _get_entry_count(self) -> int:
         """Get the number of entries in the cache.