pygments 2.20.0: highlight python code to html with pygments

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: highlight python code to html with pygments
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:pypi/pygments@2.20.0
Demonstrate these symbols/APIs:
  - pygments.formatters.HtmlFormatter
  - pygments.highlight
  - pygments.lexers.get_lexer_by_name

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:8b007acc95bf4cb7c2c440148dc8a73c920a0e1ec61b74d6480f31b899a2d738","contract":["get_lexer_by_name retrieves the PythonLexer instance for 'python' and raises ClassNotFound when an unrecognized language alias is provided","pygments.highlight with HtmlFormatter(nowrap=True) highlights tokens into HTML span tags without surrounding container pre or div tags","HtmlFormatter with full=True wraps highlighted code into a standalone HTML document with doctype and title metadata","HtmlFormatter.get_style_defs generates CSS style rules corresponding to token classes for the target CSS selector"],"goal":"highlight python code to html with pygments","kind":"HOW","packages":["pkg:pypi/pygments@2.20.0"],"schemaVersion":1,"symbols":["pygments.formatters.HtmlFormatter","pygments.highlight","pygments.lexers.get_lexer_by_name"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"pypi","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"pip","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/pygments@2.20.0"],"schemaVersion":1,"subject":"pkg:pypi/pygments@2.20.0","symbols":["pygments.formatters.HtmlFormatter","pygments.highlight","pygments.lexers.get_lexer_by_name"],"verifierAdapter":"python@1"}

pygments==2.20.0

"""Sample demonstrating syntax highlighting of Python code to HTML using pygments."""

from typing import Tuple
from pygments import highlight
from pygments.formatters import HtmlFormatter
from pygments.lexers import get_lexer_by_name
from pygments.util import ClassNotFound


def highlight_snippet(code: str, language: str = "python") -> str:
    """Highlight a code snippet as an inline HTML fragment without wrapping tags."""
    lexer = get_lexer_by_name(language)
    formatter = HtmlFormatter(nowrap=True)
    return highlight(code, lexer, formatter)


def highlight_document(code: str, language: str = "python", title: str = "Source Code") -> Tuple[str, str]:
    """Highlight code into a standalone HTML document along with its CSS styles."""
    lexer = get_lexer_by_name(language)
    formatter = HtmlFormatter(full=True, title=title)
    html_doc = highlight(code, lexer, formatter)
    css_styles = formatter.get_style_defs(".highlight")
    return html_doc, css_styles


def demonstrate_pygments_highlighting() -> None:
    """Demonstrate core Pygments highlighting APIs."""
    sample_code = 'def greet(name: str) -> str:\n    return f"Hello, {name}!"\n'

    # 1. Inline snippet highlighting
    snippet = highlight_snippet(sample_code, "python")
    assert '<span class="k">def</span>' in snippet

    # 2. Standalone HTML document and stylesheet generation
    doc, css = highlight_document(sample_code, "python", title="Greeting Function")
    assert "<!DOCTYPE html" in doc
    assert "<title>Greeting Function</title>" in doc
    assert ".highlight" in css

    # 3. Handling invalid lexer names
    try:
        get_lexer_by_name("unsupported_lang_xyz")
    except ClassNotFound:
        pass


if __name__ == "__main__":
    demonstrate_pygments_highlighting()
    print("Pygments syntax highlighting demonstrations completed successfully.")

{
  "schemaVersion": 1,
  "goal": "highlight python code to html with pygments",
  "kind": "HOW",
  "packages": [
    "pkg:pypi/pygments@2.20.0"
  ],
  "symbols": [
    "pygments.formatters.HtmlFormatter",
    "pygments.highlight",
    "pygments.lexers.get_lexer_by_name"
  ]
}

import os
import sys

# Ensure project root is on sys.path for local module imports
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

from pygments import highlight
from pygments.formatters import HtmlFormatter
from pygments.lexers import get_lexer_by_name
from pygments.util import ClassNotFound

from sample import highlight_document, highlight_snippet


def test_get_lexer_by_name():
    # Assertion 1: get_lexer_by_name retrieves the PythonLexer instance for 'python' and raises ClassNotFound when an unrecognized language alias is provided
    lexer = get_lexer_by_name("python")
    assert lexer.name == "Python"
    assert lexer.aliases[0] == "python"

    try:
        get_lexer_by_name("invalid_lexer_alias_that_does_not_exist")
        assert False, "Expected ClassNotFound exception"
    except ClassNotFound as exc:
        assert "no lexer for alias" in str(exc)


def test_highlight_nowrap_snippet():
    # Assertion 2: pygments.highlight with HtmlFormatter(nowrap=True) highlights tokens into HTML span tags without surrounding container pre or div tags
    code = 'def add(a: int, b: int) -> int:\n    return a + b\n'
    lexer = get_lexer_by_name("python")
    formatter = HtmlFormatter(nowrap=True)
    html_output = highlight(code, lexer, formatter)

    assert '<span class="k">def</span>' in html_output
    assert '<span class="nf">add</span>' in html_output
    assert '<div class="highlight">' not in html_output
    assert '<pre>' not in html_output

    # Verify through sample module helper
    snippet = highlight_snippet(code, "python")
    assert snippet == html_output


def test_highlight_full_document():
    # Assertion 3: HtmlFormatter with full=True wraps highlighted code into a standalone HTML document with doctype and title metadata
    code = 'message = "Hello, world!"\n'
    doc, _ = highlight_document(code, "python", title="Test Page")

    assert "<!DOCTYPE html" in doc
    assert "<html" in doc
    assert "<title>Test Page</title>" in doc
    assert '<div class="highlight">' in doc
    assert '<pre>' in doc
    assert "</html>" in doc


def test_formatter_style_defs():
    # Assertion 4: HtmlFormatter.get_style_defs generates CSS style rules corresponding to token classes for the target CSS selector
    formatter = HtmlFormatter()
    css = formatter.get_style_defs(".highlight")

    assert ".highlight" in css
    assert ".highlight .k {" in css or ".highlight .k" in css
    assert "background:" in css or "color:" in css


def main():
    test_get_lexer_by_name()
    test_highlight_nowrap_snippet()
    test_highlight_full_document()
    test_formatter_style_defs()
    print("Contract verification passed.")


if __name__ == "__main__":
    main()