JupyterLab Pygments Theme

Warnings

• gotcha Pygments-generated HTML and CSS classes from this theme are not as granular as JupyterLab's CodeMirror editor. This means some visual nuances, like differentiating properties from general names or how dots in `foo.bar` are styled, cannot be perfectly replicated.
  Fix: Be aware of these inherent limitations of Pygments styling when expecting an exact match to CodeMirror's rendering.
• gotcha When directly embedding Pygments-generated HTML and CSS (especially with `HtmlFormatter`) into Jupyter Notebook/Lab cell outputs, the CSS can sometimes conflict with the global Jupyter theme, potentially affecting the readability of other output elements or applying unintended styles.
  Fix: Ensure that the generated HTML and CSS are properly scoped (e.g., by using a unique `cssclass` for the formatter and styling it appropriately) to minimize conflicts. Consider generating `full=True` output that includes the `<style>` tags for isolated styling.
• breaking There have been reported issues with recursive build-time dependencies (e.g., `jupyterlab-pygments`, `jupyterlab`, `nbconvert`) leading to bootstrapping problems during packaging, especially when upgrading Python versions (e.g., 3.8 to 3.9). This can make it difficult for packagers to build and install these components.
  Fix: This is an ongoing issue being addressed by the JupyterLab team, with work moving towards a separate `jupyterlab-builder` package. Packagers should monitor the `jupyterlab/jupyterlab-builder` repository for updates and potential solutions.
• deprecated While `jupyterlab-pygments` is a theme, its primary environment, JupyterLab 3, reached its end-of-maintenance on May 15, 2024, with critical fixes only until December 31, 2024. Users are strongly encouraged to upgrade to JupyterLab 4 for continued support and new features.
  Fix: Upgrade your JupyterLab installation to version 4.x or later. This theme should remain compatible across JupyterLab versions, but leveraging a current JupyterLab host is recommended.

Install

• pip install jupyterlab-pygments Install via pip
• conda install -c conda-forge jupyterlab_pygments Install via Conda

Imports

• jupyterlab_pygments

  import jupyterlab_pygments

  While you can import the package, its primary function is to register a Pygments style named 'jupyterlab'. You typically use this style by name with Pygments' formatters, rather than directly importing symbols from the package itself for style application.
• style='jupyterlab'

  from pygments.formatters import HtmlFormatter
  formatter = HtmlFormatter(style='jupyterlab')

  The 'jupyterlab' style is automatically registered by Pygments when the package is installed. Access it by name when creating a Pygments formatter.

Quickstart

This quickstart demonstrates how to use the `jupyterlab` Pygments style to highlight Python code and display it within a Jupyter environment. The `HtmlFormatter` is configured with `style='jupyterlab'` to apply the theme, and `full=True` to embed the necessary CSS.

from pygments import highlight
from pygments.lexers import PythonLexer
from pygments.formatters import HtmlFormatter
from IPython.display import HTML, display

# Example Python code to highlight
code_to_highlight = """
def greet(name):
    print(f"Hello, {name}!")

greet("World")
"""

# Create an HTML formatter using the 'jupyterlab' style
# The style 'jupyterlab' is made available by the jupyterlab-pygments package
formatter = HtmlFormatter(style='jupyterlab', full=True, cssclass='highlight-jupyterlab')

# Generate the HTML output with highlighting
highlighted_html = highlight(code_to_highlight, PythonLexer(), formatter)

# To display in a Jupyter environment, use IPython.display
# For standalone use, you would typically write highlighted_html to a file.
# The 'full=True' option includes the <style> tags, making it self-contained.
display(HTML(highlighted_html))