API Reference

Rosettes formatters package. Contains output formatters for different targets (HTML, terminal, etc.). **Available Formatters:** - `HtmlFormatter`: HTML output with semantic or Pygments-compatible CSS classes - `TerminalFormatter`: ANSI escape codes for terminal output - `NullFormatter`: No-op formatter for testing and benchmarking **Usage:** Most users should use the high-level `rosettes.highlight()` function with the `formatter` parameter: ```python >>> from rosettes import highlight >>> html = highlight("def foo(): pass", "python", formatter="html") >>> ansi = highlight("def foo(): pass", "python", formatter="terminal") ``` Direct formatter usage is for: - Custom processing pipelines - Streaming output to files - Integration with external systems **Custom Formatters:** To create a custom formatter, implement the `rosettes._protocol.Formatter` protocol. See `rosettes.formatters.html` for a reference implementation. **See Also:** - `rosettes._protocol.Formatter`: Protocol definition for formatters - `rosettes._formatter_registry`: How formatters are registered

Rosettes lexers package. All lexers are hand-written state machines with O(n) guaranteed performance and zero ReDoS vulnerability. Lexers are loaded lazily via the registry.

Rosettes themes package. Semantic token system for syntax highlighting with modern CSS support. Provides palettes, CSS generation, and accessibility validation. **Design Philosophy:** Rosettes uses a **semantic role system** instead of individual token colors: 1. **Roles over Tokens**: ~20 semantic roles (FUNCTION, STRING, COMMENT) instead of 100+ token types. Themes define colors for roles. 2. **Separation of Concerns**: Token → Role mapping is language-agnostic. Palettes define colors for roles, not specific syntax. 3. **CSS Custom Properties**: Palettes generate CSS variables for runtime theming without regenerating HTML. **Quick Start:** ```python >>> from rosettes.themes import MONOKAI, get_palette >>> palette = get_palette("monokai") >>> css_vars = palette.to_css_vars() ``` **Architecture:** - `SyntaxRole`: Semantic meaning of code elements (FUNCTION, STRING, etc.) - TokenType → Role: Mapping from fine-grained tokens to semantic roles - `SyntaxPalette`: Immutable color definitions for each role - `AdaptivePalette`: Light/dark mode support with CSS media queries **Types:** - `SyntaxRole`: Enum of semantic roles - `SyntaxPalette`: Immutable theme definition (~20 color slots) - `AdaptivePalette`: Light/dark adaptive theme **Built-in Palettes:** Bengal Themes: - `BENGAL_TIGER`: Warm orange tones (default) - `BENGAL_SNOW_LYNX`: Cool light theme - `BENGAL_CHARCOAL`: Dark gray theme - `BENGAL_BLUE`: Cool blue tones Third-Party Compatible: - `MONOKAI`: Classic dark theme - `DRACULA`: Purple-accented dark theme - `GITHUB`: Light/dark GitHub-style themes **Custom Palettes:** ```python >>> from rosettes.themes import SyntaxPalette, register_palette >>> my_theme = SyntaxPalette( ... name="my-theme", ... background="#1a1a1a", ... text="#f0f0f0", ... string="#98c379", ... function="#61afef", ... ) >>> register_palette(my_theme) ``` **See Also:** - `rosettes.themes._roles`: SyntaxRole enum definition - `rosettes.themes._mapping`: TokenType → SyntaxRole mapping - `rosettes.themes._palette`: SyntaxPalette and AdaptivePalette classes