Module

_formatter_registry

Lazy formatter registry for Rosettes.

Formatters are loaded on-demand using functools.cache for thread-safe memoization.

Design Philosophy:

Mirrors the lexer registry pattern (seerosettes._registry) for consistency:

  1. Lazy loading: Formatter modules imported only on first use
  2. Cached instances: functools.cache ensures one instance per formatter
  3. Alias support: Multiple names resolve to the same formatter
  4. Thread-safe: cache is thread-safe; formatters are immutable

Architecture:

  • _FORMATTER_SPECS: Static mapping of names to (module, class) specs
  • _ALIAS_TO_NAME: Case-insensitive alias lookup
  • _get_formatter_by_canonical: Cached formatter instantiation

Available Formatters:

  • html: HTML output with semantic or Pygments CSS classes
  • terminal: ANSI escape codes for terminal output
  • null: No-op formatter for benchmarking/testing

Performance:

  • First call: ~0.5ms (module import + instantiation)
  • Subsequent calls: ~100ns (dict lookup + cache hit)

Common Mistakes:

# ❌ WRONG: Caching formatter instances
formatters = {"html": get_formatter("html")}

# ✅ CORRECT: Just call get_formatter() — already cached
formatter = get_formatter("html")

See Also:

  • rosettes._registry: Lexer registry (same pattern)
  • rosettes._protocol.Formatter: Protocol that formatters implement
  • rosettes.formatters: Formatter implementations
1Class4Functions

Classes

FormatterSpec 3 ▼
Specification for lazy-loading a formatter.

Specification for lazy-loading a formatter.

Attributes

Name Type Description
module str

Full module path (e.g., 'rosettes.formatters.html').
class_name str

Name of the formatter class in the module.
aliases tuple[str, ...]

Alternative names for lookup.

Functions

get_formatter 1 Formatter ▼
Get a formatter instance by name or alias.
def get_formatter(name: str) -> Formatter
Parameters
Name Type Description
name str

Formatter name or alias (e.g., 'html', 'terminal').
Returns
Formatter
_get_formatter_by_canonical 1 Formatter ▼
Internal cached loader.
def _get_formatter_by_canonical(canonical: str) -> Formatter
Parameters
Name Type Description
canonical str
Returns
Formatter
list_formatters 0 list[str] ▼
List all supported formatter names.
def list_formatters() -> list[str]
Returns
list[str]
supports_formatter 1 bool ▼
Check if a formatter is supported.
def supports_formatter(name: str) -> bool
Parameters
Name Type Description
name str
Returns
bool