ChuckandClaude Opus 5.5
d37a3a712a
Codacy (Bandit B110, B108). The bench's silent except now prints why it read config.json directly. The stats file's fixed name in /dev/shm is safe: write() goes through mkstemp and os.replace, which replaces a planted symlink instead of following it; the comment says so and marks it nosec. 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