Syntax Highlighting

code_block highlights source code with Pygments, in any of the languages it knows, and draws it on its theme's background.

--8 < --"syntax_highlighting.py:example"

ScreenshotText

 github-dark                                      

 @component                                       
 def greeting(name: str) -> Text:                 
     """Say hello."""                             
     return Text(content=f"Hello, {name}!")       


 monokai                                          

 @component                                       
 def greeting(name: str) -> Text:                 
     """Say hello."""                             
     return Text(content=f"Hello, {name}!")       


 solarized-light                                  

 @component                                       
 def greeting(name: str) -> Text:                 
     """Say hello."""                             
     return Text(content=f"Hello, {name}!")       

A theme is the name of any Pygments style, or a pygments.style.Style subclass, which is how to define your own.

To lay the code out yourself, highlight returns its chunks, to put in a Text with whatever else you like, and code_style the background and text color to draw them on.

Highlighting is cached by its arguments, so a component can highlight the same code on every render without lexing it again. Tabs are expanded, to four columns unless tab_size says otherwise.

API

counterweight.highlighting

Syntax highlighting: source code as styled Chunks, colored by a Pygments lexer and style.

Highlighting is a pure function of its arguments, so the results are cached, and a component can highlight the same code on every render without lexing it again.

DEFAULT_CODE_THEME module-attribute

DEFAULT_CODE_THEME: CodeTheme = 'github-dark'

CodeTheme

CodeTheme = str | type[Style]

highlight cached

highlight(
    code: str,
    language: str,
    theme: CodeTheme = DEFAULT_CODE_THEME,
    tab_size: int = 4,
) -> tuple[Chunk, ...]

code as chunks styled by the tokens a Pygments lexer finds in it.

language is any name or alias of a Pygments lexer, such as python, py, or toml; theme is a Pygments style, by name (any of pygments.styles.get_all_styles()) or as a pygments.style.Style subclass, which is how to define your own. An unknown language or theme raises pygments.util.ClassNotFound. Tabs are expanded to tab_size columns.

The theme's colors are set only where it sets them, so the rest come from the Text's text_style: put the chunks in a Text styled by code_style to draw them on the theme's background.

code_block

code_block(
    code: str,
    language: str,
    theme: CodeTheme = DEFAULT_CODE_THEME,
    style: Style | None = None,
    tab_size: int = 4,
) -> Text

A Text of code highlighted as language, on the theme's background, with style merged over code_style.

code_style cached

code_style(theme: CodeTheme = DEFAULT_CODE_THEME) -> Style

The theme's background and its plain text's style, for a Text holding chunks from highlight.