Module

themes._palette

Immutable palette definitions for Rosettes theming.

Provides frozen dataclasses for syntax highlighting palettes. All palettes are thread-safe by design.

Design Philosophy:

Palettes define colors for semantic roles, not individual tokens. This keeps themes manageable (~20 colors) while supporting 100+ token types.

Architecture:

  • SyntaxPalette: Single theme with fixed colors

    • ~20 color slots for semantic roles
    • Style modifiers (bold, italic)
    • CSS variable generation

  • AdaptivePalette: Light/dark mode support

    • Contains two SyntaxPalette instances
    • Generates@media (prefers-color-scheme)CSS

    Creating Palettes:

Minimal (only required fields):

>>> palette = SyntaxPalette(
...     name="minimal",
...     background="#1a1a1a",
...     text="#f0f0f0",
... )
>>> filled = palette.with_defaults()  # Fills missing colors

Complete (all roles specified):

>>> palette = SyntaxPalette(
...     name="complete",
...     background="#1a1a1a",
...     text="#f0f0f0",
...     string="#98c379",
...     number="#d19a66",
...     function="#61afef",
...     # ... all other roles ...
... )

CSS Generation:

>>> css_vars = palette.to_css_vars(indent=2)
>>> print(css_vars)
  --syntax-bg: #1a1a1a;
  --syntax-string: #98c379;
  ...

Thread-Safety:

Both classes are frozen dataclasses. Once created, they cannot be modified. Safe to share across threads.

See Also:

  • rosettes.themes: Palette registry and built-in palettes
  • rosettes.themes._roles: SyntaxRole enum (what the colors are for)
2Classes

Classes

SyntaxPalette 36 ▼
Immutable syntax highlighting palette. Thread-safe by design. Defines ~20 semantic color slots ins…

Immutable syntax highlighting palette.

Thread-safe by design. Defines ~20 semantic color slots instead of 100+ individual token colors.

Required Fields: name: Unique identifier for the palette background: Background color for code blocks text: Default text color

Optional Fields: All other fields default to empty string and are filled by with_defaults() using sensible fallbacks.

Attributes

Name Type Description
name str —
background str —
text str —
background_highlight str —
control_flow str —
declaration str —
import_ str —
string str —
number str —
boolean str —
type_ str —
function str —
variable str —
constant str —
comment str —
docstring str —
error str —
warning str —
added str —
removed str —
muted str —
punctuation str —
operator str —
attribute str —
namespace str —
tag str —
regex str —
escape str —
bold_control bool —
bold_declaration bool —
italic_comment bool —
italic_docstring bool —

Methods

with_defaults 0 SyntaxPalette ▼
Return a new palette with empty fields filled from defaults.
def with_defaults(self) -> SyntaxPalette
Returns
SyntaxPalette
to_css_vars 1 str ▼
Generate CSS custom property declarations.
def to_css_vars(self, indent: int = 0) -> str
Parameters
Name Type Description
indent — Default:0
Returns
str
generate_css 0 str ▼
Generate complete CSS stylesheet for syntax highlighting. Generates CSS rules …
def generate_css(self) -> str

Generate complete CSS stylesheet for syntax highlighting.

Generates CSS rules for all semantic roles, suitable for use with the HTML formatter.

Returns
str Complete CSS stylesheet as a string.
Internal Methods 1 ▼
__post_init__ 0 ▼
Validate palette after initialization.
def __post_init__(self) -> None
AdaptivePalette 5 ▼
Theme that adapts to light/dark mode preference. Wraps two SyntaxPalette instances for light and d…

Theme that adapts to light/dark mode preference.

Wraps two SyntaxPalette instances for light and dark mode. Generates CSS with @media (prefers-color-scheme) queries.

Thread-safe: frozen dataclass containing frozen palettes.

CSS Generation:

Adaptive palettes generate CSS with media queries:

@media (prefers-color-scheme: light) {
  :root { --syntax-bg: #ffffff; ... }
}
@media (prefers-color-scheme: dark) {
  :root { --syntax-bg: #0d1117; ... }
}

Attributes

Name Type Description
name str

Unique identifier for the adaptive palette
light SyntaxPalette

Palette for light mode (prefers-color-scheme: light)
dark SyntaxPalette

Palette for dark mode (prefers-color-scheme: dark)

Methods

generate_css 0 str ▼
Generate adaptive CSS with light/dark mode support. Generates CSS with @media …
def generate_css(self) -> str

Generate adaptive CSS with light/dark mode support.

Generates CSS with @media (prefers-color-scheme) queries for automatic light/dark mode switching.

Returns
str Complete CSS stylesheet with media queries.
Internal Methods 1 ▼
__post_init__ 0 ▼
Validate adaptive palette.
def __post_init__(self) -> None