Syntax Reference¶

class Syntax(Gradient):
    """A Rich syntax-highlighting convenience constructor with gradient rendering.

    Args:
        code: Source code to highlight.
        lexer: Lexer name or Pygments lexer instance.
        theme: Pygments style theme.
        dedent: Whether to strip initial indentation.
        line_numbers: Whether to render line numbers.
        start_line: Starting line number.
        line_range: Optional start/end line range.
        highlight_lines: Optional line numbers to highlight.
        code_width: Optional code width.
        tab_size: Spaces per tab.
        word_wrap: Whether to wrap long lines.
        background_color: Optional background color.
        indent_guides: Whether to show indentation guides.
        padding: Padding around syntax output.
        colors: Foreground gradient color stops.
        bg_colors: Background gradient color stops.
        rainbow: Whether to generate a rainbow palette.
        hues: Number of auto-generated hues.
        repeat_scale: Scale factor controlling gradient repeats. Defaults to None,
            which derives it from the color stops.
        expand: Whether the gradient frame expands.
        justify: Horizontal alignment.
        vertical_justify: Vertical alignment.
        console: Optional Rich console.
        highlight_words: Word highlight configuration.
        highlight_regex: Regex highlight configuration.
        keep_token_colors: Keep the theme's colors for highlighted tokens
            (keywords, strings, comments, ...). Only plain code, line numbers
            and whitespace take the gradient. Set to ``False`` to recolor
            everything with the gradient.
    """

    def __init__(
        self,
        code: str,
        lexer: str | Lexer,
        *,
        theme: str = "monokai",
        dedent: bool = False,
        line_numbers: bool = False,
        start_line: int = 1,
        line_range: tuple[int | None, int | None] | None = None,
        highlight_lines: set[int] | None = None,
        code_width: int | None = None,
        tab_size: int = 4,
        word_wrap: bool = False,
        background_color: str | None = None,
        indent_guides: bool = False,
        padding: PaddingDimensions = 0,
        colors: Sequence[ColorType] | None = None,
        bg_colors: Sequence[ColorType] | None = None,
        rainbow: bool = False,
        hues: int = 5,
        repeat_scale: float | None = None,
        expand: bool = True,
        justify: AlignMethod = "left",
        vertical_justify: VerticalAlignMethod = "middle",
        console: Console | None = None,
        highlight_words: HighlightWordsType | None = None,
        highlight_regex: HighlightRegexType | None = None,
        keep_token_colors: bool = True,
    ) -> None:
        """Initialize gradient-enabled Rich syntax highlighting."""
        self._base_color: Color | None = None
        syntax = RichSyntax(
            code,
            lexer,
            theme=theme,
            dedent=dedent,
            line_numbers=line_numbers,
            start_line=start_line,
            line_range=line_range,
            highlight_lines=highlight_lines,
            code_width=code_width,
            tab_size=tab_size,
            word_wrap=word_wrap,
            background_color=background_color,
            indent_guides=indent_guides,
            padding=padding,
        )
        self._syntax = syntax
        if keep_token_colors:
            self._base_color = syntax._theme.get_style_for_token(Token).color
        super().__init__(
            syntax,
            colors=list(colors) if colors is not None else None,
            bg_colors=list(bg_colors) if bg_colors is not None else None,
            console=console,
            hues=hues,
            rainbow=rainbow,
            expand=expand,
            justify=justify,
            vertical_justify=vertical_justify,
            repeat_scale=repeat_scale,
            highlight_words=highlight_words,
            highlight_regex=highlight_regex,
        )

    def _merge_styles(self, original: Style, gradient_style: Style) -> Style:
        """Leave highlighted tokens alone; apply the gradient to everything else."""
        color = original.color
        if self._base_color is not None and color is not None and color != self._base_color:
            return original
        return super()._merge_styles(original, gradient_style)

    @property
    def syntax(self) -> RichSyntax:
        """Return the underlying Rich Syntax renderable."""
        return self._syntax