ChuckandClaude Opus 5.5
9a705c2ca4
84043468 also gated the ESPN chunk fetches and the background data
service's workers, for the hourly sports refresh. A burst test on hdpi
(baseball and football refreshing every 5 minutes, 10-minute soaks, G F F G):
G prefetch gated only 0.87%, 0.83% late; 6+ late 20, 16; fetches 0.3-1.8s
F + fetch threads gated 1.23%, 1.05% late; 6+ late 12, 16; fetches 1.6-4.6s
Every parked fetch thread wakes at each swap and has to take the GIL again
just to park at the end of the window, so twenty of them cost more than
they saved, and the fetches ran two to three times as long. The plugins'
own copies of espn_dates (half the burst) were never gated anyway.
espn_dates and the background data service go back to main's versions and
the module-level active gate goes. Kept from that commit: the render thread
is never gated, a live refresh from another thread can't take its place,
and nested blocks keep the outer boundary.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>Common Utilities
This directory contains reusable utilities and helpers for LEDMatrix plugins and core modules.
Adaptive Layout & Images (src/adaptive_layout.py, src/adaptive_images.py)
The recommended way to lay out plugins that render legibly on any panel
size (64x32 through 256x128+) without hand-tuned coordinates. Re-exported
from src.common for convenience; canonical import paths are
src.adaptive_layout / src.adaptive_images.
# Every BasePlugin already has self.layout and the draw helpers:
regs = scoreboard_regions(self.layout.bounds, ctx=self.layout)
self.draw_image(away_logo, regs.away_slot, mode="fill_height",
crop_to_ink=True, cache_key=f"logo:{abbr}")
self.draw_fit(score_text, regs.score_area) # largest crisp font that fits
self.draw_fit(status, regs.status_band)
Key pieces: Region (rect algebra: bands/columns/splits/offset),
font ladders (LADDER_GRID, LADDER_ARCADE — discrete crisp sizes, never
fractional scaling), LayoutContext (fit_text, fit_image, by_tier,
px), and composite carvers scoreboard_regions() / media_row().
Full guide: docs/ADAPTIVE_LAYOUT.md.
API Helpers (api_helper.py)
Utilities for making HTTP requests and handling API responses.
Logo Helpers (logo_helper.py)
Utilities for loading and managing team logos.
Text Helpers (text_helper.py)
Utilities for text processing and formatting.
BDF Fonts (bdf_font.py)
The one way to load and draw BDF bitmap fonts. load_bdf_face(path, size)
returns (face, realised_px), falling back to the file's native strike when
it has none at size; draw_bdf_text(draw, text, x, y, face, color) draws
top-left anchored onto a PIL ImageDraw exactly as the panel does.
DisplayManager, FontManager, element_style and the plugin test harness
all go through it.
Scroll Helpers (scroll_helper.py)
Utilities for scrolling text on the display.
Permission Utilities (permission_utils.py)
Helpers for ensuring directory permissions and ownership are correct
when running as a service (used by CacheManager to set up its
persistent cache directory).
Best Practices
- Use centralized logging: Import from
src.logging_configinstead of creating loggers directly - Reuse utilities: Check existing utilities before creating new ones
- Document additions: Add documentation when adding new utilities